Skip to Content

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.

projects/shop/project.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop
cluster: hetzner-fsn1
clusters/hetzner-fsn1.yaml
# 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: general

Roles on a Postgres database

projects/shop/apps/db.yaml
# 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: renew

databases maps a database name to its groups and roles.

  • Groups are roles without login that your migrations can grant to. bypass_rls: true lets 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 keyMeaning
ownerThe role owns the database and its schemas. At most one per database.
grantsPermission rules (below). Leaving it out leaves the role's grants alone; [] revokes them all.
member_ofGroups of this database, or pg_read_all_data, pg_write_all_data or pg_monitor.
set_roleThe role a session switches to at login. It must be listed in member_of, or be the role's own group.
bypass_rlsBypass row-level security.
connection_limitConnections per login, 1 to 500.
search_pathThe schema search path.
ttl, max_ttlHow long a lease lives (default 1h) and the hard limit renewals cannot pass (default 30d).
on_expiryrenew keeps the login and extends it; reissue creates a new login before the old one expires.
pg_roleUse 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.

projects/shop/apps/cache.yaml
# 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: 24h

A 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.

projects/shop/apps/api.yaml
# 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/db
  • output is url, user, password, host, port or database. The value reaches the app as a reference to its lease secret and is never written into the app's settings. format is not supported on a lease.
  • An app has one lease per role, shared by every key and file that names it.
  • lease_files also 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>_FILE variable.

{{dynamic:NAME}} values from the dashboard are not supported in IaC files. Use a lease instead.

On this page