Resources¶

Physical connections, and the databases built on top of them. A database is one of two kinds, discriminated by a required kind field: a plain generic database, or a CDM database with its logical vocab/results role bundle.

ConnectionConfig¶

A concrete database endpoint: dialect, host, credentials, target database. Stored in [connections.<name>].

Bases: BaseModel

Complete specification of one physical database connection: server address, credentials, and target database.

Referenced by :attr:DatabaseConfig.connection and :attr:DatabaseConfig.vocab_connection. Each entry under [connections] in config.toml maps to one instance of this model.

Passwords are stored in plaintext for now; secret management support is planned for a future release.

build_url ¶

build_url() -> str

Build the full connection URL, including the plaintext password.

Returns:

Type	Description
`str`	SQLAlchemy-compatible connection URL. For SQLite, returns `sqlite:///<database_name>`; `database_name` must be set explicitly (e.g. to `:memory:`), there is no implicit default.

resolve ¶

resolve(name: str) -> ResolvedConnection

Resolve this connection to a concrete, engine-ready target.

safe_url ¶

safe_url() -> str

Build the connection URL with the password redacted.

Safe for logging and display. Identical to build_url() for SQLite connections, which carry no password.

Returns:

Type	Description
`str`	Connection URL with `***` substituted for the password field.

to_env_pairs ¶

to_env_pairs(prefix: str) -> list[str]

Return PREFIX_FIELD=value strings for each non-None field.

Used by :func:~oa_configurator.io.write_env_file to emit env vars for Docker Compose env_file:. Field names are uppercased directly (e.g. host → PREFIX_HOST), so adding a new field here automatically appears in the export without touching io.py. The test_only config-only flag is excluded, since it is not a database connection parameter.

DatabaseKind¶

Bases: str, Enum

Discriminator for :class:DatabaseConfig subclasses.

DatabaseConfig¶

The shared base: kind, connection, schema_name. Not constructed directly — every [databases.<name>] entry is one of the two concrete kinds below, chosen by its own kind field. schema_name defaults differently per kind: unset on GenericDatabaseConfig means "no schema override, use the connection's own default"; CDMDatabaseConfig defaults it to "omop".

Bases: BaseModel

Shared interface for every named database: a connection plus a schema to route into.

Abstract in practice: kind has no default, so every concrete entry must declare it explicitly via one of the subclasses below. Use this class (not a subclass) for isinstance checks and RefTo targets that accept any kind; use :data:DatabaseEntry for parsing raw config data, which dispatches to the correct subclass based on kind.

resolve ¶

resolve(name: str, stack: StackConfig) -> ResolvedDatabase

Resolve this database to a concrete connection and effective schema.

stack must already have passed :meth:StackConfig.validate_references, so self.connection is guaranteed to exist in stack.connections.

GenericDatabaseConfig¶

kind = "generic". A database with no CDM-specific fields: just connection and schema_name. Used by anything that isn't the CDM itself, e.g. a vector store's own database (see Vector Stores).

Bases: DatabaseConfig

A connection plus one optional schema. No CDM role-splitting.

Used by consumers that need a single database with no vocab/results distinction, e.g. an embedding store or a metadata database.

CDMDatabaseConfig¶

kind = "cdm". Maps the OMOP logical roles (CDM, vocab, results) to named connections and schema names.

Bases: DatabaseConfig

Maps the OMOP logical roles (CDM, vocab, results) to named connections and schema names.

This is what a CDM-consuming package treats as "its database": the logical CDM/vocab/results bundle, as opposed to :class:ConnectionConfig (the physical server address and credentials underneath it). Most packages only need a single cdm_db database.

resolve ¶

resolve(
    name: str, stack: StackConfig
) -> ResolvedCDMDatabase

Resolve this database to concrete connections and effective schema names.

The vocab connection falls back to the primary connection when not explicitly configured; the vocab schema falls back to the CDM schema under the same condition. stack must already have passed :meth:StackConfig.validate_references, so self.connection/ self.vocab_connection are guaranteed to exist in stack.connections.

Role¶

Selects among a CDM database's several connections at resolve time. Not related to kind: kind decides which fields an entry has at config-authoring time, Role selects among one CDM entry's connections. A generic entry only ever has one connection, so Role has nothing to select there.

Bases: str, Enum

Which physical target a database's logical role maps to.

Shared between :meth:ResolvedDatabase.connection_target, which picks a concrete connection (only PRIMARY/VOCAB apply; RESULTS has no connection of its own), and :meth:ResolvedDatabase.schema_translate_map, which picks a schema name (all three apply). One enum instead of two separately-typed, overlapping string sets.

Resolved types¶

ConnectionConfig.resolve(), GenericDatabaseConfig.resolve(), and CDMDatabaseConfig.resolve() produce these. Resolver.resolve_connection()/resolve_database() are thin wrappers around the same methods; resolve_database() returns the resolved subtype matching the entry's own kind.

Concrete physical connection ready for engine creation.

Attributes:

Name	Type	Description
`name`	`str`	Logical name of the connection as declared in the config.
`url`	`str`	Full database URL including credentials. TODO: make this a private attribute to avoid accidental password exposure; requires a factory method or `__post_init__` since dataclass field visibility can't be changed without breaking callers.
`safe_url`	`str`	Database URL with credentials redacted, safe for logging and display.
`_engine_url`	`URL`	SQLAlchemy URL object used for engine creation. Avoids the lossy string round-trip through `url` for SQLite paths containing `?`/`#`.

create_engine ¶

create_engine(**kwargs: Any) -> Engine

Create a SQLAlchemy engine for this connection.

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	Forwarded to `sqlalchemy.create_engine`.	`{}`

Returns:

Type	Description
`Engine`

Resolved generic database: one connection, one optional schema.

Attributes:

Name	Type	Description
`name`	`str`	Logical name of the database as declared in the config.
`connection`	`ResolvedConnection`	Resolved connection for this database.
`schema_name`	`str \| None`	Effective schema name for this database, or None for no override (use the connection's own default/search_path).

create_engine ¶

create_engine(
    *,
    execution_options: dict[str, Any] | None = None,
    **kwargs: Any,
) -> Engine

Create a SQLAlchemy engine with the schema translate map applied.

Parameters:

Name	Type	Description	Default
`execution_options`	`dict`	Additional execution options merged into the engine. The `schema_translate_map` key is set automatically and must not be supplied here.	`None`
`**kwargs`	`Any`	Forwarded to `sqlalchemy.create_engine`.	`{}`

Returns:

Type	Description
`Engine`	Engine configured with `schema_translate_map` set to `{None: schema_name}`, a genuine no-op when `schema_name` is None, deferring to the connection's own default/search_path.

Bases: ResolvedDatabase

Resolved CDM database: adds vocab/results role-splitting on top of :class:ResolvedDatabase.

Attributes:

Name	Type	Description
`vocab_connection`	`ResolvedConnection`	Resolved vocabulary connection for this database. May be the same as connection if no separate vocab connection is configured.
`vocab_schema`	`str`	Effective vocabulary schema name for this database. May be the same as schema_name if no separate vocab schema is configured.
`results_schema`	`str \| None`	Effective results schema name for this database, or None if not configured.

connection_target ¶

connection_target(
    role: Role = Role.PRIMARY,
) -> ResolvedConnection

Return the resolved connection for a given role.

Parameters:

Name	Type	Description	Default
`role`	`Role`	Which connection to return. Defaults to `Role.PRIMARY`. When `vocab_connection` was not configured, `Role.VOCAB` returns the same connection as `Role.PRIMARY`.	`PRIMARY`

Returns:

Type	Description
`ResolvedConnection`	The concrete connection for role.

Raises:

Type	Description
`ValueError`	If role is `Role.RESULTS` (results has no connection of its own).

create_engine ¶

create_engine(
    role: Role = Role.PRIMARY,
    *,
    execution_options: dict[str, Any] | None = None,
    **kwargs: Any,
) -> Engine

Create a SQLAlchemy engine with the schema translate map applied.

The schema translate map routes OMOP ORM models to the correct schemas automatically (None -> schema_name, "vocab" -> vocab_schema, "results" -> results_schema when configured).

Parameters:

Name	Type	Description	Default
`role`	`Role`	Which connection to create an engine for. Defaults to `Role.PRIMARY`.	`PRIMARY`
`execution_options`	`dict`	Additional execution options merged into the engine. The `schema_translate_map` key is set automatically and must not be supplied here.	`None`
`**kwargs`	`Any`	Forwarded to `sqlalchemy.create_engine`.	`{}`

Returns:

Type	Description
`Engine`	Engine configured with `schema_translate_map` for OMOP ORM routing.

schema_translate_map ¶

schema_translate_map() -> dict[str | None, str | None]

SQLAlchemy schema translate map for OMOP ORM models.

Maps: None → schema_name (default / unqualified tables → CDM) "vocab" → vocab_schema (or schema_name as fallback) "results" → results_schema (omitted when not configured)