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
1
2
3
Step 2: Choose database engine
1
2
Step 3: Configure your database cluster
1
2
3
Step 4: Create the database cluster
1
2
3
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
1
2
Step 2: Log in or sign up
1
2
Step 3: Create a database
1
2
3
What happens during creation
When you create a Postgres database cluster, PlanetScale automatically:
- Provisions a PostgreSQL cluster in your selected region
- Creates the initial
mainbranch - 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.
Dashboard
CLI
1
2
3
4
5
6
Create a new “Default role” in your PlanetScale CLI to create connection credentials for your database branch.
1
2
Connection strings
PlanetScale provides connection strings in various formats for different frameworks and languages. Here are some common examples:
Default databases
When your database branch is first created, there are a number of default databases that are created at the same time.
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 - Use
sslmode=verify-full(recommended, withsslrootcert=system);sslmode=requireis the weaker minimum - 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
Your database is ready. See Next steps for the top platform features to enable before going to production.
Need help?
Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.