base

etl_craft.dialects.engine.base ¶

What differs between Engine DBs, behind one interface.

Each dialect is a directory holding its module, its schema.sql (what init-db applies to an empty database), its migrations/ (what migrate applies to an existing one) and its queries/. Callers never branch on the Engine DB themselves: they ask for the dialect and call the method they need.

The query catalog holds every Engine DB query as a .sql file named after the query. A dialect's own queries/<name>.sql overrides the shared dialects/engine/queries/<name>.sql where the SQL differs. Every selected column is aliased in lower case, because SQLite and PostgreSQL disagree on the case of unquoted identifiers.

EngineDialect ¶

Bases: ABC

One Engine DB: how to connect, lock, split scripts, and which SQL to run.

name `property` ¶

name: str

SQLAlchemy's name for this database, such as postgresql.

auth_modes `property` ¶

auth_modes: frozenset[str]

The auth modes this Engine DB accepts.

build_engine `abstractmethod` ¶

build_engine(config: ConnectorConfig, profile: ConnectionProfile, **engine_kwargs: Any) -> Engine

Build a SQLAlchemy engine for profile, with no secret in its URL.

lock `abstractmethod` ¶

lock(engine: Engine, key: int, name: str, wait_seconds: float = 0) -> AbstractContextManager[None]

Hold the cross-process lock key for the with body.

name identifies it in messages. With wait_seconds 0 it waits indefinitely; otherwise it raises LockTimeoutError once that time has passed.

refresh_metadata_triggers `abstractmethod` ¶

refresh_metadata_triggers(conn: Connection) -> None

Install metadata capture and write guards for the current table definitions.

schema_problem ¶

schema_problem(conn: Connection, schema: str) -> str | None

Return why the Engine schema cannot be used, or None.

SQLite has one schema per file, and the file is created on first connect.

schema_path ¶

schema_path() -> Path

Return the full schema a fresh install applies.

migrations_dir ¶

migrations_dir() -> Path

Return the directory of the packaged ENGINE migration stream.

split_statements ¶

split_statements(sql_text: str) -> list[str]

Split a script into statements this database accepts one at a time.

migration_transaction ¶

migration_transaction(engine: Engine, *, rebuild_metadata: str | None = None) -> Iterator[Connection]

Apply a migration and its ledger row together, including any dialect's rebuild setup.

queries_dir ¶

queries_dir() -> Path

Return this dialect's own queries directory; its files override shared ones.

query_names ¶

query_names() -> frozenset[str]

Every query this dialect can run.

query_path ¶

query_path(name: str) -> Path

Return the file query name is read from; LookupError for an unknown name.

query ¶

query(name: str) -> str

Return the SQL text of query name.

Whole-line -- comments describe the query in its file and are left out, so a comment may name a :parameter without the driver seeing a second one.

existing_tables ¶

existing_tables(engine: Engine, names: tuple[str, ...]) -> list[str]

Return which of names already exist as tables, in lower case and sorted.