Element `<database>`¶

Purpose: Declare a named relational database client for reads, writes, and SQL execution.

Why: Use it to give relational reads, writes, selectors, and SQL execution one client id.

Example¶

<database id="customer-db"/>

Decision guide¶

Business value: Centralizes relational connectivity for selectors, SQL setup, inserts, and database operations.

Use when
- A descriptor reads from or writes to a relational database.
Choose another approach when
- The source is a MongoDB collection, file, object store, or message broker.
Prerequisites
- Choose the DBMS and provide its required connection properties through project configuration.
Alternatives
- Use mongodb for collection-oriented document data. (See: <mongodb>)

Complete examples¶

Prepare and read a deterministic relational source

Use a named database client when SQL preparation, source selection, and later targets must share one connection contract.

sqlite-assembly/datamimic.xml
<setup numProcess="1">
    <database id="source_db" dbms="sqlite" database="docs.sqlite"/>
    <execute script="'DROP TABLE IF EXISTS customers'" type="sql" target="source_db"/>
    <execute script="'CREATE TABLE customers (id INTEGER, name TEXT)'" type="sql" target="source_db"/>
    <execute script='"INSERT INTO customers VALUES (1, char(65,100,97)), (2, char(71,114,97,99,101))"'
             type="sql"
             target="source_db"/>
    <generate name="selected_customers"
              source="source_db"
              selector="SELECT id, name FROM customers ORDER BY id"
              distribution="ordered"
              target="LogExporter"/>
</setup>

Rules and invalid combinations¶

A relational client requires a database locator.

Attributes: dbms, database

Why: The DBMS and network endpoint do not identify the database, service, or catalog to open.

Valid combination
<database id="customerDb"/>

Invalid combination
<database id="customerDb" dbms="postgresql"/>

Allowed parents / Allowed children¶

Allowed parents: else, else-if, if, setup, while

Allowed children:

None

Extension attributes: The declared attributes are complete. This element also accepts runtime-defined vendor extensions, which intentionally have no static completion.

Generate Database-backed Sequences — Explains bounded database sequence reservation and its single-process policy.
Choose a source and target — Guides users and agents from an input ownership boundary and intended side effect to one bounded source and target contract.