> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# 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](/iac/apps#source).
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 title="projects/shop/project.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop
cluster: hetzner-fsn1
```

```yaml title="clusters/hetzner-fsn1.yaml" iac
# 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

```yaml title="projects/shop/apps/db.yaml" iac
# 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 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](/iac/gitops#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`](/iac/reference/types#rolespec) and
[`PermissionRule`](/iac/reference/types#permissionrule) for every key.

## Roles on Valkey

A Valkey app declares `roles` directly, without databases.

```yaml title="projects/shop/apps/cache.yaml" iac
# 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`](/iac/reference/types#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 title="projects/shop/apps/api.yaml" iac
# 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.
