Databases and leases
Declare database roles and grants on a managed database, and give apps short-lived credentials through leases.
A managed database is an app with a database template.
Its roles are a block on that app file: databases for Postgres and
ClickHouse, roles for Valkey. Other apps of the project get credentials
for a role through a lease: a login that A-Line.cloud creates for the
app, renews and finally expires.
The examples on this page share one project, shop.
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop
cluster: hetzner-fsn1# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
provider: hetzner
region: fsn1
pools:
- name: control-plane
role: control_plane
- name: generalRoles on a Postgres database
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
template: postgres
version: "16"
databases:
shop:
groups:
shop_rw: {}
roles:
migrate:
owner: true
ttl: 72h
app:
member_of: [shop_rw]
reporting:
grants:
- schema: public
privileges: [read]
- schema: billing
table: invoices
columns: [id, total]
privileges: [read]
row_filter: "region = 'eu'"
connection_limit: 5
search_path: [public, billing]
ttl: 1h
max_ttl: 7d
on_expiry: renewdatabases maps a database name to its groups and roles.
- Groups are roles without login that your migrations can grant to.
bypass_rls: truelets a group bypass row-level security. - Roles are what apps lease. Each role becomes a group named
<database>_<role>; every lease is its own login in that group.
| Role key | Meaning |
|---|---|
owner | The role owns the database and its schemas. At most one per database. |
grants | Permission rules (below). Leaving it out leaves the role's grants alone; [] revokes them all. |
member_of | Groups of this database, or pg_read_all_data, pg_write_all_data or pg_monitor. |
set_role | The role a session switches to at login. It must be listed in member_of, or be the role's own group. |
bypass_rls | Bypass row-level security. |
connection_limit | Connections per login, 1 to 500. |
search_path | The schema search path. |
ttl, max_ttl | How long a lease lives (default 1h) and the hard limit renewals cannot pass (default 30d). |
on_expiry | renew keeps the login and extends it; reissue creates a new login before the old one expires. |
pg_role | Use this Postgres role name instead of <database>_<role>. Naming a role that already exists adopts it; privileged roles cannot be adopted. |
Making a role the owner, setting bypass_rls and adopting an existing role
are held until someone confirms them.
Permission rules
Each rule needs privileges and narrows its scope with schema, table
and columns. A key you leave out widens the rule: a rule with only a
schema covers every table of the schema, including tables created later.
row_filter limits the rows the role can see. The rule's database is the
enclosing one; don't set database in it.
See RoleSpec and
PermissionRule for every key.
Roles on Valkey
A Valkey app declares roles directly, without databases.
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
template: valkey
version: "8"
roles:
sessions:
keys: ["session:*"]
commands: ["@read", "@write"]
ttl: 24hA Valkey role takes key patterns (keys, read_keys, write_keys),
channels, commands and deny_commands, plus the same ttl, max_ttl
and on_expiry as a Postgres role. See
ValkeyRoleSpec.
Using a lease in an app
An app asks for a lease in an env value: from names the database app,
lease names the role (<database>/<role>, or just <role> for Valkey),
and output picks the part of the credentials.
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
image: ghcr.io/example/api:1.4.2
port: 8080
env:
DATABASE_URL:
from: app/db
lease: shop/app
output: url
REPORTING_USER:
from: app/db
lease: shop/reporting
output: user
CACHE_URL:
from: app/cache
lease: sessions
output: url
lease_files:
- from: app/db
lease: shop/app
path: /run/secrets/dboutputisurl,user,password,host,portordatabase. The value reaches the app as a reference to its lease secret and is never written into the app's settings.formatis not supported on a lease.- An app has one lease per role, shared by every key and file that names it.
lease_filesalso mounts the lease as files (url,user,password,host,port,database) in the given directory. The files are updated when the lease changes, so use them for processes that re-read their credentials. Env keys of a role delivered as files also get a<KEY>_FILEvariable.
{{dynamic:NAME}} values from the dashboard are not supported in IaC files.
Use a lease instead.