Associations

Logical associations

Many-to-many associations are logical relationships with two named ends. They express a relationship that is stored as an associative table while keeping that table out of the logical model.

Ends and keys

Each end names an entity and maps declared columns to attributes in a primary or named unique key. If no key is named, the primary key is used. Pair order matters for composite keys.

Extra attributes

Extra attributes follow the two ends and are stored after end columns in the derived table. They use ordinary attribute types, nullability, defaults and descriptions.

Derivation

Derivation creates a table named after the association, with a primary key consisting of left columns followed by right columns, plus one foreign key per end. Repeating derivation is idempotent; incompatible existing tables are reported rather than replaced.

Self-associations

An association may connect an entity to itself. Its ends still need distinct column mappings, and derived foreign keys are suffixed _left and _right.

Diagrams

Logical diagrams show one labelled edge between the two entities with many markers at both ends. Derived tables appear only in physical diagrams.

Compare/pull

Logical comparison reports add, drop and alter association changes. Pull plans keep inferred association changes separate so their evidence can be reviewed.

Format

Use many_to_many declarations after ordinary relationships. For example, left student (student_id -> id) and right course (course_id -> id) define an enrollment association.

JSON

JSON model version 7 writes many_to_many after relationships. Each end contains its entity, optional key, ordered column pairs and required flag. Versions 1 through 6 read with an empty association map.

Limits

Only binary associations are supported. Association entities with independent identity and cross-database references are outside this feature.