Databases

Declare a database in orch.pkl and orch runs it for you. It generates the credentials, gives your services a connection URL, and backs the data up when you ask it to.

amends "https://orch.torsten.work/pkl/v1/Application.pkl"

name = "shop"

services {
  ["web"] {
    image = "ghcr.io/acme/shop:1.4.2"
    http = new Http { port = 8080; domains { "shop.example.com" } }
    connect {
      ["DATABASE_URL"] = "main"
      ["REDIS_URL"] = "cache"
    }
  }
}

databases {
  ["main"] = new Postgres { version = "17" }
  ["cache"] = new Redis { version = "7.4" }
}

orch deploy starts both databases next to web. connect sets each variable to the database's connection URL and starts web after the database is ready. Nobody has to create a password.

connect works the same in cron jobs. Pkl checks every name against databases when it evaluates orch.pkl, so a typo such as "mian" fails with services["web"].connect["DATABASE_URL"]: no database is named "mian" in databases before anything is deployed. orch also rejects a variable that env or secretEnv already sets. The URL comes from the database's NAME-url secret (see Credentials), so secretEnv { ["DATABASE_URL"] = "main-url" } still works where you need it.

Engines

Class Image Default version Port
Postgres postgres 17 5432
MySQL mysql 8.4 3306
MariaDB mariadb 11.4 3306
MongoDB mongo 8.0 27017
Redis redis 7.4 6379
Valkey valkey/valkey 8.1 6379
Dragonfly docker.dragonflydb.io/dragonflydb/dragonfly latest 6379
Garnet ghcr.io/microsoft/garnet latest 6379
ClickHouse clickhouse/clickhouse-server 25.8 9000 (native), 8123 (HTTP)
LibSQL ghcr.io/tursodatabase/libsql-server latest 8080

Valkey, Dragonfly and Garnet speak the Redis protocol, so Redis clients work with them unchanged. Garnet's image runs as a user that cannot write to a local volume, so orch runs it without one: it starts empty after every restart and suits caches only.

Every engine accepts the same fields:

Field Type Default Rules
version String per engine, above Tag of the official image
image String? null Full image reference instead, for a mirror or a compatible build; version is then only shown, not used
resources Resources 100m CPU; 256Mi for Postgres and MariaDB, 512Mi for MySQL and MongoDB, 128Mi otherwise See Resources
constraints Mapping<String, String> empty Node labels the database's node must have
backup DatabaseBackup? null, no backups Set it to back the database up on a schedule

DatabaseBackup has schedule (five UTC cron fields, default "0 3 * * *") and keep (1 to 365, default 7).

Database names are DNS labels of at most 54 characters, so the names derived from them below stay valid.

What orch creates

A database named main in application shop becomes:

  • a service main, reachable at main.shop.svc.internal on the engine's port, with one replica and a one minute stop grace period;
  • a local volume main-data with its files (except for Garnet). The service gets CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_FOWNER, CAP_SETGID and CAP_SETUID, which the official image needs to hand that volume to its database user. They do not make the application administrator-only;
  • for the dump engines (Postgres, MySQL, MariaDB, MongoDB, ClickHouse) with backups on, a local volume main-backup that holds the latest dump;
  • the secrets below, created on the first deploy that declares the database.

The service and volumes are ordinary parts of the application. They show up in orch app status, orch app diff, orch logs shop main and orch volume list, and a service or volume of the same name is rejected. Changing a database's version or resources rolls it out like any other service: the old replica stops before the new one starts on the same node and volume.

Credentials

Engine Secrets URL format
Postgres main-password, main-url postgres://orch:[email protected]:5432/main
MySQL, MariaDB main-password, main-url mysql://orch:[email protected]:3306/main
MongoDB main-password, main-url mongodb://orch:[email protected]:27017/main?authSource=admin
Redis, Valkey, Dragonfly, Garnet main-password, main-url redis://:[email protected]:6379
ClickHouse main-password, main-url clickhouse://orch:[email protected]:9000/main
LibSQL main-jwt-key, main-token, main-url http://main.shop.svc.internal:8080?authToken=TOKEN

The user is orch and the database is named after the entry; ClickHouse turns dashes in that name into underscores. MySQL and MariaDB use the same password for root. LibSQL clients authenticate with main-token, a full-access token signed for the public key in main-jwt-key; pass the token separately if your client does not read authToken from the URL.

orch only creates a secret that does not exist yet and never changes one, so a database keeps the password it was initialized with. To choose your own password, set it with orch secret set shop main-password --from-stdin before the first deploy. The engines only read the password when they initialize an empty volume, so changing it later means changing it inside the database too.

Backups

Backups are off until you add a backup:

["main"] = new Postgres {
  backup = new DatabaseBackup {
    schedule = "0 */6 * * *"
    keep = 14
  }
}

They run on the database's node.

  • Dump engines write a fresh dump into the main-backup volume, then orch archives that volume. A dump is consistent even while the database takes writes.
  • Redis, Valkey and Dragonfly run SAVE, then orch archives the main-data volume.
  • LibSQL archives main-data; SQLite files are copied with SQLite's online backup.

A backup that fails is retried an hour later. See and take backups with:

orch db list
orch db backups shop main
orch db backup shop main

orch volume download shop main-backup BACKUP downloads an archive, which for a dump engine contains the dump (dump.pgc, dump.sql, dump.archive.gz, or ClickHouse's dump directory).

Restore

orch db restore shop main            # the newest backup (see below after a lost node)
orch db restore shop main 20261020T030000Z

For a dump engine, orch swaps the backup into main-backup, waits until the database accepts connections, and loads the dump into it: pg_restore --clean, the SQL dump (which drops and recreates the database), mongorestore --drop, or ClickHouse's RESTORE after dropping the database. For the Redis-compatible engines and LibSQL it swaps the backup into main-data and restarts the database on it; the data it replaced is kept as a -before-restore backup.

After a worker is lost and the database moved to another node, a restore without a name stops and names the newest backup from before and after the move, because the newest may hold the new node's empty database. Backups taken after you restore one by name are trusted again, so the next scheduled backup ends the question. A restore without a name also stops when the bucket's backups cannot be listed.

orch web shows the same on each database's own page, opened from its application's page. It lists the backups with their size, age, and whether they are on the node, in the bucket, or both, takes one with Back up now, and restores the one you pick, the same way as orch db restore with a name. The page also shows the database's live CPU and memory use.

Loading a dump is limited to five minutes. For a larger database, download the dump and load it yourself with orch exec.

Move

orch db move shop main worker-2

stops the database, copies its volumes to worker-2, and starts it there. A failed move leaves it running on its old node. See moving a volume.

Limits

  • A database runs one replica on one node, like any service with a local volume. There is no replication or failover.
  • Backups stay on the database's node unless a backup destination copies them to S3.
  • Removing a database from orch.pkl stops it. Its secrets stay until you delete them with orch secret delete.
Edit this page on GitHub