Skip to content

Create databases and users

Since v0.10.0 every managed database is a container of a Falak image, one per database service: its own data volume, memory limit, password and TLS certificate. A database appears on the project canvas as a service that sites can reference. Nothing is installed on the host, and any server can run database containers (every server gets Docker).

Engine Value Versions Image
PostgreSQL postgresql 15, 16, 17, 18 ghcr.io/falak-sh/falak-postgres
MySQL mysql 8.0, 8.4 ghcr.io/falak-sh/falak-mysql
MariaDB mariadb 10.11, 11.4 ghcr.io/falak-sh/falak-mariadb
Redis redis 7.4, 8 ghcr.io/falak-sh/falak-redis
Valkey valkey 8.1 ghcr.io/falak-sh/falak-valkey

Each image is the official image pinned by digest, plus falak-db, a small helper the agent uses for backups, restores, health checks and point-in-time recovery. Images are multi-arch (amd64 and arm64), scanned in CI and signed. Servers run an image only by the digest the control plane ships with its release; the agent refuses anything else.

Redis and Valkey have their own settings (eviction, persistence) — see Redis and Valkey.

  1. On the canvas: + Create → Database.
  2. Pick the engine, the version and the server. Name the service (for example shop-db); the name is what references use.
  3. Optionally adjust memory, CPUs and disk size.
  4. Create. The card is provisioning until the container runs, then Active.

Create picker → Database: choose the engine and a server.

Field Rule
Name Unique per server
Version One of the versions above; default the newest the release ships
Memory Default 512 MB (Redis / Valkey 128 MB); minimum 256 MB PostgreSQL and MariaDB, 384 MB MySQL, 32 MB Redis / Valkey
Disk Default 10 GB (Redis / Valkey 2 GB): the size of the data volume, grown later without downtime

A SQL database container starts with one database and one user named after it, granted ALL PRIVILEGES. Redis and Valkey containers have one keyspace and their default user.

Container falak-db-<id>, restart unless-stopped, 60 s to shut down cleanly
Data A sized volume (an ext4 image with a hard size limit), protected against deletion
Config Rendered at every start and tuned to the memory limit: PostgreSQL shared_buffers 25 % and effective_cache_size 75 %, InnoDB buffer pool 55 %, Redis / Valkey maxmemory 80 %
Passwords Files on a tmpfs, never in the container’s environment; restored by the agent after a reboot
TLS A certificate from the Falak CA. SQL engines offer TLS; turn on Require TLS to refuse plaintext
Health falak-db health as the Docker healthcheck, reported in heartbeats
Logs Through the log shipper; slow query logging is on (1000 ms, Redis / Valkey 10 ms)

Provisioning sets Docker’s live-restore, so restarting or upgrading Docker leaves database containers running.

Tab Contents
Overview The container (health, image digest, memory), connection details with copy and reveal, Rotate password, Limits & settings
Databases & users Databases in the container, users and their grants (SQL engines)
Backups Schedules, history, restore, drills — see Backups and drills
Settings Memory, max connections, version upgrades, danger zone

The database’s own page (Databases → the instance) also has the Point-in-time recovery card.

The database service panel, Overview tab: connection details with reveal.

Setting Engines Default
Memory, CPUs all as created
Max connections PostgreSQL, MySQL, MariaDB 100 / 151
Slow query log (ms) all 1000 (Redis / Valkey 10); 0 turns it off
Require TLS all off
Public access all off — see Remote access

Changing memory re-tunes the engine’s config. Settings, certificates and limits change in place with a restart; the container is only recreated for a new image, ports, network or mounts.

  1. Panel → Databases & users → New user.
  2. Enter a username and optional password (generated when empty) and, for MySQL/MariaDB, the host (% for any).
  3. Grant access per database. Privileges are upper-case names such as ALL PRIVILEGES, SELECT, INSERT.

Rotate a password from the user’s menu. Revealing a password needs databases.credentials.reveal (owners, admins, developers).

Reference the database from the site’s variables:

DATABASE_URL=${{ shop-db.DATABASE_URL }}

The keys are DATABASE_URL, DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD. The host and port depend on where the site runs:

The site runs… DB_HOST / DB_PORT
In a container on the database’s server (Docker site, Compose stack, function) falak-db-<id> and the engine’s port, on the environment’s private Docker network (falak-env-<environment>)
Natively on the database’s server 127.0.0.1 and the container’s host port
On another server of the environment The database server’s address on a private network both share, and the host port — see Remote access

References never resolve to a public address. See Variable references.

Settings → Operations → Version:

  • Minor (a newer image of the same major, for example a weekly rebuild with security updates): the container is recreated on the new digest, on the same volume.
  • Major (SQL engines): a new container is created and every database is copied into it while the old one is read-only (writes fail until the copy is checked, so downtime grows with the data). Row counts are compared per table, then the new container takes over the name and port apps use. The old one stays stopped with its volume until you delete it.

Deleting asks you to type the name. You choose whether its data volume is deleted too.

Action Permission Roles
View databases.view all
Create/delete containers, databases and users, change settings, back up databases.manage owner, admin, developer
Reveal passwords databases.credentials.reveal owner, admin, developer
Restore backups, point-in-time restores, export backup keys databases.restore owner, admin
Backup storage credentials databases.storage.manage owner, admin