PlanetScale Pulumi Tutorial

Companion code for the Automate logical databases with distinct roles in Postgres blog post.

This Pulumi program demonstrates how to automate the setup of isolated logical PostgreSQL databases on a PlanetScale Postgres cluster. It creates multiple databases (e.g. blog, todo), each with a dedicated application role that can only connect to its own database, enforcing strict tenant isolation at the Postgres level.

What it does

1. Creates a bootstrap role with postgres-inherited privileges for Pulumi to manage resources.
2. Creates logical databases (blog, todo) on the PlanetScale Postgres branch.
3. Revokes CONNECT from PUBLIC on all databases so new roles have no access by default.
4. Creates per-application roles (blog_app, todo_app) via PlanetScale with read/write privileges.
5. Grants each app role CONNECT and CREATE only on its designated database.
6. Explicitly revokes each app role from the postgres database and from peer databases.
7. Exports direct (port 5432) and pooled (port 6432) connection URLs for each application.

Prerequisites

• Node.js (v18+)
• pnpm
• Pulumi CLI
• A PlanetScale account with a Postgres database cluster
• A PlanetScale service token with permissions to manage branches and roles

Setup

1. Clone and install dependencies

git clone https://github.com/planetscale/tutorial-pulumi.git
cd tutorial-pulumi
pnpm install

2. Add the PlanetScale Pulumi provider

Generate the PlanetScale provider SDK locally. This creates the sdks/planetscale/ directory.

pulumi package add terraform-provider planetscale/planetscale

3. Initialize a Pulumi stack

pulumi stack init dev

4. Configure the stack

Set the configuration values for your PlanetScale organization and cluster. You will need a service token.

pulumi config set organization "<organization-name>"
pulumi config set clusterName "<database-cluster-name>"
pulumi config set branch "main"
pulumi config set importBranch true
pulumi config set --secret planetScaleServiceToken "pscale_tkn_..."
pulumi config set --plaintext planetScaleServiceTokenId "p..."

Config key	Description
organization	Your PlanetScale organization slug
clusterName	The name of your PlanetScale Postgres database cluster
branch	The Postgres branch to target (default: main)
importBranch	Set to true to use an existing branch, false to create one
planetScaleServiceToken	PlanetScale service token (stored as a Pulumi secret)
planetScaleServiceTokenId	The ID of the service token
clusterSize	Required only when importBranch is false (e.g. PS_10_AWS_ARM)

5. Deploy

pulumi up

After deployment, Pulumi will output connection URLs for each application database.

Customizing

To add or remove application databases, edit the appDatabases array in lib/services.ts:

export const appDatabases: string[] = ["blog", "todo"];

Each entry creates a logical database and a corresponding <name>_app role.

Contributing

This repository is published as companion code for a tutorial blog post. It is not actively accepting contributions, but you are welcome to open an issue if you have a question or find a problem.

License

This project is licensed under the Apache License 2.0.