> ## Documentation Index
> Fetch the complete documentation index at: https://planetscale.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# PlanetScale Postgres with Cloudflare Workers
> Create a new Postgres database and integrate it with Cloudflare Workers and Hyperdrive.
export const YouTubeEmbed = ({id, title}) => {
return
;
};
[Cloudflare Workers](https://developers.cloudflare.com/workers/) is a serverless platform that allows you to run your code at the edge, close to your users. [Hyperdrive](https://developers.cloudflare.com/hyperdrive/) accelerates queries you make to existing databases.
Already created a PlanetScale Postgres database? [Jump straight to integration instructions](#integrate-with-cloudflare-workers).
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](https://auth.planetscale.com/sign-up). 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](/postgres/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](/postgres/postgres-architecture/#cluster-design).
## Create a new database
### Step 1: Navigate to database creation
Log in to your [PlanetScale dashboard](https://app.planetscale.com)
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](/postgres/cluster-configuration/cpu-architectures)
### 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:
```bash theme={null}
pscale --version
```
Alternatively, follow the instructions in the [PlanetScale CLI GitHub repository](https://github.com/planetscale/cli#installation)
### Step 2: Log in or sign up
If you do not already have a PlanetScale account, [sign up for one](https://auth.planetscale.com/sign-up) by running:
```bash theme={null}
pscale signup
```
Log in to the PlanetScale CLI by running:
```bash theme={null}
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:
```bash theme={null}
pscale org list
```
Switch organizations by running:
```bash theme={null}
pscale org switch
```
Find the **region** closest to your application's hosting.
List available regions by running:
```bash theme={null}
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:
```bash theme={null}
pscale database create --region --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](https://developers.cloudflare.com/workers/get-started/quickstarts/#postgres-hyperdrive-template).
```bash Terminal theme={null}
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.
Log into the Cloudflare dashboard and navigate to **"Compute & AI"** > **"Workers & Pages"**. You should see your Worker in the list.
Select the **"Storage & databases"** tab, then **"Hyperdrive"**, and finally **"Create configuration"** in the top right corner.
Click **"Connect to PlanetScale database"** then click **Next**.
Click **Login to PlanetScale** to log in to your PlanetScale account.
The next screen will allow you to grant access to your organization, database, and branch. Start by selecting your organization from the list.
Select the database you created, the "main" branch and then click **Next**.
You must include a **database name**. For MySQL/Vitess databases, the default database name is the same as your project name (for example, `my-project`). For Postgres databases, the default database name is `postgres`.
You should see a success screen with the connection binding details to add to your `wrangler.json` file.
You should now have metrics within your Cloudflare dashboard in the Hyperdrive page.
Create a Hyperdrive connection by running the `wrangler` command below:
* Replace the `--connection-string` placeholders with your database credentials
* Replace the `` placeholder with a name for your Hyperdrive connection
**For MySQL/Vitess databases:**
```bash Terminal theme={null}
npx wrangler hyperdrive create --connection-string="mysql://:@/"
```
**For Postgres databases:**
```bash Terminal theme={null}
npx wrangler hyperdrive create --connection-string="postgresql://:@:/?sslmode=verify-full"
```
If successful, the command will output your new Hyperdrive configuration, for example:
```json Terminal theme={null}
{
"hyperdrive": [
{
"binding": "HYPERDRIVE",
"id": ""
}
]
}
```
### 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](https://developers.cloudflare.com/workers/configuration/smart-placement/) 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:
```json wrangler.json theme={null}
{
"placement": {
"region": "aws:us-east-1"
}
}
```
| 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 europe-west4 (Netherlands) | `gcp:europe-west4` |
| GCP northamerica-northeast1 (Montreal) | `gcp:northamerica-northeast1` |
| GCP us-central1 (Iowa) | `gcp:us-central1` |
| GCP us-east1 (South Carolina) | `gcp:us-east1` |
| 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:
```json wrangler.json theme={null}
{
"placement": {
"mode": "smart"
}
}
```
### Step 2: Deploy your Worker
Run the following to deploy your Worker.
```bash Terminal theme={null}
npx wrangler deploy
```
For more information on using Cloudflare Workers and Hyperdrive, [refer to the Cloudflare documentation](https://developers.cloudflare.com/hyperdrive/).
## What's next?
Once you're done with development, consider these next steps:
* **Create additional roles**: Set up [application-specific roles](/postgres/connecting/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](/postgres/branching) to safely test schema changes before deploying to production.
* **Set up monitoring**: Configure [query insights](/postgres/monitoring/query-insights) to monitor database performance and identify slow queries.
## Need help?
Get help from [the PlanetScale Support team](https://planetscale.com/contact?initial=support), or join our [Discord community](https://pscale.link/community) to see how others are using PlanetScale.