xtr-orm 5.1.0__tar.gz → 5.2.0__tar.gz

{xtr_orm-5.1.0 → xtr_orm-5.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-orm
-Version: 5.1.0
+Version: 5.2.0
 Summary: Databases for async applications: engines, sessions and versioned schema migrations, configured once per connection.
 Keywords: orm,database,migrations,sqlalchemy,alembic,asyncio
 Author: Xterr
@@ -204,8 +204,9 @@ removing it undoes.
   the [message bus middleware](#message-bus-middleware).
 - **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate*, *Configure* and
   *Environment* steps below: it lists `OrmBundle`, writes a starting `<app>/config/packages/orm.py` with the
-  `default` connection, and `DATABASE_URL` in `.env`. It prints the middleware step, which a recipe
-  cannot make for you.
+  `default` connection, and `DATABASE_URL` in `.env`, and adds a PostgreSQL `database` service to
+  `compose.yaml`, published on `5432` in `compose.override.yaml`. It prints the middleware step,
+  which a recipe cannot make for you.
 - **Activate** — `OrmBundle: {"all": True}` in `BUNDLES` in `<app>/config/bundles.py`, imported from
   `xtr_orm.bundle`.
 - **Brings along** — the logging and console bundles, when those packages are installed.
@@ -218,10 +219,14 @@ removing it undoes.
   [Kernel / bundle](#kernel--bundle).
 - **Environment** — `DATABASE_URL`, read when a connection is first used — engine, session,
   migrator or command — not when the application boots. Its query may carry options; see
-  [Options in the URL](#options-in-the-url).
+  [Options in the URL](#options-in-the-url). The recipe's value reaches the `database` service
+  `docker compose up -d database` starts; the `POSTGRES_*` variables that service reads, set in
+  the shell or `.env`, change its version, database, user and password — keep `DATABASE_URL` in
+  step with them.
 - **Ignore** — nothing: commit `migrations/`.
 - **Remove** — take the `orm_*` entries out of every bus's `middleware`, drop the `BUNDLES`
-  entry, delete `<app>/config/packages/orm.py`, then `uv remove xtr-orm`.
+  entry, delete `<app>/config/packages/orm.py` and the `xtr-orm` blocks in `compose.yaml` and
+  `compose.override.yaml`, then `uv remove xtr-orm`.
 - **Check** — `debug:bundles` shows `orm` as `listed` and `active`, and
   `orm:migrations:status` reaches the database.
 

{xtr_orm-5.1.0 → xtr_orm-5.2.0}/README.md

@@ -172,8 +172,9 @@ removing it undoes.
   the [message bus middleware](#message-bus-middleware).
 - **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate*, *Configure* and
   *Environment* steps below: it lists `OrmBundle`, writes a starting `<app>/config/packages/orm.py` with the
-  `default` connection, and `DATABASE_URL` in `.env`. It prints the middleware step, which a recipe
-  cannot make for you.
+  `default` connection, and `DATABASE_URL` in `.env`, and adds a PostgreSQL `database` service to
+  `compose.yaml`, published on `5432` in `compose.override.yaml`. It prints the middleware step,
+  which a recipe cannot make for you.
 - **Activate** — `OrmBundle: {"all": True}` in `BUNDLES` in `<app>/config/bundles.py`, imported from
   `xtr_orm.bundle`.
 - **Brings along** — the logging and console bundles, when those packages are installed.
@@ -186,10 +187,14 @@ removing it undoes.
   [Kernel / bundle](#kernel--bundle).
 - **Environment** — `DATABASE_URL`, read when a connection is first used — engine, session,
   migrator or command — not when the application boots. Its query may carry options; see
-  [Options in the URL](#options-in-the-url).
+  [Options in the URL](#options-in-the-url). The recipe's value reaches the `database` service
+  `docker compose up -d database` starts; the `POSTGRES_*` variables that service reads, set in
+  the shell or `.env`, change its version, database, user and password — keep `DATABASE_URL` in
+  step with them.
 - **Ignore** — nothing: commit `migrations/`.
 - **Remove** — take the `orm_*` entries out of every bus's `middleware`, drop the `BUNDLES`
-  entry, delete `<app>/config/packages/orm.py`, then `uv remove xtr-orm`.
+  entry, delete `<app>/config/packages/orm.py` and the `xtr-orm` blocks in `compose.yaml` and
+  `compose.override.yaml`, then `uv remove xtr-orm`.
 - **Check** — `debug:bundles` shows `orm` as `listed` and `active`, and
   `orm:migrations:status` reaches the database.
 

{xtr_orm-5.1.0 → xtr_orm-5.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-orm"
-version = "5.1.0"
+version = "5.2.0"
 description = "Databases for async applications: engines, sessions and versioned schema migrations, configured once per connection."
 readme = "README.md"
 requires-python = ">=3.11"

{xtr_orm-5.1.0 → xtr_orm-5.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-orm"
-version = "5.1.0"
+version = "5.2.0"
 description = "Databases for async applications: engines, sessions and versioned schema migrations, configured once per connection."
 readme = "README.md"
 requires-python = ">=3.11"

xtr_orm-5.2.0/src/xtr_orm/recipe/manifest.toml

@@ -0,0 +1,66 @@
+# The recipe for xtr-orm: what *Use in an application* in the README takes, as
+# data. Keep the two in step — the README is the source.
+
+[bundles]
+# "<module>:<class>" = the environments it is listed with, exactly as in BUNDLES.
+"xtr_orm.bundle:OrmBundle" = { all = true }
+
+[files]
+# Destination under the application package = template under this recipe.
+# The default connection on DATABASE_URL, written out so the application has
+# one place to add replicas, connections and its models' metadata.
+"config/packages/orm.py" = "files/config/orm.py.tmpl"
+
+[env]
+# Read when a connection is first used — engine, session, migrator or command —
+# not when the application boots. The PostgreSQL compose.yaml runs, for the
+# postgres extra the README installs; change it, or put the real one in
+# .env.local.
+DATABASE_URL = "postgresql+asyncpg://app:!ChangeMe!@127.0.0.1:5432/app"
+
+[gitignore]
+# Nothing: migrations/ is committed.
+lines = []
+
+# A PostgreSQL for DATABASE_URL to reach: `docker compose up -d database`.
+# Kept verbatim: ${...} is Compose's own interpolation, read from the shell or .env.
+[compose."compose.yaml"]
+services = '''
+  database:
+    image: postgres:${POSTGRES_VERSION:-16}-alpine
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-app}
+      # You should definitely change the password in production
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-!ChangeMe!}
+      POSTGRES_USER: ${POSTGRES_USER:-app}
+    healthcheck:
+      test: ["CMD", "pg_isready", "-d", "${POSTGRES_DB:-app}", "-U", "${POSTGRES_USER:-app}"]
+      timeout: 5s
+      retries: 5
+      start_period: 60s
+    volumes:
+      - database_data:/var/lib/postgresql/data:rw
+      # You may use a bind-mounted host directory instead, so that it is harder to accidentally remove the volume and lose all your data!
+      # - ./docker/db/data:/var/lib/postgresql/data:rw
+'''
+volumes = '''
+  database_data:
+'''
+
+# Development only: the database published on the port DATABASE_URL names.
+[compose."compose.override.yaml"]
+services = '''
+  database:
+    ports:
+      - "5432:5432"
+'''
+
+[notes]
+steps = [
+  "With the messenger bundle active, list the orm_* middleware in every bus's middleware: every message is then a unit of work.",
+]
+check = [
+  "<script> debug:bundles — orm is listed and active",
+  "<script> orm:migrations:status — it reaches the database",
+]
+run = ["docker compose up -d database — the PostgreSQL DATABASE_URL points at"]

xtr_orm-5.1.0/src/xtr_orm/recipe/manifest.toml

@@ -1,32 +0,0 @@
-# The recipe for xtr-orm: what *Use in an application* in the README takes, as
-# data. Keep the two in step — the README is the source.
-
-[bundles]
-# "<module>:<class>" = the environments it is listed with, exactly as in BUNDLES.
-"xtr_orm.bundle:OrmBundle" = { all = true }
-
-[files]
-# Destination under the application package = template under this recipe.
-# The default connection on DATABASE_URL, written out so the application has
-# one place to add replicas, connections and its models' metadata.
-"config/packages/orm.py" = "files/config/orm.py.tmpl"
-
-[env]
-# Read when a connection is first used — engine, session, migrator or command —
-# not when the application boots. A local PostgreSQL to start from, for the
-# postgres extra the README installs; change it, or put the real one in
-# .env.local.
-DATABASE_URL = "postgresql+asyncpg://app:change-me@127.0.0.1:5432/app"
-
-[gitignore]
-# Nothing: migrations/ is committed.
-lines = []
-
-[notes]
-steps = [
-  "With the messenger bundle active, list the orm_* middleware in every bus's middleware: every message is then a unit of work.",
-]
-check = [
-  "<script> debug:bundles — orm is listed and active",
-  "<script> orm:migrations:status — it reaches the database",
-]