etlantic-sqlmodel API¶
Status: Available in ETLantic 0.41.0. SQLModel bridge helpers. Install narrative: package README. Hub: Optional packages API.
Setup¶
Failure modes¶
| Topic | Behavior |
|---|---|
| Model mismatch | Type/bridge errors |
Public API¶
etlantic-sqlmodel — ContractModel ↔ SQLModel bridge + CP1 reference stores.
Bases: SQLModel
Scoped alias pointing at an immutable revision.
Bases: SQLModel
Deployment / promotion environment directory row.
Bases: SQLModel
Stable logical identity preserved across revisions.
Bases: SQLModel
Immutable promotion record preserving logical_id.
Bases: SQLModel
Immutable append-only registry revision.
Bases: SQLModel
Security-domain directory row.
Workspace-scoped definition registry backed by SQLModel.
Minimal SQLModel-backed EventStore with tenant/workspace isolation.
dataclass
¶
SqlModelRegistryProvider(engine: Engine, tenants: SqlModelTenantDirectory | None = None, workspaces: SqlModelWorkspaceDirectory | None = None, revisions: SqlModelRevisionRegistry | None = None)
SQLModel :class:RegistryProvider with shared suspension checks.
dataclass
¶
SqlModelRevisionRegistry(engine: Engine, tenants: SqlModelTenantDirectory | None = None, workspaces: SqlModelWorkspaceDirectory | None = None)
Append-only SQLModel revision store with aliases and promotions.
Durable acceptance store with ADR-016 scoped idempotency and run observation.
dataclass
¶
SQLModel tenant directory with isolation and suspension fail-closed.
dataclass
¶
SQLModel workspace directory keyed by (tenant_id, workspace_id).
Bases: SQLModel
Durable tenant directory row (CP2 / 040-P).
Bases: SQLModel
Durable workspace directory row (tenant-owned).
Schema bridge helpers without ORM sessions or migrations.
Create CP reference tables.
Intended for tests and local demos — not a production migration path.
Create CP2 registry tables.
Intended for tests and local demos — not a production migration path.
Prefer :mod:etlantic_sqlmodel.migrations.
Create an engine; use a file URL for restart durability tests.
Return a zero-arg factory that opens a short-lived Session.
FastAPI-compatible dependency generator for a request-scoped session.
Sessions stay in the API layer — never pass them into pipeline runtimes.
Yield a session that commits on success and rolls back on error.
Upgrade to the latest migration (SQLite-friendly for tests).
Return the applied migration version, or None on a fresh database.
Roll back migrations down to target (None = empty schema).
Apply pending migrations up to target (default: latest).
contract_to_sqlmodel(contract_cls: type[Data], *, table_name: str | None = None, primary_key: tuple[str, ...] | None = None) -> type[SQLModel]
Generate a SQLModel table class from a Data / ContractModel class.
contract_to_sqlmodel_source(contract_cls: type[Data], *, table_name: str | None = None, primary_key: tuple[str, ...] | None = None) -> str
Generate importable SQLModel source for a Data / ContractModel class.
Extract draft contract metadata from a SQLModel table class.
Return ordered primary-key column names from a SQLModel table class.
validate_model_primary_keys(model_cls: type[Any], *, expected_keys: tuple[str, ...] | list[str] | None = None) -> ValidationReport
Fail closed when a SQLModel table lacks the expected primary key.
Compare contract and SQLModel metadata; return a ValidationReport.
Entry-point factory for tooling and conformance helpers.
run_conformance_checks(contract_cls: type[Data], *, table_name: str | None = None, primary_key: tuple[str, ...] | None = None) -> ValidationReport
Round-trip contract → SQLModel → metadata and compare schemas.
Optional SQLModel control-plane reference stores (CP1/CP2).
Persistence models are separate from HTTP response models. Sessions are
request-scoped helpers and must not be passed into pipeline runtimes.
create_control_plane_tables / create_registry_tables are for
tests/demos — production must apply versioned migrations under
etlantic_sqlmodel.migrations.
SQLModelDurableWorkStore(engine: Engine, *, admission_limit: int | None = None, store_id: str = 'default')
Transactional DurableWorkStore backed by a SQL snapshot row.
Bases: SQLModel
Scoped alias pointing at an immutable revision.
Bases: SQLModel
Transactional CP3 durable-work snapshot (reference provider).
One logical store per engine; mutations load/save under a DB transaction so accept+outbox and fencing CAS share commit boundaries.
Bases: SQLModel
Deployment / promotion environment directory row.
Bases: SQLModel
Stable logical identity preserved across revisions.
Bases: SQLModel
Immutable promotion record preserving logical_id.
Bases: SQLModel
Immutable append-only registry revision.
Bases: SQLModel
Security-domain directory row.
Bases: SQLModel
Durable tenant directory row (CP2 / 040-P).
Bases: SQLModel
Durable workspace directory row (tenant-owned).
dataclass
¶
BackupTranscript(schema: str, created_at: str, tenants: tuple[dict[str, Any], ...], workspaces: tuple[dict[str, Any], ...], revisions: tuple[dict[str, Any], ...], logicals: tuple[dict[str, Any], ...] = (), aliases: tuple[dict[str, Any], ...] = (), promotions: tuple[dict[str, Any], ...] = (), environments: tuple[dict[str, Any], ...] = (), security_domains: tuple[dict[str, Any], ...] = ())
Structured backup transcript (scope-preserving).
dataclass
¶
SqlModelRegistryProvider(engine: Engine, tenants: SqlModelTenantDirectory | None = None, workspaces: SqlModelWorkspaceDirectory | None = None, revisions: SqlModelRevisionRegistry | None = None)
SQLModel :class:RegistryProvider with shared suspension checks.
dataclass
¶
SqlModelRevisionRegistry(engine: Engine, tenants: SqlModelTenantDirectory | None = None, workspaces: SqlModelWorkspaceDirectory | None = None)
Append-only SQLModel revision store with aliases and promotions.
dataclass
¶
SQLModel tenant directory with isolation and suspension fail-closed.
dataclass
¶
SQLModel workspace directory keyed by (tenant_id, workspace_id).
Workspace-scoped definition registry backed by SQLModel.
Minimal SQLModel-backed EventStore with tenant/workspace isolation.
Durable acceptance store with ADR-016 scoped idempotency and run observation.
Create CP3 durable tables (tests/demos only).
Dump source and load into destination; return the transcript.
Dump tenants, workspaces, and revisions from a registry SQLite engine.
load_registry_sqlite(engine: Engine, transcript: BackupTranscript, *, create_tables: bool = True) -> SqlModelRegistryProvider
Restore tenants/workspaces/revisions into engine, preserving scope.
Read a backup transcript JSON file.
Write a backup transcript JSON file.
collect_revision_hits(provider: SqlModelRegistryProvider, ctx: ControlPlaneContext, *, logical_id: str | None = None, kind: str | None = None) -> Sequence[RevisionSearchHit]
Return metadata-only hits for ctx scope (no content bodies).
Create CP2 registry tables.
Intended for tests and local demos — not a production migration path.
Prefer :mod:etlantic_sqlmodel.migrations.
Create an engine; use a file URL for restart durability tests.
Return a zero-arg factory that opens a short-lived Session.
FastAPI-compatible dependency generator for a request-scoped session.
Sessions stay in the API layer — never pass them into pipeline runtimes.
Yield a session that commits on success and rolls back on error.
Create CP reference tables.
Intended for tests and local demos — not a production migration path.
SQLModel-backed DurableWorkStore (CP3 / 041-P).
Reference provider: each mutating call loads the durable snapshot inside a
database transaction, applies MemoryDurableWorkStore semantics, and writes the
snapshot back with an optimistic payload_version check before commit.
Production note: apply versioned migrations — do not rely on
create_durable_tables as the sole schema path.
SQLModel persistence tables for control-plane reference stores.
These are persistence models only — not HTTP response models and not ETLantic pipeline contracts.
Bases: SQLModel
Durable tenant directory row (CP2 / 040-P).
Bases: SQLModel
Durable workspace directory row (tenant-owned).
Bases: SQLModel
Stable logical identity preserved across revisions.
Bases: SQLModel
Immutable append-only registry revision.
Bases: SQLModel
Scoped alias pointing at an immutable revision.
Bases: SQLModel
Immutable promotion record preserving logical_id.
Bases: SQLModel
Deployment / promotion environment directory row.
Bases: SQLModel
Security-domain directory row.
Bases: SQLModel
Transactional CP3 durable-work snapshot (reference provider).
One logical store per engine; mutations load/save under a DB transaction so accept+outbox and fencing CAS share commit boundaries.
Registry SQLite backup/restore transcript helpers (CP2 / 040-O).
Dump and load tenants, workspaces, and revisions while preserving compound tenant/workspace scope. Content bodies are included for round-trip fidelity but histories/impact remain separate (metadata-only stores).
dataclass
¶
BackupTranscript(schema: str, created_at: str, tenants: tuple[dict[str, Any], ...], workspaces: tuple[dict[str, Any], ...], revisions: tuple[dict[str, Any], ...], logicals: tuple[dict[str, Any], ...] = (), aliases: tuple[dict[str, Any], ...] = (), promotions: tuple[dict[str, Any], ...] = (), environments: tuple[dict[str, Any], ...] = (), security_domains: tuple[dict[str, Any], ...] = ())
Structured backup transcript (scope-preserving).
Dump tenants, workspaces, and revisions from a registry SQLite engine.
Write a backup transcript JSON file.
Read a backup transcript JSON file.
load_registry_sqlite(engine: Engine, transcript: BackupTranscript, *, create_tables: bool = True) -> SqlModelRegistryProvider
Restore tenants/workspaces/revisions into engine, preserving scope.
Dump source and load into destination; return the transcript.
SQLModel-backed revision metadata search (CP2 / 040-O).
collect_revision_hits(provider: SqlModelRegistryProvider, ctx: ControlPlaneContext, *, logical_id: str | None = None, kind: str | None = None) -> Sequence[RevisionSearchHit]
Return metadata-only hits for ctx scope (no content bodies).
SQLModel-backed RegistryProvider implementations (CP2 / 040-P).
Production deployments must apply versioned migrations — do not rely on
create_all / create_registry_tables as the sole schema path.
dataclass
¶
SQLModel tenant directory with isolation and suspension fail-closed.
dataclass
¶
SQLModel workspace directory keyed by (tenant_id, workspace_id).
dataclass
¶
SqlModelRevisionRegistry(engine: Engine, tenants: SqlModelTenantDirectory | None = None, workspaces: SqlModelWorkspaceDirectory | None = None)
Append-only SQLModel revision store with aliases and promotions.
dataclass
¶
SqlModelRegistryProvider(engine: Engine, tenants: SqlModelTenantDirectory | None = None, workspaces: SqlModelWorkspaceDirectory | None = None, revisions: SqlModelRevisionRegistry | None = None)
SQLModel :class:RegistryProvider with shared suspension checks.
Create CP2 registry tables.
Intended for tests and local demos — not a production migration path.
Prefer :mod:etlantic_sqlmodel.migrations.
Request-scoped SQLModel session helpers for control-plane stores.
Create an engine; use a file URL for restart durability tests.
Yield a session that commits on success and rolls back on error.
Return a zero-arg factory that opens a short-lived Session.
FastAPI-compatible dependency generator for a request-scoped session.
Sessions stay in the API layer — never pass them into pipeline runtimes.
SQLModel-backed DefinitionRepository and SubmissionStore implementations.
Workspace-scoped definition registry backed by SQLModel.
Durable acceptance store with ADR-016 scoped idempotency and run observation.
Minimal SQLModel-backed EventStore with tenant/workspace isolation.
Create CP reference tables.
Intended for tests and local demos — not a production migration path.
Lightweight versioned migrations for etlantic-sqlmodel control-plane tables.
Production must apply these migrations (or an equivalent Alembic chain). Do
not treat SQLModel.metadata.create_all / create_control_plane_tables
/ create_registry_tables as the sole production schema path.
Return the applied migration version, or None on a fresh database.
Apply pending migrations up to target (default: latest).
Roll back migrations down to target (None = empty schema).
Upgrade to the latest migration (SQLite-friendly for tests).