xtr_orm.bundle ¶
The xtr-dependency-injection bundle for xtr-orm.
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.makothat new revisions are rendered from; the package's own whenNone. -
recursive_version_locations(bool) –Read revisions from subdirectories of :attr:
directorytoo. -
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 ¶
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 fromDATABASE_URLby 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_optionsand every other the engine takes. -
session_options(Mapping[str, object]) –Session options —
expire_on_commit,autoflush,infoand 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:
urlnames, 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;
Nonefor the default ones. -
metadata(MetaData | Sequence[MetaData] | None) –The table definitions a migration diff compares the database with; those registered for :attr:
bind_keywhenNone. -
migrations(MigrationsConfig | None) –Where the revisions are and how they are recorded;
migrationsin the project directory for the default connection,migrations/<name>for any other, whenNone.
with_url_options ¶
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:
-
InvalidArgumentError–When an option's value cannot be read.
OrmBundle ¶
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 ¶
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 ¶
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).