xtr-orm 1.5.0__py3-none-any.whl

xtr_orm/command/migrations_execute_command.py

@@ -0,0 +1,86 @@
+"""``orm:migrations:execute``: run chosen revisions alone, up or down."""
+
+from __future__ import annotations
+
+from typing import final
+
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+from xtr_orm.exception import MigrationError
+from xtr_orm.migrations import Direction
+
+from .connection_command import (
+    ConnectionCommand,
+    confirm_changes,
+    report_count,
+    report_plan,
+    report_results,
+    save_sql,
+)
+
+__all__ = ["MigrationsExecuteCommand"]
+
+
+@as_command("orm:migrations:execute")
+@final
+class MigrationsExecuteCommand(ConnectionCommand):
+    """Execute one or more migration versions up or down manually."""
+
+    __slots__ = ()
+
+    async def __call__(  # noqa: PLR0911 — each way out says why it stopped
+        self,
+        io: ConsoleStyle,
+        *versions: str,
+        up: bool = False,
+        down: bool = False,
+        dry_run: bool = False,
+        write_sql: str | None = None,
+        connection: str | None = None,
+    ) -> int:
+        """Run exactly the versions, in order, each up (the default) or down, and nothing else.
+
+        Going up, a revision must not be applied and must follow only applied
+        ones; going down, it must be applied and followed by none that is.
+        Use orm:migrations:version to record a revision without running it.
+
+        Args:
+            io: Where the command writes.
+            versions: The revisions to run, by full or partial id.
+            up: Run their upgrades.
+            down: Run their downgrades.
+            dry_run: List what would run, and run nothing.
+            write_sql: Write the SQL that would run to this file — or to a
+                dated file in this directory — and run nothing.
+            connection: The connection to run them on; the default one when
+                left out.
+        """
+        if up and down:
+            io.error("Give --up or --down, not both.")
+            return ExitCode.INVALID
+        if not versions:
+            io.error("Name at least one version to execute.")
+            return ExitCode.INVALID
+        direction = Direction.DOWN if down else Direction.UP
+        migrator = await self._migrator(io, connection)
+        if migrator is None:
+            return ExitCode.FAILURE
+        try:
+            if write_sql is not None:
+                save_sql(io, write_sql, await migrator.execute_sql(versions, direction))
+                return ExitCode.SUCCESS
+            planned = await migrator.plan_for_versions(versions, direction)
+            if dry_run:
+                report_plan(io, planned)
+                io.note("Dry run: nothing was executed.")
+                return ExitCode.SUCCESS
+            if not confirm_changes(io, migrator):
+                io.error("Migration cancelled!")
+                return ExitCode.FAILURE
+            results = await migrator.execute(versions, direction)
+        except MigrationError as error:
+            io.error(escape(error.reason))
+            return ExitCode.FAILURE
+        report_results(io, results)
+        report_count(io, results)
+        return ExitCode.SUCCESS

xtr_orm/command/migrations_generate_command.py

@@ -0,0 +1,47 @@
+"""``orm:migrations:generate``: write an empty revision."""
+
+from __future__ import annotations
+
+from typing import final
+
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+from xtr_orm.exception import MigrationError
+
+from .connection_command import ConnectionCommand, report_written
+
+__all__ = ["MigrationsGenerateCommand"]
+
+
+@as_command("orm:migrations:generate")
+@final
+class MigrationsGenerateCommand(ConnectionCommand):
+    """Generate a blank migration class."""
+
+    __slots__ = ()
+
+    async def __call__(
+        self,
+        io: ConsoleStyle,
+        *,
+        message: str | None = None,
+        connection: str | None = None,
+    ) -> int:
+        """Write an empty revision following the latest one, to fill in by hand.
+
+        Args:
+            io: Where the command writes.
+            message: What the revision does; it names the file too.
+            connection: The connection whose revisions to add to; the default
+                one when left out.
+        """
+        migrator = await self._migrator(io, connection)
+        if migrator is None:
+            return ExitCode.FAILURE
+        try:
+            written = migrator.generate(message)
+        except MigrationError as error:
+            io.error(escape(error.reason))
+            return ExitCode.FAILURE
+        report_written(io, "Generated new migration class to", written, connection)
+        return ExitCode.SUCCESS

xtr_orm/command/migrations_latest_command.py

@@ -0,0 +1,44 @@
+"""``orm:migrations:latest``: the revisions no other follows."""
+
+from __future__ import annotations
+
+from typing import final
+
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+from xtr_orm.exception import MigrationError
+
+from .connection_command import ConnectionCommand, format_version
+
+__all__ = ["MigrationsLatestCommand"]
+
+
+@as_command("orm:migrations:latest")
+@final
+class MigrationsLatestCommand(ConnectionCommand):
+    """Outputs the latest version."""
+
+    __slots__ = ()
+
+    async def __call__(self, io: ConsoleStyle, *, connection: str | None = None) -> int:
+        """Print the revisions no other follows, one per line — base when there are none.
+
+        Args:
+            io: Where the command writes.
+            connection: The connection whose revisions to read; the default one
+                when left out.
+        """
+        migrator = await self._migrator(io, connection)
+        if migrator is None:
+            return ExitCode.FAILURE
+        try:
+            status = await migrator.status()
+        except MigrationError as error:
+            io.error(escape(error.reason))
+            return ExitCode.FAILURE
+        heads = [each for each in status.available if each.is_head]
+        if not heads:
+            io.text("base")
+        for head in heads:
+            io.text(escape(format_version(head.version, head.description)))
+        return ExitCode.SUCCESS

xtr_orm/command/migrations_list_command.py

@@ -0,0 +1,71 @@
+"""``orm:migrations:list``: every revision, and whether it is applied."""
+
+from __future__ import annotations
+
+from typing import final
+
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+from xtr_orm.exception import MigrationError
+from xtr_orm.migrations import ExecutedMigration
+
+from .connection_command import ConnectionCommand
+
+__all__ = ["MigrationsListCommand"]
+
+
+@as_command("orm:migrations:list")
+@final
+class MigrationsListCommand(ConnectionCommand):
+    """Display a list of all available migrations and their status."""
+
+    __slots__ = ()
+
+    async def __call__(self, io: ConsoleStyle, *, connection: str | None = None) -> int:
+        """List every revision, earliest first, then the applied ones whose file is gone.
+
+        Args:
+            io: Where the command writes.
+            connection: The connection to read; the default one when left out.
+        """
+        migrator = await self._migrator(io, connection)
+        if migrator is None:
+            return ExitCode.FAILURE
+        try:
+            status = await migrator.status()
+        except MigrationError as error:
+            io.error(escape(error.reason))
+            return ExitCode.FAILURE
+        executed = {each.version: each for each in status.executed}
+        rows = [
+            _row(each.version, executed.get(each.version), each.description, available=True)
+            for each in status.available
+        ]
+        rows += [
+            _row(each.version, each, "", available=False) for each in status.executed_unavailable
+        ]
+        io.table(
+            ["Migration Versions", "Status", "Migrated At", "Execution Time", "Description"],
+            rows,
+        )
+        return ExitCode.SUCCESS
+
+
+def _row(
+    version: str, executed: ExecutedMigration | None, description: str, *, available: bool
+) -> list[str]:
+    if executed is None:
+        status = "not migrated"
+    else:
+        status = "migrated" if available else "migrated, not available"
+    migrated_at = (
+        f"{executed.executed_at:%Y-%m-%d %H:%M:%S}"
+        if executed is not None and executed.executed_at is not None
+        else ""
+    )
+    duration = (
+        f"{executed.execution_time:.3f}s"
+        if executed is not None and executed.execution_time is not None
+        else ""
+    )
+    return [escape(version), status, migrated_at, duration, escape(description)]

xtr_orm/command/migrations_migrate_command.py

@@ -0,0 +1,108 @@
+"""``orm:migrations:migrate``: bring the database to a revision, up or down."""
+
+from __future__ import annotations
+
+from typing import Final, final
+
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+from xtr_orm.exception import MigrationError
+
+from .connection_command import (
+    ConnectionCommand,
+    confirm_changes,
+    report_count,
+    report_plan,
+    report_results,
+    save_sql,
+)
+
+__all__ = ["MigrationsMigrateCommand"]
+
+_LATEST: Final = frozenset({"latest", "head", "heads"})
+
+
+@as_command("orm:migrations:migrate")
+@final
+class MigrationsMigrateCommand(ConnectionCommand):
+    """Execute a migration to a specified version or the latest available version."""
+
+    __slots__ = ()
+
+    async def __call__(  # noqa: C901, PLR0911 — each way out says why it stopped
+        self,
+        io: ConsoleStyle,
+        version: str = "latest",
+        *,
+        dry_run: bool = False,
+        write_sql: str | None = None,
+        allow_no_migration: bool = False,
+        connection: str | None = None,
+    ) -> int:
+        """Run every revision between where the database is and the version.
+
+        The version is a revision — a full or partial id — a relative one
+        (+1, -2), or one of latest, first (before every
+        revision), next, prev and current. A revision already
+        applied is migrated down to; one that is not, up to.
+
+        Args:
+            io: Where the command writes.
+            version: Where to bring the database.
+            dry_run: List what would run, and run nothing.
+            write_sql: Write the SQL that would run to this file — or to a
+                dated file in this directory — and run nothing.
+            allow_no_migration: Succeed when there are no revisions at all.
+            connection: The connection to migrate; the default one when left
+                out.
+        """
+        migrator = await self._migrator(io, connection)
+        if migrator is None:
+            return ExitCode.FAILURE
+        try:
+            status = await migrator.status()
+            if not status.available:
+                if allow_no_migration:
+                    io.warning("No migrations to execute.")
+                    return ExitCode.SUCCESS
+                io.error(
+                    f'The version "{escape(version)}" couldn\'t be reached, '
+                    "there are no registered migrations.",
+                )
+                return ExitCode.FAILURE
+            unregistered = len(status.executed_unavailable)
+            if unregistered:
+                io.warning(
+                    f"You have {unregistered} previously executed migrations in the database "
+                    "that are not registered migrations.",
+                )
+                if not io.confirm("Are you sure you wish to continue?", default=True):
+                    io.error("Migration cancelled!")
+                    return ExitCode.FAILURE
+            plans = await migrator.plan(version)
+            if not plans:
+                where = ", ".join(status.current) or "base"
+                message = (
+                    f'Already at the latest version ("{escape(where)}").'
+                    if version in _LATEST
+                    else f'Already at "{escape(version)}": no migrations to execute.'
+                )
+                io.success(message)
+                return ExitCode.SUCCESS
+            if write_sql is not None:
+                save_sql(io, write_sql, await migrator.migrate_sql(version))
+                return ExitCode.SUCCESS
+            if dry_run:
+                report_plan(io, plans)
+                io.note("Dry run: nothing was executed.")
+                return ExitCode.SUCCESS
+            if not confirm_changes(io, migrator):
+                io.error("Migration cancelled!")
+                return ExitCode.FAILURE
+            results = await migrator.migrate(version)
+        except MigrationError as error:
+            io.error(escape(error.reason))
+            return ExitCode.FAILURE
+        report_results(io, results)
+        report_count(io, results)
+        return ExitCode.SUCCESS

xtr_orm/command/migrations_rollup_command.py

@@ -0,0 +1,43 @@
+"""``orm:migrations:rollup``: record the single remaining revision as all there is."""
+
+from __future__ import annotations
+
+from typing import final
+
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+from xtr_orm.exception import MigrationError
+
+from .connection_command import ConnectionCommand
+
+__all__ = ["MigrationsRollupCommand"]
+
+
+@as_command("orm:migrations:rollup")
+@final
+class MigrationsRollupCommand(ConnectionCommand):
+    """Rollup migrations by deleting all tracked versions and insert the one version that exists."""
+
+    __slots__ = ()
+
+    async def __call__(self, io: ConsoleStyle, *, connection: str | None = None) -> int:
+        """Forget every applied revision, then record the single remaining one as applied.
+
+        For after squashing every revision into one: the database is left as
+        it is, recorded as being at that revision.
+
+        Args:
+            io: Where the command writes.
+            connection: The connection to record on; the default one when left
+                out.
+        """
+        migrator = await self._migrator(io, connection)
+        if migrator is None:
+            return ExitCode.FAILURE
+        try:
+            rolled = await migrator.rollup()
+        except MigrationError as error:
+            io.error(escape(error.reason))
+            return ExitCode.FAILURE
+        io.success(f'Rolled up migrations to version "{escape(rolled.version)}".')
+        return ExitCode.SUCCESS

xtr_orm/command/migrations_status_command.py

@@ -0,0 +1,66 @@
+"""``orm:migrations:status``: where the database stands, in one table."""
+
+from __future__ import annotations
+
+from typing import final
+
+from xtr_console import ConsoleStyle, ExitCode, as_command, escape
+
+from xtr_orm.exception import MigrationError
+
+from .connection_command import ConnectionCommand
+
+__all__ = ["MigrationsStatusCommand"]
+
+
+@as_command("orm:migrations:status")
+@final
+class MigrationsStatusCommand(ConnectionCommand):
+    """View the status of a set of migrations."""
+
+    __slots__ = ()
+
+    async def __call__(self, io: ConsoleStyle, *, connection: str | None = None) -> int:
+        """Show where the revisions and their tables are, and where the database stands.
+
+        Args:
+            io: Where the command writes.
+            connection: The connection to read; the default one when left out.
+        """
+        migrator = await self._migrator(io, connection)
+        if migrator is None:
+            return ExitCode.FAILURE
+        try:
+            status = await migrator.status()
+        except MigrationError as error:
+            io.error(escape(error.reason))
+            return ExitCode.FAILURE
+        config = migrator.config
+        url = migrator.engine.url
+        schema = config.version_table_schema
+        rows = [
+            ["Storage", "Version table", _qualified(schema, config.version_table)],
+            ["", "History table", _qualified(schema, config.history_table)],
+            ["Database", "Connection", migrator.name],
+            ["", "Driver", f"{url.get_backend_name()}+{url.get_driver_name()}"],
+            ["", "Name", url.database or ""],
+            ["Versions", "Previous", _versions(status.previous) if status.current else "none"],
+            ["", "Current", _versions(status.current)],
+            ["", "Next", ", ".join(status.next) or "none"],
+            ["", "Latest", _versions(status.latest)],
+            ["Migrations", "Executed", str(len(status.executed))],
+            ["", "Executed Unavailable", str(len(status.executed_unavailable))],
+            ["", "Available", str(len(status.available))],
+            ["", "New", str(len(status.new))],
+            ["Migrations Directory", "", config.directory],
+        ]
+        io.table(["Configuration", "", ""], [[escape(cell) for cell in row] for row in rows])
+        return ExitCode.SUCCESS
+
+
+def _versions(versions: tuple[str, ...]) -> str:
+    return ", ".join(versions) or "base"
+
+
+def _qualified(schema: str | None, table: str) -> str:
+    return f"{schema}.{table}" if schema else table

xtr_orm/command/migrations_up_to_date_command.py

@@ -0,0 +1,83 @@
+"""``orm:migrations:up-to-date``: whether every revision is applied."""
+
+from __future__ import annotations
+
+from typing import Annotated, Final, final
+
+from xtr_console import ConsoleStyle, ExitCode, Option, as_command, escape
+
+from xtr_orm.exception import MigrationError
+
+from .connection_command import ConnectionCommand
+
+__all__ = ["MigrationsUpToDateCommand"]
+
+_UNREGISTERED: Final = 2
+"""The exit code for applied revisions without a file, with --fail-on-unregistered."""
+
+
+@as_command("orm:migrations:up-to-date")
+@final
+class MigrationsUpToDateCommand(ConnectionCommand):
+    """Tells you if your schema is up-to-date."""
+
+    __slots__ = ()
+
+    async def __call__(
+        self,
+        io: ConsoleStyle,
+        *,
+        fail_on_unregistered: Annotated[bool, Option(alias="-u")] = False,
+        list_migrations: Annotated[bool, Option(alias="-l")] = False,
+        connection: str | None = None,
+    ) -> int:
+        """Tell whether every revision is applied, exiting 1 when some are not.
+
+        Applied revisions whose file is gone are reported too, and exit 2 with
+        --fail-on-unregistered.
+
+        Args:
+            io: Where the command writes.
+            fail_on_unregistered: Fail when applied revisions have no file.
+            list_migrations: List the revisions not applied, and the applied
+                ones without a file.
+            connection: The connection to read; the default one when left out.
+        """
+        migrator = await self._migrator(io, connection)
+        if migrator is None:
+            return ExitCode.FAILURE
+        try:
+            status = await migrator.status()
+        except MigrationError as error:
+            io.error(escape(error.reason))
+            return ExitCode.FAILURE
+        new = len(status.new)
+        unregistered = len(status.executed_unavailable)
+        if not new and not unregistered:
+            io.success("Up-to-date! No migrations to execute.")
+            return ExitCode.SUCCESS
+        code: int = ExitCode.SUCCESS
+        if new:
+            are = " is" if new == 1 else "s are"
+            io.error(f"Out-of-date! {new} migration{are} available to execute.")
+            code = ExitCode.FAILURE
+        if unregistered:
+            io.error(
+                f"You have {unregistered} previously executed "
+                f"migration{'' if unregistered == 1 else 's'} in the database that "
+                f"{'is not a' if unregistered == 1 else 'are not'} registered "
+                f"migration{'' if unregistered == 1 else 's'}.",
+            )
+            if fail_on_unregistered:
+                code = _UNREGISTERED
+        if list_migrations:
+            rows = [
+                [escape(each.version), "not migrated", escape(each.description)]
+                for each in status.new
+            ]
+            rows += [
+                [escape(each.version), "migrated, not available", ""]
+                for each in status.executed_unavailable
+            ]
+            io.table(["Migration Versions", "Status", "Description"], rows)
+        return code

xtr_orm/command/migrations_version_command.py

@@ -0,0 +1,89 @@
+"""``orm:migrations:version``: record revisions as applied or not, without running them."""
+
+from __future__ import annotations
+
+from typing import Annotated, final
+
+from xtr_console import ConsoleStyle, ExitCode, Option, as_command, escape
+
+from xtr_orm.exception import MigrationError
+
+from .connection_command import ConnectionCommand
+
+__all__ = ["MigrationsVersionCommand"]
+
+
+@as_command("orm:migrations:version")
+@final
+class MigrationsVersionCommand(ConnectionCommand):
+    """Manually add and delete migration versions from the version table."""
+
+    __slots__ = ()
+
+    async def __call__(  # noqa: PLR0911 — each way out says why it stopped
+        self,
+        io: ConsoleStyle,
+        version: str | None = None,
+        *,
+        add: bool = False,
+        delete: bool = False,
+        all_versions: Annotated[bool, Option(name="--all")] = False,
+        connection: str | None = None,
+    ) -> int:
+        """Record the version as applied (--add) or not (--delete), running nothing.
+
+        Adding, the revision must follow only applied ones; deleting, no
+        applied revision may follow it. An applied revision whose file is gone
+        can always be deleted. With --all, every revision is added, or every
+        record deleted.
+
+        Args:
+            io: Where the command writes.
+            version: The revision to record, by full or partial id.
+            add: Record it as applied.
+            delete: Record it as not applied.
+            all_versions: Every revision, instead of one.
+            connection: The connection to record on; the default one when left
+                out.
+        """
+        if add == delete:
+            io.error(
+                "You must specify whether you want to --add or --delete the specified version."
+            )
+            return ExitCode.INVALID
+        if (version is None) == (not all_versions):
+            io.error("You must specify the version or use the --all argument, not both.")
+            return ExitCode.INVALID
+        migrator = await self._migrator(io, connection)
+        if migrator is None:
+            return ExitCode.FAILURE
+        if not io.confirm(
+            "WARNING! You are about to add, delete or synchronize migration versions from the "
+            "version table that could result in data lost. Are you sure you wish to continue?",
+            default=True,
+        ):
+            io.error("Migration cancelled!")
+            return ExitCode.FAILURE
+        try:
+            if add:
+                done = await (
+                    migrator.add_versions([version])
+                    if version is not None
+                    else migrator.add_all_versions()
+                )
+            elif version is not None:
+                done = await migrator.delete_versions([version])
+            else:
+                await migrator.delete_all_versions()
+                io.success("Every version was deleted from the version table.")
+                return ExitCode.SUCCESS
+        except MigrationError as error:
+            io.error(escape(error.reason))
+            return ExitCode.FAILURE
+        verb = "Added" if add else "Deleted"
+        for each in done:
+            io.text(f"  {verb} {escape(each)}")
+        plural = "" if len(done) == 1 else "s"
+        where = "to" if add else "from"
+        io.success(f"{verb} {len(done)} version{plural} {where} the version table.")
+        return ExitCode.SUCCESS