httk.store.db.mapping

Schema-to-SQL mapping: build SQLAlchemy Core tables from resolved TableSchema IR.

table_for() turns one resolved schema into a sqlalchemy.Table registered in a sqlalchemy.MetaData (idempotently: an already-built table is returned as-is), recursing into referenced and child-element storable classes so that the complete logical layout is present in the same metadata. sqlalchemy_metadata() is the convenience wrapper that maps a batch of schemas into one fresh metadata.

The relational layout produced here is exactly the one the schema IR documents, plus the store-managed columns:

• every parent table gets an sid integer primary key (autoincrementing, with an attached <table>_sid_seq sequence for dialects such as DuckDB that need one; SQLite ignores it) and — only under the "content_id" dedup policy — a unique-indexed content_id text column;

• every child table gets a <parent table>_sid integer sid column (NOT NULL, indexed) and a <field>_index integer ordering column ahead of its element columns; logical references are defined by httk.store.db.graph.

Index names are deterministic and table-scoped — ix_<table>_<column> for plain indexes, uq_<table>_<column> for unique ones, columns joined by underscores for composites — truncated with a stable hash suffix when they would exceed common identifier-length limits.

Attributes

SID_COLUMN	The store-managed integer primary-key column present on every table.
CONTENT_ID_COLUMN	The store-managed content-identity column of tables with the "content_id" dedup policy.
ROLE_COLUMN	The permanentization role of a parent record — 0 dependency, 1 main.
DISPATCH_CONTENT_ID_COLUMN	The content identity primary key of an entry-family dispatch table.

Functions

sqlalchemy_metadata(schemas)	A fresh sqlalchemy.MetaData holding the tables of schemas (recursively).
entry_dispatch_table_name(family_name)	The deterministic reserved table name for one registered entry family.
backing_dispatch_column_name(backing_name)	The deterministic nullable foreign-key column for one backing in a dispatch table.
dispatch_table_for(family_name, backings, metadata)	Build the one-of-many dispatch table for an entry family.
table_for(schema, metadata)	The sqlalchemy.Table of schema within metadata, building it on first use.

Module Contents

httk.store.db.mapping.SID_COLUMN: Final = 'sid'

The store-managed integer primary-key column present on every table.

httk.store.db.mapping.CONTENT_ID_COLUMN: Final = 'content_id'

The store-managed content-identity column of tables with the "content_id" dedup policy.

httk.store.db.mapping.ROLE_COLUMN: Final = '_httk_role'

The permanentization role of a parent record — 0 dependency, 1 main.

httk.store.db.mapping.DISPATCH_CONTENT_ID_COLUMN: Final = 'content_id'

The content identity primary key of an entry-family dispatch table.

httk.store.db.mapping.sqlalchemy_metadata(schemas)

A fresh sqlalchemy.MetaData holding the tables of schemas (recursively).

httk.store.db.mapping.entry_dispatch_table_name(family_name)

The deterministic reserved table name for one registered entry family.

httk.store.db.mapping.backing_dispatch_column_name(backing_name)

The deterministic nullable foreign-key column for one backing in a dispatch table.

httk.store.db.mapping.dispatch_table_for(family_name, backings, metadata)

Build the one-of-many dispatch table for an entry family.

A single-backing family has no dispatch table and must not call this helper. The primary key is the backing record’s canonical content id; every nullable backing sid is unique on its own, and the named check constraint makes precisely one of them non-null.

httk.store.db.mapping.table_for(schema, metadata)

The sqlalchemy.Table of schema within metadata, building it on first use.

Building is idempotent per metadata — if the table is already registered it is returned unchanged — and recursive: the child tables of the schema and the tables of every referenced storable class (reference fields and storable child elements alike) are built into the same metadata, so the complete logical layout is available to the storage algorithms.