PlanetScale for Postgres quickstart
(Updated )
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
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
- Log in to your PlanetScale dashboard
- 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.
Note
This name is referenced just 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
- 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
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:
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. Note that you can only ever have one of these for the database.
Warning
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.Record the
Host
,Username
, andPassword
for your Default role and keep them 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)
Warning
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.