PlanetScale for Postgres quickstart

This guide will walk you through how to create a new PlanetScale for Postgres database.

We’ll cover:

• Creating a new Postgres database
• Cluster configuration options
• Connecting to your database
• Monitoring 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 for Postgres clusters use real Postgres in a high-availability architecture with one primary and two replicas.

Creating a new database

Step 1: Navigate to database creation

1. Log in to your PlanetScale dashboard

2. Select your organization from the dropdown

3. Click “New database” button or navigate to /new

Step 2: Choose database engine

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

   • Vitess (MySQL-compatible)
   • Postgres (PostgreSQL-compatible)
2. Select Postgres to create a PostgreSQL database

Step 3: Configure your database cluster

1. Database name: Enter a unique name for your database

2. Region: Choose the primary region where your database will be hosted

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

3. Cluster configuration: Select your preferred cluster size and CPU architecture

Step 4: Create the database cluster

1. Review your configuration settings

2. Click “Create database” to provision your Postgres database

3. Your database will be created with a main branch by default

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

Database credentials and connection

Getting your connection credentials

To connect to your Postgres database:

1. Navigate to your database in the PlanetScale dashboard

2. Click on the “Connect” button in the top right

3. Select “Default role”

4. Click “Create default role”. A new default role is created for your database branch. Note that you can only ever have one of these for the database.

   The Default role is meant purely for administrative purposes. 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.

5. Record the Host, Username, and Password for your Default role and keep them someplace secure.

   
6. 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)

Passwords are shown only once, until you navigate away from this page. If you lose your record of this, you must reset the password.

Connection string format

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:

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

Node.js (node-postgres):

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

Rails (config/credentials.yml.enc):

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

Need help?

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