pg-quaestor 0.1.0__tar.gz

pg_quaestor-0.1.0/LICENSE

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

pg_quaestor-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: pg-quaestor
+Version: 0.1.0
+Summary: Lightweight PostgreSQL migration module with named migrations and dependency resolution
+Author-email: Kristof Csillag <kristof.csillag@deai-labs.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/deai-network/pg-quaestor
+Project-URL: Repository, https://github.com/deai-network/pg-quaestor
+Project-URL: Issues, https://github.com/deai-network/pg-quaestor/issues
+Keywords: postgresql,postgres,asyncpg,migration,async,asyncio,schema
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asyncpg>=0.29
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# pg-quaestor
+
+*In ancient Rome, a **quaestor** was the official in charge of the treasury — here, it manages your PostgreSQL schema and data, your real treasure.*
+
+Lightweight PostgreSQL migration module with named migrations and dependency resolution.
+
+## Install
+
+```bash
+pip install pg-quaestor
+```
+
+## Quick Start
+
+```python
+import asyncio
+
+import asyncpg
+from pg_quaestor import MigrationRegistry
+
+registry = MigrationRegistry()
+
+
+@registry.register("create_users")
+async def create_users(conn):
+    await conn.execute("CREATE TABLE users (email text PRIMARY KEY)")
+
+
+@registry.register("add_status", depends_on=["create_users"])
+async def add_status(conn):
+    await conn.execute(
+        "ALTER TABLE users ADD COLUMN status text NOT NULL DEFAULT 'active'"
+    )
+
+
+async def main():
+    conn = await asyncpg.connect("postgresql://localhost/myapp")
+    applied = await registry.run(conn, "myapp")
+    print(f"Applied migrations: {applied}")
+    await conn.close()
+
+
+asyncio.run(main())
+```
+
+## API Reference
+
+| Symbol | Signature | Description |
+|--------|-----------|-------------|
+| `MigrationRegistry()` | `MigrationRegistry()` | Create a new registry. No arguments. |
+| `.register()` | `register(name: str, depends_on: list[str] \| None = None) -> Callable` | Decorator. Registers an async migration function. |
+| `.run()` | `async run(conn: asyncpg.Connection, prefix: str) -> list[str]` | Execute all unapplied migrations. Returns names applied in this call. |
+| `.migrations` | `migrations -> dict[str, MigrationDefinition]` | The registry's own mapping. |
+
+`MigrationDefinition` is not exported from `pg_quaestor`. A migration function is `async def migration(conn: asyncpg.Connection) -> None`. Pass a connection. Taking one from a pool is the caller's job.
+
+## How It Works
+
+- Applied migrations are tracked in `{prefix}_migrations` in the schema named by the connection's `search_path`. The library does not change `search_path`.
+- `prefix` is a bare identifier of 1 to 52 characters (`[A-Za-z_][A-Za-z0-9_]*`). The table name is quoted, so `MyApp` stays `MyApp_migrations`.
+- Each row stores `name` (text, primary key) and `applied_at` (timestamptz, UTC, set by the runner).
+- Each migration runs in one transaction on that connection. The runner inserts the tracking row in the same transaction and commits. A raised exception rolls the migration's SQL and the tracking row back together. Migrations already committed in that run stay applied. The next `run` retries the failed one.
+- The migration must not `COMMIT`, `ROLLBACK`, or close the connection. The runner does not detect a migration that does.
+- `CREATE INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `VACUUM`, `REINDEX CONCURRENTLY`, and `CREATE DATABASE` are outside this version. There is no flag to run a migration outside a transaction.
+- `run` raises `ValueError` if the connection is already inside a transaction.
+- A session advisory lock on `hashtextextended(prefix, 0)` is held for the run, so two runners for the same prefix take turns. Different prefixes lock independently.
+- Dependencies are resolved with Kahn's algorithm. A missing or circular dependency raises `ValueError` and applies nothing further. Independent migrations run in alphabetical order.
+- Several registries share one database by using different prefixes.
+- Requires PostgreSQL 11 or newer.
+- Progress and errors are logged to the `pg_quaestor` logger.

pg_quaestor-0.1.0/README.md

@@ -0,0 +1,70 @@
+# pg-quaestor
+
+*In ancient Rome, a **quaestor** was the official in charge of the treasury — here, it manages your PostgreSQL schema and data, your real treasure.*
+
+Lightweight PostgreSQL migration module with named migrations and dependency resolution.
+
+## Install
+
+```bash
+pip install pg-quaestor
+```
+
+## Quick Start
+
+```python
+import asyncio
+
+import asyncpg
+from pg_quaestor import MigrationRegistry
+
+registry = MigrationRegistry()
+
+
+@registry.register("create_users")
+async def create_users(conn):
+    await conn.execute("CREATE TABLE users (email text PRIMARY KEY)")
+
+
+@registry.register("add_status", depends_on=["create_users"])
+async def add_status(conn):
+    await conn.execute(
+        "ALTER TABLE users ADD COLUMN status text NOT NULL DEFAULT 'active'"
+    )
+
+
+async def main():
+    conn = await asyncpg.connect("postgresql://localhost/myapp")
+    applied = await registry.run(conn, "myapp")
+    print(f"Applied migrations: {applied}")
+    await conn.close()
+
+
+asyncio.run(main())
+```
+
+## API Reference
+
+| Symbol | Signature | Description |
+|--------|-----------|-------------|
+| `MigrationRegistry()` | `MigrationRegistry()` | Create a new registry. No arguments. |
+| `.register()` | `register(name: str, depends_on: list[str] \| None = None) -> Callable` | Decorator. Registers an async migration function. |
+| `.run()` | `async run(conn: asyncpg.Connection, prefix: str) -> list[str]` | Execute all unapplied migrations. Returns names applied in this call. |
+| `.migrations` | `migrations -> dict[str, MigrationDefinition]` | The registry's own mapping. |
+
+`MigrationDefinition` is not exported from `pg_quaestor`. A migration function is `async def migration(conn: asyncpg.Connection) -> None`. Pass a connection. Taking one from a pool is the caller's job.
+
+## How It Works
+
+- Applied migrations are tracked in `{prefix}_migrations` in the schema named by the connection's `search_path`. The library does not change `search_path`.
+- `prefix` is a bare identifier of 1 to 52 characters (`[A-Za-z_][A-Za-z0-9_]*`). The table name is quoted, so `MyApp` stays `MyApp_migrations`.
+- Each row stores `name` (text, primary key) and `applied_at` (timestamptz, UTC, set by the runner).
+- Each migration runs in one transaction on that connection. The runner inserts the tracking row in the same transaction and commits. A raised exception rolls the migration's SQL and the tracking row back together. Migrations already committed in that run stay applied. The next `run` retries the failed one.
+- The migration must not `COMMIT`, `ROLLBACK`, or close the connection. The runner does not detect a migration that does.
+- `CREATE INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `VACUUM`, `REINDEX CONCURRENTLY`, and `CREATE DATABASE` are outside this version. There is no flag to run a migration outside a transaction.
+- `run` raises `ValueError` if the connection is already inside a transaction.
+- A session advisory lock on `hashtextextended(prefix, 0)` is held for the run, so two runners for the same prefix take turns. Different prefixes lock independently.
+- Dependencies are resolved with Kahn's algorithm. A missing or circular dependency raises `ValueError` and applies nothing further. Independent migrations run in alphabetical order.
+- Several registries share one database by using different prefixes.
+- Requires PostgreSQL 11 or newer.
+- Progress and errors are logged to the `pg_quaestor` logger.

pg_quaestor-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pg-quaestor"
+version = "0.1.0"
+description = "Lightweight PostgreSQL migration module with named migrations and dependency resolution"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Kristof Csillag", email = "kristof.csillag@deai-labs.com" },
+]
+keywords = ["postgresql", "postgres", "asyncpg", "migration", "async", "asyncio", "schema"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+dependencies = [
+    "asyncpg>=0.29",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "build>=1.2",
+    "twine>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/deai-network/pg-quaestor"
+Repository = "https://github.com/deai-network/pg-quaestor"
+Issues = "https://github.com/deai-network/pg-quaestor/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pg_quaestor = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

pg_quaestor-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pg_quaestor-0.1.0/src/pg_quaestor/__init__.py

@@ -0,0 +1,5 @@
+"""Quaestor — lightweight PostgreSQL migration module."""
+
+from pg_quaestor.registry import MigrationRegistry
+
+__all__ = ["MigrationRegistry"]

pg_quaestor-0.1.0/src/pg_quaestor/registry.py

@@ -0,0 +1,51 @@
+"""MigrationRegistry — collects and registers migration definitions."""
+
+from dataclasses import dataclass, field
+from typing import Awaitable, Callable
+
+import asyncpg
+
+from pg_quaestor.runner import run_migrations
+
+
+@dataclass
+class MigrationDefinition:
+    """A single migration definition."""
+
+    name: str
+    execute: Callable[[asyncpg.Connection], Awaitable[None]]
+    depends_on: list[str] = field(default_factory=list)
+
+
+class MigrationRegistry:
+    """Collects migration definitions and runs them against a database."""
+
+    def __init__(self) -> None:
+        self._migrations: dict[str, MigrationDefinition] = {}
+
+    def register(
+        self,
+        name: str,
+        depends_on: list[str] | None = None,
+    ) -> Callable:
+        """Decorator to register a migration function."""
+
+        def decorator(fn: Callable[[asyncpg.Connection], Awaitable[None]]):
+            if name in self._migrations:
+                raise ValueError(f"Migration '{name}' is already registered")
+            self._migrations[name] = MigrationDefinition(
+                name=name,
+                execute=fn,
+                depends_on=depends_on or [],
+            )
+            return fn
+
+        return decorator
+
+    @property
+    def migrations(self) -> dict[str, MigrationDefinition]:
+        return self._migrations
+
+    async def run(self, conn: asyncpg.Connection, prefix: str) -> list[str]:
+        """Run all unapplied migrations. Returns the names applied in this call."""
+        return await run_migrations(conn, prefix, self._migrations)

pg_quaestor-0.1.0/src/pg_quaestor/runner.py

@@ -0,0 +1,131 @@
+"""Migration runner — dependency resolution and execution."""
+
+import logging
+import re
+from datetime import datetime, timezone
+
+import asyncpg
+
+logger = logging.getLogger("pg_quaestor")
+
+_PREFIX = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _quote_ident(prefix: str) -> str:
+    if _PREFIX.fullmatch(prefix) is None or len(prefix) > 52:
+        raise ValueError(
+            f"prefix must be a bare identifier of at most 52 characters, got {prefix!r}"
+        )
+    return '"' + prefix.replace('"', '""') + '_migrations"'
+
+
+# Behavior matches mongo-quaestor src/quaestor/runner.py _topological_sort; keep the two copies in step.
+def _topological_sort(migrations: dict, unapplied: set[str]) -> list[str]:
+    """Topological sort of unapplied migrations respecting depends_on.
+
+    Raises ValueError on circular dependencies or missing dependencies.
+    """
+    all_known = set(migrations.keys())
+    for name, mig in migrations.items():
+        for dep in mig.depends_on:
+            if dep not in all_known:
+                raise ValueError(
+                    f"Migration '{name}' depends on '{dep}', which is not registered"
+                )
+
+    in_degree: dict[str, int] = {name: 0 for name in unapplied}
+    dependents: dict[str, list[str]] = {name: [] for name in unapplied}
+
+    for name in unapplied:
+        for dep in migrations[name].depends_on:
+            if dep in unapplied:
+                in_degree[name] += 1
+                dependents[dep].append(name)
+
+    queue = [name for name in unapplied if in_degree[name] == 0]
+    queue.sort()
+    result = []
+
+    while queue:
+        current = queue.pop(0)
+        result.append(current)
+        for dependent in sorted(dependents[current]):
+            in_degree[dependent] -= 1
+            if in_degree[dependent] == 0:
+                queue.append(dependent)
+            queue.sort()
+
+    if len(result) != len(unapplied):
+        remaining = unapplied - set(result)
+        raise ValueError(
+            f"Circular dependency detected among migrations: {remaining}"
+        )
+
+    return result
+
+
+async def run_migrations(
+    conn: asyncpg.Connection,
+    prefix: str,
+    migrations: dict,
+) -> list[str]:
+    """Run unapplied migrations in dependency order."""
+    table = _quote_ident(prefix)
+    if conn.is_in_transaction():
+        raise ValueError(
+            "run() requires a connection that is not already in a transaction"
+        )
+
+    await conn.execute("SELECT pg_advisory_lock(hashtextextended($1, 0))", prefix)
+    body_error = None
+    try:
+        try:
+            await conn.execute(
+                f"CREATE TABLE IF NOT EXISTS {table} ("
+                "name text PRIMARY KEY, "
+                "applied_at timestamptz NOT NULL)"
+            )
+            rows = await conn.fetch(f"SELECT name FROM {table}")
+            applied = {row["name"] for row in rows}
+            unapplied = set(migrations.keys()) - applied
+            if not unapplied:
+                logger.info(
+                    f"[{prefix}] All {len(migrations)} migrations already applied"
+                )
+                return []
+
+            ordered = _topological_sort(migrations, unapplied)
+            logger.info(f"[{prefix}] {len(ordered)} migrations to apply: {ordered}")
+
+            applied_now = []
+            for name in ordered:
+                mig = migrations[name]
+                logger.info(f"[{prefix}] Applying migration: {name}")
+                try:
+                    async with conn.transaction():
+                        await mig.execute(conn)
+                        await conn.execute(
+                            f"INSERT INTO {table} (name, applied_at) VALUES ($1, $2)",
+                            name,
+                            datetime.now(timezone.utc),
+                        )
+                except Exception as e:
+                    logger.error(f"[{prefix}] Migration '{name}' failed: {e}")
+                    raise
+                applied_now.append(name)
+                logger.info(f"[{prefix}] Migration '{name}' applied successfully")
+
+            return applied_now
+        except Exception as e:
+            body_error = e
+            raise
+    finally:
+        try:
+            await conn.execute(
+                "SELECT pg_advisory_unlock(hashtextextended($1, 0))",
+                prefix,
+            )
+        except Exception as unlock_error:
+            logger.error(f"[{prefix}] Failed to release advisory lock: {unlock_error}")
+            if body_error is None:
+                raise

pg_quaestor-0.1.0/src/pg_quaestor.egg-info/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: pg-quaestor
+Version: 0.1.0
+Summary: Lightweight PostgreSQL migration module with named migrations and dependency resolution
+Author-email: Kristof Csillag <kristof.csillag@deai-labs.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/deai-network/pg-quaestor
+Project-URL: Repository, https://github.com/deai-network/pg-quaestor
+Project-URL: Issues, https://github.com/deai-network/pg-quaestor/issues
+Keywords: postgresql,postgres,asyncpg,migration,async,asyncio,schema
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asyncpg>=0.29
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# pg-quaestor
+
+*In ancient Rome, a **quaestor** was the official in charge of the treasury — here, it manages your PostgreSQL schema and data, your real treasure.*
+
+Lightweight PostgreSQL migration module with named migrations and dependency resolution.
+
+## Install
+
+```bash
+pip install pg-quaestor
+```
+
+## Quick Start
+
+```python
+import asyncio
+
+import asyncpg
+from pg_quaestor import MigrationRegistry
+
+registry = MigrationRegistry()
+
+
+@registry.register("create_users")
+async def create_users(conn):
+    await conn.execute("CREATE TABLE users (email text PRIMARY KEY)")
+
+
+@registry.register("add_status", depends_on=["create_users"])
+async def add_status(conn):
+    await conn.execute(
+        "ALTER TABLE users ADD COLUMN status text NOT NULL DEFAULT 'active'"
+    )
+
+
+async def main():
+    conn = await asyncpg.connect("postgresql://localhost/myapp")
+    applied = await registry.run(conn, "myapp")
+    print(f"Applied migrations: {applied}")
+    await conn.close()
+
+
+asyncio.run(main())
+```
+
+## API Reference
+
+| Symbol | Signature | Description |
+|--------|-----------|-------------|
+| `MigrationRegistry()` | `MigrationRegistry()` | Create a new registry. No arguments. |
+| `.register()` | `register(name: str, depends_on: list[str] \| None = None) -> Callable` | Decorator. Registers an async migration function. |
+| `.run()` | `async run(conn: asyncpg.Connection, prefix: str) -> list[str]` | Execute all unapplied migrations. Returns names applied in this call. |
+| `.migrations` | `migrations -> dict[str, MigrationDefinition]` | The registry's own mapping. |
+
+`MigrationDefinition` is not exported from `pg_quaestor`. A migration function is `async def migration(conn: asyncpg.Connection) -> None`. Pass a connection. Taking one from a pool is the caller's job.
+
+## How It Works
+
+- Applied migrations are tracked in `{prefix}_migrations` in the schema named by the connection's `search_path`. The library does not change `search_path`.
+- `prefix` is a bare identifier of 1 to 52 characters (`[A-Za-z_][A-Za-z0-9_]*`). The table name is quoted, so `MyApp` stays `MyApp_migrations`.
+- Each row stores `name` (text, primary key) and `applied_at` (timestamptz, UTC, set by the runner).
+- Each migration runs in one transaction on that connection. The runner inserts the tracking row in the same transaction and commits. A raised exception rolls the migration's SQL and the tracking row back together. Migrations already committed in that run stay applied. The next `run` retries the failed one.
+- The migration must not `COMMIT`, `ROLLBACK`, or close the connection. The runner does not detect a migration that does.
+- `CREATE INDEX CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `VACUUM`, `REINDEX CONCURRENTLY`, and `CREATE DATABASE` are outside this version. There is no flag to run a migration outside a transaction.
+- `run` raises `ValueError` if the connection is already inside a transaction.
+- A session advisory lock on `hashtextextended(prefix, 0)` is held for the run, so two runners for the same prefix take turns. Different prefixes lock independently.
+- Dependencies are resolved with Kahn's algorithm. A missing or circular dependency raises `ValueError` and applies nothing further. Independent migrations run in alphabetical order.
+- Several registries share one database by using different prefixes.
+- Requires PostgreSQL 11 or newer.
+- Progress and errors are logged to the `pg_quaestor` logger.

pg_quaestor-0.1.0/src/pg_quaestor.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/pg_quaestor/__init__.py
+src/pg_quaestor/py.typed
+src/pg_quaestor/registry.py
+src/pg_quaestor/runner.py
+src/pg_quaestor.egg-info/PKG-INFO
+src/pg_quaestor.egg-info/SOURCES.txt
+src/pg_quaestor.egg-info/dependency_links.txt
+src/pg_quaestor.egg-info/requires.txt
+src/pg_quaestor.egg-info/top_level.txt
+tests/test_registry.py
+tests/test_runner.py

pg_quaestor-0.1.0/src/pg_quaestor.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pg_quaestor-0.1.0/src/pg_quaestor.egg-info/requires.txt

@@ -0,0 +1,7 @@
+asyncpg>=0.29
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.23
+build>=1.2
+twine>=5.0

pg_quaestor-0.1.0/src/pg_quaestor.egg-info/top_level.txt

@@ -0,0 +1 @@
+pg_quaestor

pg_quaestor-0.1.0/tests/test_registry.py

@@ -0,0 +1,47 @@
+"""Tests for MigrationRegistry."""
+
+import pytest
+
+from pg_quaestor import MigrationRegistry
+
+
+def test_register_migration():
+    reg = MigrationRegistry()
+
+    async def first(conn):
+        pass
+
+    registered = reg.register("first")(first)
+
+    assert registered is first
+    assert "first" in reg.migrations
+    assert reg.migrations["first"].name == "first"
+    assert reg.migrations["first"].depends_on == []
+    assert reg.migrations["first"].execute is first
+
+
+def test_register_with_dependencies():
+    reg = MigrationRegistry()
+
+    @reg.register("base")
+    async def base(conn):
+        pass
+
+    @reg.register("dependent", depends_on=["base"])
+    async def dependent(conn):
+        pass
+
+    assert reg.migrations["dependent"].depends_on == ["base"]
+
+
+def test_duplicate_name_raises():
+    reg = MigrationRegistry()
+
+    @reg.register("dup")
+    async def first(conn):
+        pass
+
+    with pytest.raises(ValueError, match="already registered"):
+        @reg.register("dup")
+        async def second(conn):
+            pass

pg_quaestor-0.1.0/tests/test_runner.py

@@ -0,0 +1,404 @@
+"""Tests for the migration runner."""
+
+import asyncio
+from datetime import datetime, timezone
+
+import pytest
+
+from pg_quaestor import MigrationRegistry
+
+
+async def test_run_applies_migrations(pg):
+    reg = MigrationRegistry()
+    log = []
+
+    @reg.register("m1")
+    async def m1(conn):
+        log.append("m1")
+        await conn.execute("CREATE TABLE from_m1 (id int)")
+
+    @reg.register("m2")
+    async def m2(conn):
+        log.append("m2")
+        await conn.execute("CREATE TABLE from_m2 (id int)")
+
+    applied = await reg.run(pg.conn, "test")
+    assert applied == ["m1", "m2"]
+    assert log == ["m1", "m2"]
+
+    rows = await pg.conn.fetch('SELECT name, applied_at FROM "test_migrations" ORDER BY name')
+    assert [row["name"] for row in rows] == ["m1", "m2"]
+    assert all(row["applied_at"].tzinfo is not None for row in rows)
+
+
+async def test_run_skips_already_applied(pg):
+    reg = MigrationRegistry()
+    run_count = {"m1": 0}
+
+    @reg.register("m1")
+    async def m1(conn):
+        run_count["m1"] += 1
+
+    await reg.run(pg.conn, "test")
+    applied = await reg.run(pg.conn, "test")
+    assert applied == []
+    assert run_count["m1"] == 1
+
+
+async def test_run_respects_dependencies(pg):
+    reg = MigrationRegistry()
+    log = []
+
+    @reg.register("base")
+    async def base(conn):
+        log.append("base")
+
+    @reg.register("child", depends_on=["base"])
+    async def child(conn):
+        log.append("child")
+
+    @reg.register("grandchild", depends_on=["child"])
+    async def grandchild(conn):
+        log.append("grandchild")
+
+    applied = await reg.run(pg.conn, "test")
+    assert log == ["base", "child", "grandchild"]
+    assert applied == ["base", "child", "grandchild"]
+
+
+async def test_run_partial_dependencies_already_applied(pg):
+    reg = MigrationRegistry()
+    log = []
+
+    @reg.register("base")
+    async def base(conn):
+        log.append("base")
+
+    @reg.register("child", depends_on=["base"])
+    async def child(conn):
+        log.append("child")
+
+    await pg.conn.execute(
+        "CREATE TABLE test_migrations ("
+        "name text PRIMARY KEY, applied_at timestamptz NOT NULL)"
+    )
+    await pg.conn.execute(
+        "INSERT INTO test_migrations (name, applied_at) VALUES ($1, $2)",
+        "base",
+        datetime.now(timezone.utc),
+    )
+
+    applied = await reg.run(pg.conn, "test")
+    assert applied == ["child"]
+    assert log == ["child"]
+
+
+async def test_run_circular_dependency_raises(pg):
+    reg = MigrationRegistry()
+
+    @reg.register("a", depends_on=["b"])
+    async def a(conn):
+        pass
+
+    @reg.register("b", depends_on=["a"])
+    async def b(conn):
+        pass
+
+    with pytest.raises(ValueError, match="Circular dependency"):
+        await reg.run(pg.conn, "test")
+
+
+async def test_run_missing_dependency_raises(pg):
+    reg = MigrationRegistry()
+
+    @reg.register("orphan", depends_on=["nonexistent"])
+    async def orphan(conn):
+        pass
+
+    with pytest.raises(ValueError, match="not registered"):
+        await reg.run(pg.conn, "test")
+
+
+async def test_run_failed_migration_rolls_back(pg):
+    reg = MigrationRegistry()
+
+    @reg.register("good")
+    async def good(conn):
+        await conn.execute("CREATE TABLE good_t (id int)")
+        await conn.execute("INSERT INTO good_t (id) VALUES (1)")
+
+    @reg.register("bad", depends_on=["good"])
+    async def bad(conn):
+        await conn.execute("INSERT INTO good_t (id) VALUES (2)")
+        await conn.execute("CREATE TABLE bad_t (id int)")
+        raise RuntimeError("intentional failure")
+
+    with pytest.raises(RuntimeError, match="intentional failure"):
+        await reg.run(pg.conn, "test")
+
+    tables = {
+        row["tablename"]
+        for row in await pg.conn.fetch(
+            "SELECT tablename FROM pg_tables WHERE schemaname = $1",
+            pg.schema,
+        )
+    }
+    assert "good_t" in tables
+    assert "bad_t" not in tables
+    ids = [row["id"] for row in await pg.conn.fetch("SELECT id FROM good_t ORDER BY id")]
+    assert ids == [1]
+    names = {row["name"] for row in await pg.conn.fetch('SELECT name FROM "test_migrations"')}
+    assert names == {"good"}
+
+
+async def test_run_retry_after_failure(pg):
+    reg = MigrationRegistry()
+    attempt = {"count": 0}
+
+    @reg.register("flaky")
+    async def flaky(conn):
+        attempt["count"] += 1
+        if attempt["count"] == 1:
+            raise RuntimeError("first attempt fails")
+
+    with pytest.raises(RuntimeError, match="first attempt fails"):
+        await reg.run(pg.conn, "test")
+
+    applied = await reg.run(pg.conn, "test")
+    assert applied == ["flaky"]
+    assert attempt["count"] == 2
+
+
+async def test_run_with_prefix_isolation(pg):
+    reg1 = MigrationRegistry()
+    reg2 = MigrationRegistry()
+
+    @reg1.register("m1")
+    async def m1(conn):
+        pass
+
+    @reg2.register("m1")
+    async def m1_other(conn):
+        pass
+
+    await reg1.run(pg.conn, "alpha")
+    await reg2.run(pg.conn, "beta")
+
+    alpha = await pg.conn.fetch('SELECT name FROM "alpha_migrations"')
+    beta = await pg.conn.fetch('SELECT name FROM "beta_migrations"')
+    assert len(alpha) == 1
+    assert len(beta) == 1
+
+
+async def test_run_parallel_independent_migrations(pg):
+    reg = MigrationRegistry()
+    log = []
+
+    @reg.register("charlie")
+    async def charlie(conn):
+        log.append("charlie")
+
+    @reg.register("alpha")
+    async def alpha(conn):
+        log.append("alpha")
+
+    @reg.register("bravo")
+    async def bravo(conn):
+        log.append("bravo")
+
+    await reg.run(pg.conn, "test")
+    assert log == ["alpha", "bravo", "charlie"]
+
+
+async def test_run_diamond_dependency(pg):
+    reg = MigrationRegistry()
+    log = []
+
+    @reg.register("root")
+    async def root(conn):
+        log.append("root")
+
+    @reg.register("left", depends_on=["root"])
+    async def left(conn):
+        log.append("left")
+
+    @reg.register("right", depends_on=["root"])
+    async def right(conn):
+        log.append("right")
+
+    @reg.register("bottom", depends_on=["left", "right"])
+    async def bottom(conn):
+        log.append("bottom")
+
+    await reg.run(pg.conn, "test")
+    assert log == ["root", "left", "right", "bottom"]
+
+
+async def test_run_empty_registry_creates_table(pg):
+    reg = MigrationRegistry()
+    assert await reg.run(pg.conn, "test") == []
+    rows = await pg.conn.fetch(
+        "SELECT tablename FROM pg_tables WHERE schemaname = $1 AND tablename = $2",
+        pg.schema,
+        "test_migrations",
+    )
+    assert len(rows) == 1
+
+
+async def test_run_migration_name_is_data(pg):
+    reg = MigrationRegistry()
+    name = 'say "hi"'
+
+    @reg.register(name)
+    async def say(conn):
+        pass
+
+    assert await reg.run(pg.conn, "test") == [name]
+    rows = await pg.conn.fetch('SELECT name FROM "test_migrations"')
+    assert [row["name"] for row in rows] == [name]
+    assert await reg.run(pg.conn, "test") == []
+
+
+async def test_run_prefix_case_is_preserved(pg):
+    reg = MigrationRegistry()
+
+    @reg.register("m")
+    async def m(conn):
+        pass
+
+    assert await reg.run(pg.conn, "MyApp") == ["m"]
+    rows = await pg.conn.fetch(
+        "SELECT tablename FROM pg_tables WHERE schemaname = $1 AND tablename = $2",
+        pg.schema,
+        "MyApp_migrations",
+    )
+    assert len(rows) == 1
+    stored = await pg.conn.fetch('SELECT name FROM "MyApp_migrations"')
+    assert [row["name"] for row in stored] == ["m"]
+
+
+@pytest.mark.parametrize(
+    "prefix",
+    ["", "a-b", "1abc", "has space", "a" * 53, '"users"'],
+)
+async def test_run_rejects_bad_prefix(pg, prefix):
+    reg = MigrationRegistry()
+
+    @reg.register("m")
+    async def m(conn):
+        pass
+
+    with pytest.raises(ValueError, match="bare identifier"):
+        await reg.run(pg.conn, prefix)
+
+    rows = await pg.conn.fetch(
+        "SELECT tablename FROM pg_tables WHERE schemaname = $1",
+        pg.schema,
+    )
+    assert rows == []
+
+
+async def test_run_prefix_length_bounds(pg):
+    reg = MigrationRegistry()
+
+    @reg.register("m")
+    async def m(conn):
+        pass
+
+    short = "a"
+    long = "a" * 52
+    assert await reg.run(pg.conn, short) == ["m"]
+    assert await reg.run(pg.conn, long) == ["m"]
+    rows = await pg.conn.fetch(
+        "SELECT tablename FROM pg_tables WHERE schemaname = $1 AND tablename = ANY($2)",
+        pg.schema,
+        [short + "_migrations", long + "_migrations"],
+    )
+    assert {row["tablename"] for row in rows} == {
+        short + "_migrations",
+        long + "_migrations",
+    }
+
+
+async def test_run_rejects_open_transaction(pg):
+    reg = MigrationRegistry()
+
+    @reg.register("m")
+    async def m(conn):
+        pass
+
+    async with pg.conn.transaction():
+        with pytest.raises(ValueError, match="not already in a transaction"):
+            await reg.run(pg.conn, "myapp")
+
+    other = await pg.connect()
+    applied = await asyncio.wait_for(reg.run(other, "myapp"), timeout=2)
+    assert applied == ["m"]
+
+
+async def test_run_advisory_lock_serializes(pg):
+    reg = MigrationRegistry()
+    started = asyncio.Event()
+    release = asyncio.Event()
+    calls = {"n": 0}
+
+    @reg.register("m")
+    async def m(conn):
+        calls["n"] += 1
+        started.set()
+        await release.wait()
+
+    other = await pg.connect()
+    first = asyncio.create_task(reg.run(pg.conn, "myapp"))
+    await started.wait()
+    second = asyncio.create_task(reg.run(other, "myapp"))
+    done, pending = await asyncio.wait({second}, timeout=0.5)
+    assert second in pending
+    assert calls["n"] == 1
+    release.set()
+    assert await first == ["m"]
+    assert await second == []
+    assert calls["n"] == 1
+
+
+async def test_run_releases_lock_after_failure(pg):
+    reg = MigrationRegistry()
+    attempt = {"n": 0}
+
+    @reg.register("flaky")
+    async def flaky(conn):
+        attempt["n"] += 1
+        if attempt["n"] == 1:
+            raise RuntimeError("boom")
+
+    with pytest.raises(RuntimeError, match="boom"):
+        await reg.run(pg.conn, "test")
+
+    other = await pg.connect()
+    applied = await asyncio.wait_for(reg.run(other, "test"), timeout=2)
+    assert applied == ["flaky"]
+    assert attempt["n"] == 2
+
+
+async def test_run_lock_is_per_prefix(pg):
+    reg_a = MigrationRegistry()
+    reg_b = MigrationRegistry()
+    started = asyncio.Event()
+    release = asyncio.Event()
+
+    @reg_a.register("held")
+    async def held(conn):
+        started.set()
+        await release.wait()
+
+    @reg_b.register("other")
+    async def other(conn):
+        pass
+
+    conn_b = await pg.connect()
+    task_a = asyncio.create_task(reg_a.run(pg.conn, "alpha"))
+    await started.wait()
+    applied_b = await asyncio.wait_for(reg_b.run(conn_b, "beta"), timeout=2)
+    assert applied_b == ["other"]
+    release.set()
+    assert await task_a == ["held"]