Files
plba_v2/docs/database-contracts.md
T
2026-10-10 19:36:32 +03:00

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.