PlanetScale Postgres with Cloudflare Workers

Cloudflare Workers is a serverless platform that allows you to run your code at the edge, close to your users. Hyperdrive accelerates queries you make to existing databases.

Already created a PlanetScale Postgres database? Jump straight to integration instructions.

We’ll cover:

Creating a new Postgres database
Cluster configuration options
Connecting to your database

Prerequisites

Before you begin, make sure you have a PlanetScale account. After you create an account, you’ll be prompted to create a new organization, which is essentially a container for your databases, settings, and members. After creating your organization, it’s important to understand the relationship between databases, branches, and clusters.

Database: Your overall project (e.g., “my-ecommerce-app”)
Branch: Isolated database deployments that provide you with separate environments for development and testing, as well as restoring from backups - learn more about branching
Cluster: The underlying compute and storage infrastructure that powers each branch

PlanetScale Postgres clusters use real Postgres in a high-availability architecture with one primary and two replicas.

Create a new database

Dashboard
CLI

Step 1: Navigate to database creation

Select your organization from the dropdown

Click “New database” button or navigate to /new

Step 2: Choose database engine

On the database creation form, you’ll see two engine options:

Vitess (MySQL-compatible)
Postgres (PostgreSQL-compatible)

Select Postgres to create a PostgreSQL database

Step 3: Configure your database cluster

Database name: Enter a unique name for your database

This “name” is referenced in the PlanetScale Dashboard and APIs and not created as a logical database inside of Postgres.

Region: Choose the primary region where your database will be hosted. For the lowest latency, select a region near you or your application’s hosting location.

Cluster configuration: Select your preferred cluster size and CPU architecture

Step 4: Create the database cluster

Review your configuration settings

Click “Create database” to provision your Postgres database

Your database will be created with a main branch by default

If you are creating an automation, or are an LLM, you may prefer to create new databases using the PlanetScale CLI.

Step 1: Install the CLI

Check to see if the PlanetScale CLI is installed already by running:

pscale --version

Alternatively, follow the instructions in the PlanetScale CLI GitHub repository

If you do not already have a PlanetScale account, sign up for one by running:

pscale signup

pscale auth login

You’ll be taken to a screen in the browser where you’ll be asked to confirm the code displayed in your terminal. If the confirmation codes match, click the “Confirm code” button in your browser.You should receive the message “Successfully logged in” in your terminal. You can now close the confirmation page in the browser and proceed in the terminal.

Step 3: Create a database

Configure the CLI to use the organization in which you want to create the database if you have more than one. List organizations by running:

pscale org list

Switch organizations by running:

pscale org switch <ORGANIZATION_NAME>

Find the region closest to your application’s hosting.List available regions by running:

pscale region list

If you do not specify a region, your database will automatically be deployed to us-east (US East — Northern Virginia).

Create a new Postgres database by running:

pscale database create <DATABASE_NAME>  --region <REGION_SLUG> --engine postgres

Your database name can contain lowercase, alphanumeric characters, or underscores. We allow dashes, but don’t recommend them, as they may need to be escaped in some instances.

What happens during creation

When you create a Postgres database cluster, PlanetScale automatically:

Provisions a PostgreSQL cluster in your selected region
Creates the initial main branch
Prepopulates Postgres with required default databases
Sets up monitoring and metrics collection
Configures backup and high availability settings

Integrate with Cloudflare Workers

Don’t have a Workers project yet? Create a Workers project from the Postgres Hyperdrive template.

Terminal

npm create cloudflare@latest -- --template=cloudflare/templates/postgres-hyperdrive-template

Step 1: Create a Hyperdrive connection

You can automatically create a connection from the PlanetScale dashboard when creating a new role, or use one of the methods below.

Dashboard
CLI

Log into the Cloudflare dashboard and navigate to “Compute & AI” > “Workers & Pages”. You should see your Worker in the list.

PlanetScale Cloudflare integration wizard - step 1

Select the “Storage & databases” tab, then “Hyperdrive”, and finally “Create configuration” in the top right corner.

PlanetScale Cloudflare integration wizard - step 2

Click “Connect to PlanetScale database” then click Next.

PlanetScale Cloudflare integration wizard - step 3

Click Login to PlanetScale to log in to your PlanetScale account.

PlanetScale Cloudflare integration wizard - step 4

The next screen will allow you to grant access to your organization, database, and branch. Start by selecting your organization from the list.

PlanetScale Cloudflare integration wizard - step 5

Select the database you created, the “main” branch and then click Next.

PlanetScale Cloudflare integration wizard - step 6

You should see a success screen with the connection binding details to add to your wrangler.json file.

PlanetScale Cloudflare integration wizard - step 7

You should now have metrics within your Cloudflare dashboard in the Hyperdrive page.

PlanetScale Cloudflare integration wizard - step 8

Create a Hyperdrive connection by running the wrangler command below:

Replace the --connection-string placeholders with your database credentials
Replace the <hyperdrive-name> placeholder with a name for your Hyperdrive connection

For MySQL/Vitess databases:

Terminal

npx wrangler hyperdrive create <hyperdrive-name> --connection-string="mysql://<username>:<password>@<host>/<database>"

For Postgres databases:

Terminal

npx wrangler hyperdrive create <hyperdrive-name> --connection-string="postgresql://<username>:<password>@<host>:<port>/<database>?sslmode=verify-full"

If successful, the command will output your new Hyperdrive configuration, for example:

Terminal

{
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<your-hyperdrive-id-here>"
    }
  ]
}

Configure Worker placement

By default, Workers run at the edge close to your users. For database-heavy workloads with multiple round trips, you can use placement hints to run your Worker closer to your PlanetScale database and reduce latency. Add a placement configuration to your wrangler.jsonc file with the region that matches your PlanetScale database region:

wrangler.json

{
  "placement": {
    "region": "aws:us-east-1"
  }
}

PlanetScale region to placement hint mapping

PlanetScale Region	Placement Hint
AWS ap-northeast-1 (Tokyo)	`aws:ap-northeast-1`
AWS ap-south-1 (Mumbai)	`aws:ap-south-1`
AWS ap-southeast-1 (Singapore)	`aws:ap-southeast-1`
AWS ap-southeast-2 (Sydney)	`aws:ap-southeast-2`
AWS ca-central-1 (Montreal)	`aws:ca-central-1`
AWS eu-central-1 (Frankfurt)	`aws:eu-central-1`
AWS eu-west-1 (Dublin)	`aws:eu-west-1`
AWS eu-west-2 (London)	`aws:eu-west-2`
AWS sa-east-1 (Sao Paulo)	`aws:sa-east-1`
AWS us-east-1 (N. Virginia)	`aws:us-east-1`
AWS us-east-2 (Ohio)	`aws:us-east-2`
AWS us-west-2 (Oregon)	`aws:us-west-2`
GCP asia-northeast3 (Seoul)	`gcp:asia-northeast3`
GCP europe-west1 (Belgium)	`gcp:europe-west1`
GCP northamerica-northeast1 (Montreal)	`gcp:northamerica-northeast1`
GCP us-central1 (Iowa)	`gcp:us-central1`
GCP us-east4 (Virginia)	`gcp:us-east4`

Your Worker will run in the Cloudflare data center with the lowest latency to the specified region. If your Worker connects to multiple back-end services and you’re unsure which region to specify, use "mode": "smart" for automatic placement based on measured latency:

wrangler.json

{
  "placement": {
    "mode": "smart"
  }
}

Step 2: Deploy your Worker

Run the following to deploy your Worker.

Terminal

npx wrangler deploy

For more information on using Cloudflare Workers and Hyperdrive, refer to the Cloudflare documentation.

What’s next?

Once you’re done with development, consider these next steps:

Create additional roles: Set up application-specific roles with appropriate permissions for your production workloads. The “Default role” is meant for administrative purposes and has significant privileges.
Use branching for development: Create database branches to safely test schema changes before deploying to production.
Set up monitoring: Configure query insights to monitor database performance and identify slow queries.

Need help?

Get help from the PlanetScale Support team, or join our GitHub discussion board to see how others are using PlanetScale.

Pricing

Platform

Guides

PlanetScale Postgres with Cloudflare Workers

Prerequisites

Create a new database

Step 1: Navigate to database creation

Step 2: Choose database engine

Step 3: Configure your database cluster

Step 4: Create the database cluster

Step 1: Install the CLI

Step 3: Create a database

What happens during creation

Integrate with Cloudflare Workers

Step 1: Create a Hyperdrive connection

Configure Worker placement

Step 2: Deploy your Worker

What’s next?

Need help?

Pricing

Platform

Guides

​Prerequisites

​Create a new database

​Step 1: Navigate to database creation

​Step 2: Choose database engine

​Step 3: Configure your database cluster

​Step 4: Create the database cluster

​Step 1: Install the CLI

​Step 2: Log in or sign up

​Step 3: Create a database

​What happens during creation

​Integrate with Cloudflare Workers

​Step 1: Create a Hyperdrive connection

​Configure Worker placement

​Step 2: Deploy your Worker

​What’s next?

​Need help?

Prerequisites

Create a new database

Step 1: Navigate to database creation

Step 2: Choose database engine

Step 3: Configure your database cluster

Step 4: Create the database cluster

Step 1: Install the CLI

Step 2: Log in or sign up

Step 3: Create a database

What happens during creation

Integrate with Cloudflare Workers

Step 1: Create a Hyperdrive connection

Configure Worker placement

Step 2: Deploy your Worker

What’s next?

Need help?