Aster Web Data / Connect your data

Several databases in one service

Configure one service over several databases and choose the database that stores each set.

Customers often live in one system and invoices in another: the CRM on PostgreSQL, the ledger on MariaDB, owned by the finance team and never written from outside. One service can publish sets from both, so a client reads a customer with their invoices in one request and never needs to know where each set is stored. You name each database once in the configuration, and each DataSource says which database holds it.

Configuration

Each database is a named entry under databases:, with its kind and its connection, and gets its own connection pool:

services:
  shop:
    datasources: [shop]            # Customer has database: crm, Invoice has database: ledger
  reports:
    database: crm                  # its sets default to crm
    datasources: [reports]

databases:
  crm:
    kind: postgres
    url_env: CRM_DB_URL
    tls: verify-full
    ca_file: ca.pem
    tls_strict: true
    required: true
  ledger:
    kind: mariadb
    url_env: LEDGER_DB_URL
    schema: ledger
    collation: utf8mb4_bin
    read_only: true

The connection URL stays out of the file: url_env names the environment variable that holds it, and url_file names a file that does. The kinds are on the Databases page, and each kind has a page of its own.

The example uses the keys that matter most when databases are mixed:

Key	Effect
`required`	With `true`, the server stops at start-up when it cannot open the database or the database fails its start-up check. The default, `false`, starts the server anyway: the database's sets answer `503` while the server keeps retrying, and the other databases serve as usual.
`read_only`	The server refuses to start unless every set on the database refuses writes in its own definition (`insertable`, `updatable` and `deletable` set to `false`) and no binding or action writes to it, and it opens read-only sessions where the database has them.
`collation`	The collation of the database's text fields that declare none of their own. See Model your data.
`tls`, `ca_file`, `tls_strict`	TLS for PostgreSQL and MariaDB. With `tls_strict: true`, a plaintext or unverified connection is an error rather than a warning.

The other keys, such as the parts form of the URL, pool.max and setup, are in Configuration.

Placement

Each DataSource is stored on one database. Its own database: names it, and without one the service's database applies. With more than one database configured and neither set, the server refuses the configuration at load.

The ledger's invoices name their database and refuse writes, as read_only requires:

# shop/Invoice.ds.yaml
dataSource:
  ID: Invoice
  database: ledger
  insertable: false
  updatable: false
  deletable: false
  fields:
    - {name: id, type: integer, primaryKey: true}
    - {name: issued, type: datetime, precision: 3}
    - {name: amount, type: decimal, precision: 12, scale: 2}

One database can serve several services over its one pool, as crm serves both shop and reports above.

Requests across the databases

A read that spans the databases, such as customers with their invoices, makes one statement per database for each level of the request. A database that goes down affects only its own sets, and writes to two databases cannot share a changeset. Each set's AsterData.AtomicGroup label in $metadata, one per database, tells a client which sets can be written together. Reads across databases shows the statements and gives the rules for each case.