engine

etl_craft.dialects.engine ¶

Engine DB dialects: PostgreSQL (recommended for production) and SQLite (the default).

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.

all_dialects ¶

all_dialects() -> Iterator[EngineDialect]

Yield every Engine DB dialect.

for_name ¶

for_name(dialect_name: str) -> EngineDialect

Return the dialect for a SQLAlchemy name such as postgresql+psycopg.

for_jdbc_url ¶

for_jdbc_url(jdbc_url: str) -> EngineDialect

Return the dialect a JDBC URL names; raises ConfigurationError for any other.

for_engine ¶

for_engine(engine: Engine | Connection) -> EngineDialect

Return the dialect engine is connected to.

build_engine ¶

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

Build a SQLAlchemy engine for profile, by default the active Engine profile.