PlanetScale Postgres quickstart

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

Create credentials and connect

In this section you’ll create the “Default role” in your PlanetScale dashboard to create connection credentials for your database branch.

The “Default role” is meant purely for administrative purposes. You can only create one and it has significant privileges for your database cluster and you should treat these credentials carefully. After completing this quickstart, it is strongly recommended that you create another role for your application use-cases.

Dashboard
CLI

Navigate to your database in the PlanetScale dashboard

Click on the “Connect” button in the top right

Select “Default role”

Click “Create default role”. A new default role is created for your database branch.

Record the “Host”, “Username”, and “Password” for the “Default role” someplace secure.

You can generate connection strings under “How are you connecting?” for major languages, frameworks, and tools.

Your connection details will include:

Host: the DNS name of your database endpoint
Username: automatically formatted for routing to the correct branch
Password: A securely generated password
Database: postgres (default database)
Port: 5432 (standard PostgreSQL port) or 6432 (for using PgBouncer)

Create a new “Default role” in your PlanetScale CLI to create connection credentials for your database branch.

Run the following command to create the “Default role” for your database branch.

pscale role reset-default <DATABASE_NAME> <BRANCH_NAME>

Record the “Host”, “Username”, and “Password” for the “Default role” somewhere secure.

Passwords are shown only once. If you lose your record of the password, you must reset the password.

Connection strings

PlanetScale provides connection strings in various formats for different frameworks and languages. Here are some common examples:

General PostgreSQL URL

postgresql://postgres.{branch-id}:{password}@{host}.horizon.psdb.cloud:5432/postgres?sslmode=require

psql command line

terminal

psql 'host={host} port=5432 user={user} password={password} dbname=postgres sslnegotiation=direct sslmode=verify-full sslrootcert=system'

Node.js (node-postgres)

db.ts

const { Client } = require('pg');
const client = new Client({
  host: '{host}',
  port: 5432,
  user: '{user}',
  password: '{your-password}',
  database: 'postgres',
  ssl: { rejectUnauthorized: true }
});

Rails

planetscale:
  username: {user}
  host: {host}
  port: 5432
  database: postgres
  password: {your-password}

Default databases

When your database branch is first created, there are a number of default databases that are created at the same time.

postgres=> \l
                    List of databases
      Name       |      Owner       | Removed columns...
------------------+------------------+-------------------
 postgres         | postgres         | ...
 pscale_admin     | pscale_admin     | ...
 pscale_exporter  | pscale_admin     | ...
 pscale_pgbouncer | pscale_admin     | ...
 template0        | pscale_admin     | ...
 template1        | pscale_superuser | ...
(6 rows)

These databases include those that are used by various PlanetScale platform features such as metrics and logs collection, backups, Insights, or are used by PGBouncer (as examples). They cannot be removed.

Database	Purpose
postgres	Default user database
pscale_admin	PlanetScale platform
pscale_exporter	PlanetScale platform
pscale_pgbouncer	PlanetScale platform
`template0` and `template1`	Postgres database defaults

Security requirements

All connections to Postgres databases require:

SSL/TLS encryption - Always use sslmode=require or equivalent
Certificate verification - Connections verify PlanetScale’s SSL certificates
Secure passwords - Generated passwords use cryptographically secure random generation

Password management

Password reset: You can reset your default user password anytime from the dashboard
No password rotation required: Passwords don’t expire unless you set them to
Single credential per branch: Each branch has one default user credential

Next steps

Once your database is created, you can:

Create additional branches for development and testing
Connect your applications using the connection credentials above
Monitor performance and usage through the dashboard
Scale your cluster as your needs grow
Create additional PostgreSQL roles within your database using SQL
Enable pg_strict to prevent accidental dangerous queries from running

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 quickstart

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

Create credentials and connect

Connection strings

Default databases

Security requirements

Password management

Next steps

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

​Create credentials and connect

​Connection strings

​Default databases

​Security requirements

​Password management

​Next steps

​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

Create credentials and connect

Connection strings

Default databases

Security requirements

Password management

Next steps

Need help?