Skip to main content

Database

Most Serverpod apps need to persist data (user accounts, orders, session state). Serverpod Cloud can provision and run a managed PostgreSQL database alongside your project, so you don't have to set up or maintain Postgres yourself. When the database is enabled, Cloud handles provisioning, connection details for your server, migrations on every deploy, and backups. Direct access from tools like psql or a GUI client is opt-in and requires a database user that you create yourself.

The managed database runs on PostgreSQL 17 with TLS required, connection pooling on by default, and autoscaling compute.

Enable the database​

The database is opt-in. You choose whether to enable it when you create the project, in one of two ways:

  • With serverpod cloud launch. It checks your server config for a database section and presets the database switch on the Console's New project page. You can change it there before you create the project.
  • With serverpod cloud project create. Pass --enable-db, or --no-enable-db if your project doesn't use a database. The flag is required: it has no default, so you must pass one.

Once a project is created with the database enabled, the database is provisioned automatically and made available to your server on the next deploy.

How your server connects​

When the database is enabled, your deployed Serverpod server receives its connection details as environment variables, injected by Cloud:

VariableWhat it holds
SERVERPOD_DATABASE_HOSTThe database host
SERVERPOD_DATABASE_PORTThe port (5432 by default)
SERVERPOD_DATABASE_NAMEThe database name
SERVERPOD_DATABASE_USERThe server's database user
SERVERPOD_DATABASE_REQUIRE_SSLAlways true; TLS is required
SERVERPOD_PASSWORD_databaseThe server's database password

Your server reads these through Serverpod's standard configuration. You don't write them into config/production.yaml or passwords.yaml; Cloud supplies them at runtime. The server's password is managed by the platform and never exposed to you.

Migrations run on every deploy​

Cloud applies pending migrations from your project's migrations/ directory when it deploys your server.

If a migration fails to apply, the server logs Failed to apply database migrations. Check the server logs with serverpod cloud log, then fix the migration in your project and redeploy. For a step-by-step walkthrough, see Recover from a failed deploy.

To undo a migration that already applied, create a forward migration that reverses it. Revert the model change, run serverpod create-migration, and redeploy. If the command stops because data would be lost, add --force. The forward migration changes the schema only. It does not restore data.

Backups​

Cloud can back up the managed database on demand or on a schedule, and restore it to any snapshot in one step. See Database backups for how to set up scheduled backups, take manual snapshots, and restore.

Access the database directly​

You can connect to the managed database from your machine, a GUI client, or psql for inspection and debugging. This is independent of how your server connects.

The steps:

  1. Run serverpod cloud db connection to print the host, port, and database name.
  2. Run serverpod cloud db user create <username> to create a superuser. The password is shown once, so save it.
  3. Connect from your client with the host, port, database, your username, and the saved password.

Both commands need to know which project you're working with. From a project directory that's been linked (any project created with serverpod cloud launch is linked automatically), the project ID is picked up from scloud.yaml. From anywhere else, pass -p your-project-id.

If you lose the password, run serverpod cloud db user reset-password <username> to reset it. The new password is also shown only once.

Any PostgreSQL-compatible client works. A few popular options:

  • Postico, a focused PostgreSQL client for macOS
  • pgAdmin, the official open-source admin tool
  • DBeaver, cross-platform and free for personal use
  • DataGrip, JetBrains' database IDE
  • psql, the standard PostgreSQL command-line client
  • A PostgreSQL VS Code extension if you prefer to stay in your editor

Reset the database​

The serverpod cloud db wipe command deletes all tables, all data, and all applied migrations from the managed database. It asks for confirmation by default.

serverpod cloud db wipe

After a wipe, your server will error on its next request because the schema is gone. Redeploy with serverpod cloud deploy to reapply migrations and bring the database back into a working state.

Use this when you want to start clean during development. Do not wipe a production database.

Security​

The managed database is built so you don't have to think about credentials in your code or your repo:

  • TLS is required for all connections. Cloud sets SERVERPOD_DATABASE_REQUIRE_SSL to true for your server, and the same applies to direct connections from psql or a GUI client.
  • The server's password is managed by the platform. It's never written into your repo and never shown to you. Your server reads it from the injected environment at runtime.
  • Direct access uses separate superusers that you create. The server's user and the users you create with serverpod cloud db user create are distinct, so revoking or rotating a direct-access password does not affect the server.

Performance​

The managed database includes infrastructure features you'd otherwise wire up yourself:

  • Connection pooling is on by default. The connection details returned by serverpod cloud db connection point at a pooled endpoint, so short-lived connections from many clients don't exhaust Postgres connection slots.
  • Compute autoscales. The database scales compute up and down within bounds set by your plan, so you don't need to provision for peak traffic up front.