PlanetScale for Postgres quickstart

July 8, 2025

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.

Creating a new Postgres database

PlanetScale for Postgres databases use our Postgres engine, which provides PostgreSQL compatibility with PlanetScale's scaling and branching capabilities.

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

1. Database name: Enter a unique name for your database
2. Region: Choose the primary region where your database will be hosted
3. Cluster configuration: Select your preferred cluster size and CPU architecture

Step 4: Create the database

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, PlanetScale automatically:

• Provisions a PostgreSQL cluster in your selected region
• Creates the initial main branch
• Sets up monitoring and metrics collection
• Configures backup and high availability settings
• Generates connection credentials

Database credentials and connection

Master user credentials

When you create a Postgres database, PlanetScale automatically creates a master user with the username postgres. This is the primary administrative user for your PostgreSQL database.

Important notes about database roles:

• PlanetScale only creates the master postgres user for you
• While PostgreSQL supports creating additional roles and users within your database, PlanetScale's managed service provides only the master user credentials
• You can create additional PostgreSQL roles inside your database using standard SQL commands, but connection credentials are managed only through the PlanetScale dashboard

Getting your connection credentials

To connect to your Postgres database:

1. Navigate to your database in the PlanetScale dashboard
2. Go to the "Connect" tab
3. Select your branch (usually main for new databases)
4. Click "Get connection string" or "New password"

Your connection details will include:

• Host: {your-database}.horizon.psdb.cloud
• Username: postgres.{branch-id} (automatically formatted for routing)
• Password: A securely generated password
• Database: Your database name
• Port: 5432 (standard PostgreSQL port)

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}@{database}.horizon.psdb.cloud:5432/{database-name}?sslmode=require

psql command line:

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

Node.js (node-postgres):

const { Client } = require('pg');
const client = new Client({
  host: '{database}.horizon.psdb.cloud',
  port: 5432,
  user: 'postgres.{branch-id}',
  password: '{your-password}',
  database: '{database-name}',
  ssl: { rejectUnauthorized: true }
});

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 master 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 master 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.