Managed Databases

Voxeltron runs database containers on the same host as your apps, with a persistent volume per database. Create one from the CLI, or declare one in a manifest.

The vxl db commands are available from v0.1. They use the daemon'sDatabaseService API and the server profile you selected withvxl server use.

Supported engines

vxl db create accepts postgres, mysql,redis and mongodb. Manifests support postgres andredis, because those are the recipes that inject a connection URL into the app.

Create a database

$ vxl db create shop-db --engine postgres --project shop --server prod
$ vxl db create cache --engine redis --project shop --server prod

--project names the owning project. Databases are scoped to that project; the daemon checks the project on every database call.

List databases

$ vxl db list --server prod

Get the connection string

Store the connection URL as a project secret, then pass its reference to your app. The password stays out of shell variables and command arguments:

$ DATABASE_SECRET=$(vxl db conn shop-db --project shop --server prod --as-secret)
$ vxl deploy ghcr.io/example/shop:latest --name shop --server prod --type image --env DATABASE_URL="$DATABASE_SECRET"

--as-secret prints a secret:// reference. The daemon resolves the secret when it deploys the app. Use the same project and server for both commands. The URL uses the database alias on the project's network and works for apps on that server.

To inspect the URL, run vxl db conn shop-db --project shop --server prod. On a terminal, the CLI masks the password. Add --show-password to reveal it. When stdout is redirected or piped, the CLI prints the full URL for scripts:

$ vxl db conn shop-db --project shop --server prod --show-password
$ vxl db conn shop-db --project shop --server prod | your-command
The full connection string contains a password. Keep it out of logs and commits. Prefer --as-secret when you deploy an app.

Back up and restore

Create a backup, then list the backups for that database:

$ vxl db backup shop-db --server prod
$ vxl db backups shop-db --server prod

vxl db backups prints each backup id. Restore one by id. Restores and deletes are destructive, so they require --yes:

$ vxl db restore shop-db --backup <backup-id> --yes --server prod
$ vxl db delete cache --yes --server prod

With backup.target set to an S3-compatible target, the daemon also uploads each database backup after writing it locally, and vxl db backups includes the remote copies. See backups for the configuration.

Declare a database in a manifest

services:
  db:
    type: postgres
    disk: 1GB

vxl up creates the service and injects DATABASE_URL into the app component. A redis service injects REDIS_URL. Do not set either variable in app.env; the manifest loader rejects that conflict.

How it works

  • Each database is a Docker container with a dedicated volume.
  • The container is attached to the internal network, not published on a host port.
  • Postgres and Redis manifests generate a URL secret and store it in the daemon secret store.
  • The database container keeps running when the daemon restarts.