Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Databases

A Database is a managed resource that lives inside an Environment, next to the apps that use it. The platform provisions it, keeps it running, and generates its credentials for you — you never install or operate the database engine yourself.

Four engines are available:

EngineTypical use
PostgreSQLRelational data (general default)
RedisCaching, queues, ephemeral data
MongoDBDocument data
MariaDBRelational data

Creating a database requires database-management permission in the project — see Access Control.

Create a database in the dashboard

  1. Open the Environment (for example acme › shop › production) and click Add Resource.
  2. Choose the Database resource type.
  3. Give it a name, such as shop-db. Names use lowercase letters, numbers, and hyphens, and must be unique within the Environment.
  4. Under Database Configuration, pick the Database Type: PostgreSQL, Redis, MariaDB, or MongoDB. Choosing PostgreSQL shows a High availability checkbox — see High availability.
  5. Set Size (GB): the size of its storage, 1 GB unless you change it. It can’t be changed after the database is created.
  6. Click Create Resource.

The dashboard creates the database with the platform’s default version. To choose the version yourself, use the CLI.

Create a database with the CLI

paas dbs create shop-db --type postgresql --storage-gb 20 \
  -o acme -p shop -e production

Created database shop-db

Flags:

  • --type (required): postgresql, redis, mongodb, or mariadb.
  • --storage-gb: size of the database’s storage volume in GB. If omitted, the database gets 1 GB. The size is fixed once the database is created.
  • --version: engine version. Currently honored for MongoDB; PostgreSQL, Redis, and MariaDB run the platform’s standard version regardless of this flag.
  • --ha: turn on high availability. PostgreSQL only.

When you run the CLI inside a repository that has a d2o (or paas) git remote, the organization, project, and environment are inferred and you can drop the -o/-p/-e flags. By default a database runs as a single instance; PostgreSQL databases can opt into high availability — see below.

Size, CPU and memory

Every database counts against your plan’s capacity pools for its environment type, like an app — see Plans, Limits & Usage:

  • Storage: the size you choose, or 1 GB when you don’t. It can’t be changed after creation, so pick a size with room to grow.
  • CPU and memory: each database runs with up to 500m CPU (half a core) and 512 MiB of memory, and counts that much against your plan’s CPU and memory pools.

A database with high availability counts all three twice. A create that doesn’t fit your plan is rejected with the usual LIMIT_EXCEEDED error. The database’s Settings page shows its size, CPU and memory.

Status lifecycle

A database moves through these statuses:

  • pending — just created; its configuration is being written.
  • provisioning — the engine is being set up and is not yet ready to accept connections.
  • running — the database is ready. The platform re-checks readiness continuously, so a database that becomes unhealthy drops back to provisioning until it recovers.
  • deleting — being torn down.

Check status from the CLI:

paas dbs list -o acme -p shop -e production

NAME     ENGINE      VERSION  STATUS
shop-db  postgresql  -        running

paas dbs info <name> shows one database in detail:

$ paas dbs info shop-db
shop-db (7c9e6679-7425-40de-963d-a1b2c3d4e5f6)
type: database
status: running
engine: postgresql
version: -
storage: 20 GB
created: 2026-08-31 14:02:11.482193 UTC
high availability: on

The high availability line only appears for PostgreSQL databases.

Add --json to either command for the raw API response.

High availability

PostgreSQL databases can opt into high availability. Off by default, it runs a second, continuously synchronized copy of your database on a different server. If the server running your database fails, the copy takes over automatically within seconds — connections drop briefly and reconnect, which most database drivers and connection pools already handle on their own. While the copy is healthy, writes wait for it to confirm before returning; if the copy is temporarily unavailable, your database keeps accepting writes on its own rather than blocking. Planned maintenance on our side no longer interrupts an HA database beyond a brief switchover.

Turn it on when creating a database — the dashboard’s High availability checkbox, or --ha on the CLI:

paas dbs create shop-db --type postgresql --storage-gb 20 --ha \
  -o acme -p shop -e production

You can also turn it on or off for a database you already have, with no change to its connection string or attachments:

  • Dashboard: open the database’s Settings page and use the High availability toggle.

  • CLI:

    paas dbs update shop-db -o acme -p shop -e production --ha true

Enabling it on an existing database copies the data to the new standby in the background with no downtime; how long that takes depends on the database’s size. Disabling it removes the standby copy; the primary keeps running unaffected.

The database’s Overview page in the dashboard shows High availability: On or Off, and paas dbs info shows the same as high availability: on or off.

Cost: a high-availability database counts twice against your plan’s CPU, memory, and storage pools, since it runs two full copies. A create or update that would exceed your plan’s limits is rejected with the usual LIMIT_EXCEEDED error — see Plans, Limits & Usage.

High availability is available for PostgreSQL only; Redis, MongoDB, and MariaDB databases always run as a single instance for now.

Credentials and connecting

You never copy passwords out of the dashboard. To use a database from an app, you attach it: the platform injects a ready-made connection-string environment variable (by default DATABASE_URL) into the app. See Attaching a Database.

Backups

PostgreSQL and MariaDB databases are backed up automatically. Restoring from a backup requires contacting support. Redis and MongoDB are not backed up — treat Redis as ephemeral, and export MongoDB data yourself if you need copies. See Database Backups.

Delete a database

Deleting a database destroys its data permanently: the database stops, its storage is removed, and its backups are deleted within about an hour. There is no undo. In the CLI:

paas dbs delete shop-db -o acme -p shop -e production

Type "shop-db" to confirm deletion: shop-db
Deleted database shop-db

In scripts, skip the prompt by passing the name back explicitly. Without a matching --confirm, a non-interactive session refuses to delete:

paas dbs delete shop-db -o acme -p shop -e production --confirm shop-db

If you create a new PostgreSQL database with the name of one you just deleted in the same environment before its backups are gone, creation is refused with BACKUPS_PENDING_REMOVAL — wait a little and try again, or pick another name.

Next steps