Database

dpl splits databases into two unit types:

• db-server runs the engine container.
• db creates one database and one login user inside a db-server.

This lets several apps use separate databases on one engine server.

DB Server

type: db-server
engine: postgresql
version: 18-alpine
secret: db-server-password

Fields:

Field	Required	Purpose
engine	Yes	postgresql, mariadb, or mysql.
version	No	Image tag for the default engine image.
image	No	Full image name. Overrides version.
secret	Yes	Secret that stores the root or superuser password.

Default images:

Engine	Default image
postgresql	docker.io/library/postgres:18-alpine
mariadb	docker.io/library/mariadb:12
mysql	docker.io/library/mysql:8.4

DB

type: db
server: db-main
user: app
secret: app-db-password

Fields:

Field	Required	Purpose
server	Yes	The db-server unit name.
user	Yes	Login user for this database.
secret	Yes	Secret that stores this user’s password.

The database name is the db unit name.

Values exported by a db unit

Use these values in app config:

runtime:
  env:
    DB_NAME: ${app-db:name}
    DB_USER: ${app-db:user}
    DB_PASSWORD: ${app-db:password}
    DB_HOST: ${app-db:host}
    DB_PORT: ${app-db:port}
    DB_URL: ${app-db:url}

Available keys:

Key	Value
name	Database name.
user	Database login user.
password	Decrypted user password.
host	The db-server container name (dpl--<server>). Apps reach it as a hostname on the dpl network.
port	Engine port, such as 5432 or 3306.
url	Connection URL. The password is percent-encoded, so the URL is safe to use as is.

Restore from a SQL dump

Create the server and database:

dpl deploy db-main
dpl deploy app-db

Restore when creating the database:

dpl deploy app-db ./backup.sql
dpl deploy app-db ./backup.sql.gz
gunzip -c backup.sql.gz | dpl deploy app-db -

dpl refuses to restore into an existing database. Drop or rename the database first.