Skip to content

xtr_orm.bundle

The xtr-dependency-injection bundle for xtr-orm.

ORM_CHANNEL module-attribute

ORM_CHANNEL: Final = 'orm'

The logging channel migrators write to.

MigrationsConfig dataclass

MigrationsConfig(directory: str = 'migrations', version_table: str = 'alembic_version', version_table_schema: str | None = None, history_table: str = 'alembic_version_history', file_template: str = '{year}{month}{day}{hour}{minute}{second}_{rev}_{slug}', truncate_slug_length: int = 40, timezone: str | None = None, template_directory: str | None = None, recursive_version_locations: bool = False, post_write_hooks: Sequence[Mapping[str, str]] = (), transaction_per_migration: bool = False, transactional_ddl: bool | None = None, compare_type: bool = False, compare_server_default: bool = False, render_as_batch: bool = False, include_schemas: bool = False, include_name: Callable[..., bool] | None = None, include_object: Callable[..., bool] | None = None, render_item: Callable[..., str | bool] | None = None, process_revision_directives: Callable[..., None] | None = None, user_module_prefix: str | None = None, context_options: Mapping[str, object] = _no_options())

Where a database's revisions live, how new ones are written, and how runs are recorded.

Revisions are ordinary migration files, one per change, in :attr:directory. The database keeps its current revisions in :attr:version_table, and a row per revision ever applied — when, and how long it took — in :attr:history_table.

MigrationsConfig(
    directory="%kernel.project_dir%/migrations",
    version_table_schema="meta",
    render_as_batch=True,  # SQLite cannot alter a table in place
)

Attributes:

  • directory (str) –

    Where revision files are read from and written to; created when the first one is written. A relative path is relative to the working directory — under a kernel, start it with %kernel.project_dir%.

  • version_table (str) –

    The table holding the database's current revisions.

  • version_table_schema (str | None) –

    The schema of both tables; the connection's default when None.

  • history_table (str) –

    The table recording every revision applied, when it ran and how long it took.

  • file_template (str) –

    How a new revision's file is named. {rev}, {slug}, {epoch}, {year}, {month}, {day}, {hour}, {minute} and {second} are filled in; the default sorts files by the time they were written.

  • truncate_slug_length (int) –

    The longest the message part of a file name gets.

  • timezone (str | None) –

    The time zone a revision's creation date is written in; local time when None.

  • template_directory (str | None) –

    A directory holding a script.py.mako that new revisions are rendered from; the package's own when None.

  • recursive_version_locations (bool) –

    Read revisions from subdirectories of :attr:directory too.

  • post_write_hooks (Sequence[Mapping[str, str]]) –

    Programs run on every file written, such as a formatter — each a mapping with a type ("console_scripts", "exec" or "module") and that type's options.

  • transaction_per_migration (bool) –

    Commit after each revision rather than once after all of them.

  • transactional_ddl (bool | None) –

    Whether schema changes run inside the transaction; the database's own answer when None.

  • compare_type (bool) –

    Compare column types when generating a diff. Off by default: a type the database stores as another — a UUID kept as bytes on SQLite — would otherwise differ in every diff.

  • compare_server_default (bool) –

    Compare server defaults when generating a diff.

  • render_as_batch (bool) –

    Write table changes as copy-and-move batches, which SQLite needs for anything but adding a column.

  • include_schemas (bool) –

    Compare every schema when generating a diff, not only the default one.

  • include_name (Callable[..., bool] | None) –

    Decides, by name, which schemas and tables a diff reads from the database.

  • include_object (Callable[..., bool] | None) –

    Decides which tables, columns, indexes and constraints a diff considers.

  • render_item (Callable[..., str | bool] | None) –

    Renders a type or a construct a diff writes, before the default rendering.

  • process_revision_directives (Callable[..., None] | None) –

    Adjusts a revision about to be written.

  • user_module_prefix (str | None) –

    Written before a custom type's class name; the type's own module — imported by the revision — when None.

  • context_options (Mapping[str, object]) –

    Any other migration context option, passed as it is.

alembic_file_template

alembic_file_template() -> str

Return :attr:file_template in the form the revision writer reads.

ConnectionConfig dataclass

ConnectionConfig(url: str = '%env(DATABASE_URL)%', engine_options: Mapping[str, object] = _no_options(), session_options: Mapping[str, object] = _no_options(), alchemy_options: Mapping[str, object] = _no_options(), replicas: Mapping[str, str] = _no_replicas(), keep_replica: bool = False, bind_key: str | None = None, metadata: MetaData | Sequence[MetaData] | None = None, migrations: MigrationsConfig | None = None)

One database: where it is, its replicas, its engine and sessions, and its migrations.

ConnectionConfig(
    url=env("DATABASE_URL"),
    replicas={"replica1": env("DATABASE_REPLICA_URL")},
    engine_options={"pool_size": 10, "pool_pre_ping": True},
    session_options={"expire_on_commit": False},
    migrations=MigrationsConfig(
        directory="%kernel.project_dir%/migrations", render_as_batch=True
    ),
)

Options may ride on the URL too, which is how one environment variable configures a whole connection — postgresql+asyncpg://app@db/shop?pool_size=20&expire_on_commit=false&ssl=require. An engine or session option, or keep_replica, is taken out of the URL and merged over the one configured here: the URL wins. Every other option stays on the URL for the driver.

Attributes:

  • url (str) –

    The database URL, with an async driver — postgresql+asyncpg://…, sqlite+aiosqlite:///…, mysql+asyncmy://…. Read from DATABASE_URL by default, when the connection is first used.

  • engine_options (Mapping[str, object]) –

    Engine options — echo, pool_size, max_overflow, pool_pre_ping, pool_recycle, isolation_level, connect_args, execution_options and every other the engine takes.

  • session_options (Mapping[str, object]) –

    Session options — expire_on_commit, autoflush, info and the rest.

  • alchemy_options (Mapping[str, object]) –

    Any other option of the database layer's own configuration, such as enable_touch_updated_timestamp_listener.

  • replicas (Mapping[str, str]) –

    Read replicas of the database :attr:url names, each a URL by name. With any, a session reads from a replica picked at random, and goes to the primary — :attr:url — for a write, a transaction's statements, and every read after them. Migrations, and the create and drop commands, always use the primary.

  • keep_replica (bool) –

    Go back to the replicas once a session commits, rather than read from the primary for the rest of its unit of work.

  • bind_key (str | None) –

    Which table definitions belong to this database when models declare several; None for the default ones.

  • metadata (MetaData | Sequence[MetaData] | None) –

    The table definitions a migration diff compares the database with; those registered for :attr:bind_key when None.

  • migrations (MigrationsConfig | None) –

    Where the revisions are and how they are recorded; migrations in the project directory for the default connection, migrations/<name> for any other, when None.

with_url_options

with_url_options() -> ConnectionConfig

Return this connection with the options its URL carries merged into it.

Called once the URL is read — an environment variable is not until a service needs it — so a mistake in the URL fails that service.

Raises:

OrmBundle

Bases: Bundle[OrmConfig]

Turns an :class:OrmConfig into an engine, sessions and a migrator per connection.

prepend_extension

prepend_extension(builder: ContainerBuilder) -> None

When logging is active, add the orm channel to its config.

load_extension

load_extension(config: OrmConfig, services: ServiceConfigurator, builder: ContainerBuilder) -> None

Register every connection's services under its name, the registry, the commands.

OrmConfig dataclass

OrmConfig(default_connection: str = DEFAULT_CONNECTION, connections: Mapping[str, ConnectionConfig] = _one_connection())

Which databases the application uses, each by name.

With no configuration there is one connection, default, reading its URL from DATABASE_URL when first used, with its revisions in migrations in the project directory.

OrmConfig(
    connections={
        "default": ConnectionConfig(url=env("DATABASE_URL")),
        "reports": ConnectionConfig(url=env("REPORTS_URL"), bind_key="reports"),
    },
)

Attributes:

  • default_connection (str) –

    The connection provided without a qualifier, and used by every command not given --connection.

  • connections (Mapping[str, ConnectionConfig]) –

    Every connection, by name — the default first once built, each with its migrations settings decided.

OrmMappingsPass

OrmMappingsPass(connection_parameter: str, enabled_parameter: str, *, driver: MappingDriverInterface | None = None)

Loads a mapping driver's tables into the connection two parameters name.

A library whose tables an application configures has them only once its own bundle read that configuration — too late to declare them, early enough for a compiler pass. Its bundle keeps one of these, registers it from build, builds its driver in load_extension and hands it over with :meth:set_driver; the pass then adds the tables to the definitions the connection's migrations compare the database with, so orm:migrations:diff writes them like any of the application's own.

@final
@required_bundle(OrmBundle)
@as_bundle("invoicing", config=InvoicingConfig)
class InvoicingBundle(Bundle[InvoicingConfig]):
    def __init__(self) -> None:
        self._mappings = OrmMappingsPass("invoicing.connection", "invoicing.persist")

    @override
    def build(self, builder: ContainerBuilder) -> None:
        builder.add_compiler_pass(self._mappings)

    @override
    def load_extension(
        self, config: InvoicingConfig, services: ServiceConfigurator, builder: ContainerBuilder
    ) -> None:
        builder.set_parameter("invoicing.connection", config.connection)
        builder.set_parameter("invoicing.persist", config.persist)
        if config.persist:
            self._mappings.set_driver(InvoicingDriver(config.table_prefix))

That bundle must declare @required_bundle(OrmBundle), as the example does: the pass reads the orm's own configuration to learn which connections exist, so a build where no active bundle configures it fails with UnknownConfigTypeError instead.

Both parameters are read while the container is compiled, before %name% references are resolved and long before an env(...) one is: a bundle sets them from its own resolved configuration, which is a plain name and a plain flag by then. One still holding a reference is refused, naming it, rather than taken for a name or for truth.

Load driver into the connection connection_parameter names.

Parameters:

  • connection_parameter (str) –

    The parameter holding the name of the connection whose definitions the tables join.

  • enabled_parameter (str) –

    The parameter deciding whether they do; read for truth, and an unset one means no.

  • driver (MappingDriverInterface | None, default: None ) –

    The driver, when the bundle already has it; otherwise handed over with :meth:set_driver.

set_driver

set_driver(driver: MappingDriverInterface) -> None

Hand the pass the driver to load, replacing any it was given before.

A bundle calls this from load_extension, where it first has the configuration its driver is built from; the pass runs after every bundle loaded.

process

process(builder: ContainerBuilder) -> None

Add the driver's tables to the named connection's definitions, when enabled.

Raises:

  • InvalidArgumentError –

    When the mappings are enabled with no driver handed over, when either parameter still holds an unresolved %name% reference, when the connection parameter holds something that is not a name or names no configured connection, or when that connection keeps several sets of table definitions.

  • ParameterNotFoundError –

    When the flag is set but the connection parameter is not, which the bundle sets beside it.

  • UnknownConfigTypeError –

    When no active bundle configures the orm — the library's bundle forgot @required_bundle(OrmBundle).