3.6 KiB
Database contracts
PLBA2 reads and writes application-owned tables through adapters. The application owns the schema, migrations, initial values, and retention policy. PLBA2 does not create tables or run migrations.
settings
The application creates settings in its own schema and loads initial rows in
its migration. The table has this contract:
| Field | Type | Constraints | Purpose |
|---|---|---|---|
id |
BIGINT |
Identity primary key, not null | Row identifier and final ordering key |
config_key |
VARCHAR(128) |
Nullable | Application-defined scope or entity |
setting_key |
VARCHAR(128) |
Not null | Stable setting name |
setting_value |
TEXT |
Not null | Text value decoded by the application |
sort_order |
INT |
Not null, default 0 |
Order for repeated keys |
is_enabled |
BOOLEAN |
Not null, default TRUE |
Includes or excludes a row from reads |
description |
TEXT |
Nullable | Human-readable explanation |
Indexes should support the adapter's filters and ordering, for example:
CREATE INDEX settings_key_enabled_order_idx
ON settings (setting_key, is_enabled, sort_order, id);
CREATE INDEX settings_scope_lookup_order_idx
ON settings (setting_key, config_key, is_enabled, sort_order, id);
There is no uniqueness constraint on setting_key; several enabled rows may
form an ordered list. Reads filter by setting_key, an optional config_key,
and is_enabled = TRUE, then order by sort_order, id. The value of a feature
toggle belongs in setting_value; is_enabled only controls whether the row is
read. config_key relationships are owned by the application.
settings stores business parameters, feature toggles, and technical values
that must change remotely while the process runs. Rarely changed technical
parameters remain in the root config.yaml; PLBA2 does not copy YAML into the
database.
trace_contexts and trace_messages
The application creates both trace tables in its own schema through its own
migration. Public code calls the context identifier business_trace_id; both
tables store it as trace_id.
trace_contexts contains:
| Field | Type | Constraints | Purpose |
|---|---|---|---|
trace_id |
UUID |
Primary key, not null | Public business_trace_id |
parent_id |
UUID |
Nullable | Parent context identifier |
alias |
TEXT |
Not null | Short context name |
trace_type |
TEXT |
Not null | Business operation type |
event_time |
TIMESTAMPTZ |
Not null | Context creation time |
attrs_json |
JSONB |
Not null | Context attributes, including application_id |
Create indexes on parent_id and event_time.
trace_messages contains:
| Field | Type | Constraints | Purpose |
|---|---|---|---|
id |
BIGINT |
Identity primary key, not null | Message identifier |
trace_id |
UUID |
Not null, references trace_contexts.trace_id with ON DELETE CASCADE |
Owning context |
event_time |
TIMESTAMPTZ |
Not null | Message time |
step |
TEXT |
Not null | Business step name |
status |
TEXT |
Not null | Step result |
level |
TEXT |
Not null | Business message level |
message |
TEXT |
Not null | Human-readable business message |
attrs_json |
JSONB |
Not null | Message attributes, including application_id |
Create indexes on trace_id, event_time, and status. The PostgreSQL
adapter only inserts rows, adds the runtime application_id to each
attrs_json, and passes database failures to the application. It does not
create tables, run migrations, publish RabbitMQ events, or expose a history API.