postgres-component 0.1.0__tar.gz

postgres_component-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --all-groups
+      - run: uv run pytest
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .

postgres_component-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "PyPI target"
+        required: true
+        default: "pypi"
+        type: choice
+        options: ["pypi", "testpypi"]
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: ci
+    runs-on: ubuntu-latest
+    environment: ${{ github.event.inputs.target || 'pypi' }}
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: ${{ (github.event.inputs.target == 'testpypi') && 'https://test.pypi.org/legacy/' || '' }}

postgres_component-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.superpowers/
+*.egg-info/
+__pycache__/
+.venv/
+dist/
+uv.lock

postgres_component-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

postgres_component-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release: `PostgresComponent`, `MigrationWiring`, `create_migration_engine`.

postgres_component-0.1.0/CONTEXT.md

@@ -0,0 +1,35 @@
+# postgres-component
+
+Component library for Postgres connection lifecycle, built on python-components'
+`Component` contract. Wraps a SQLAlchemy async engine so it participates in a
+`System`'s dependency graph, without owning schema or query concerns.
+
+## Language
+
+**PostgresComponent**:
+A `Component` that manages a SQLAlchemy async engine's lifecycle — verifies
+connectivity on `start()`, disposes the engine on `shutdown()` — and hands out
+session access to consumers. Owns connection lifecycle only: no models, no
+migrations, no query API of its own.
+_Avoid_: Database component, Postgres client, DB wrapper
+
+**SessionFactory**:
+The raw `async_sessionmaker` exposed by `PostgresComponent` (`session_factory`
+attribute) for callers who need manual control over a session's transaction
+boundaries — long-lived reads, streaming, anything that doesn't fit one
+begin/commit cycle.
+_Avoid_: raw session, sessionmaker, engine session
+
+**Managed Session**:
+The `session()` async context manager `PostgresComponent` exposes: begins a
+transaction, commits on clean exit, rolls back on exception. The default way
+consumers should talk to the database — one call, one unit of work. Distinct
+from a `SessionFactory` session, which commits nothing on its own.
+_Avoid_: session(), auto-commit session, transaction wrapper, unit of work
+
+**Migration Wiring**:
+The optional helper `PostgresComponent` exposes so a consuming app's own
+Alembic `env.py` can reuse the same async engine and driver already
+configured on the component. `PostgresComponent` never runs migrations
+itself — this only removes the boilerplate of re-deriving connection info.
+_Avoid_: auto-migrate, migration runner, schema sync

postgres_component-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabricio Lima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

postgres_component-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: postgres-component
+Version: 0.1.0
+Summary: Async Postgres connection-lifecycle component for python-components
+Project-URL: Homepage, https://github.com/fabriciooml/postgres-component
+Project-URL: Repository, https://github.com/fabriciooml/postgres-component
+Project-URL: Issues, https://github.com/fabriciooml/postgres-component/issues
+Project-URL: Changelog, https://github.com/fabriciooml/postgres-component/blob/main/CHANGELOG.md
+Author: Fabricio Lima
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,asyncpg,postgres,postgresql,python-components,sqlalchemy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: asyncpg<1,>=0.29
+Requires-Dist: fastapi>=0.115
+Requires-Dist: python-components<0.5,>=0.4.0
+Requires-Dist: sqlalchemy[asyncio]<3,>=2.0
+Description-Content-Type: text/markdown
+
+# postgres-component
+
+Async Postgres connection-lifecycle component for [python-components](https://github.com/lucassant95/python-components).
+
+## Install
+
+```bash
+uv add postgres-component
+```
+
+## Requirements
+
+- Python >= 3.11
+- A running Postgres server
+
+## Usage
+
+```python
+import asyncio
+
+from python_components import System
+from postgres_component import PostgresComponent
+
+database = PostgresComponent(url="postgresql+asyncpg://user:pass@localhost:5432/mydb")
+
+system = System({"database": database})
+
+async def main():
+    async with system:
+        async with database.session() as session:
+            await session.execute(...)  # commits on success, rolls back on exception
+
+asyncio.run(main())
+```
+
+`PostgresComponent` can also be built from individual kwargs instead of a URL:
+
+```python
+PostgresComponent(host="localhost", port=5432, user="user", password="pass", database="mydb")
+```
+
+`url` takes priority over the kwargs when both are given.
+
+### Health route
+
+```python
+from fastapi_component import create_app
+
+app = create_app(system)  # RouteProvider discovery adds GET /health automatically
+```
+
+### Migrations
+
+`PostgresComponent` never runs migrations itself. `migration_wiring()` hands your
+own Alembic `env.py` the same connection config so it doesn't have to be
+re-derived:
+
+```python
+# alembic/env.py
+from postgres_component import create_migration_engine
+
+engine = create_migration_engine(database.migration_wiring())
+# use `engine` with Alembic's async run_sync() pattern
+```
+
+## Semantics and caveats
+
+- **Fail-fast startup.** `start()` runs an explicit `SELECT 1` before considering itself connected — a dead database makes `start()` raise rather than "starting" successfully and failing later on first query.
+- **Managed Session is a unit of work.** `database.session()` begins a transaction, commits on clean exit, and rolls back on exception — one call is one unit of work. For manual control (long-lived reads, streaming), use the raw `database.session_factory` directly.
+- **Errors propagate raw.** SQLAlchemy exceptions (`OperationalError`, `IntegrityError`, etc.) are never wrapped; `get_status()["last_error"]` is updated as a string for introspection, but the original exception type always reaches the caller.
+- **No ORM, no migrations.** The component owns connection lifecycle only. Models and Alembic setup belong to the consuming app; `migration_wiring()` only removes the boilerplate of re-deriving connection config.
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pytest
+uv run ruff format --check .
+uv run ruff check .
+```
+
+Integration tests spin up a real Postgres instance via [testcontainers](https://testcontainers.com/modules/postgres/). For local development against a persistent instance instead, run `docker compose up -d`.
+
+## License
+
+MIT

postgres_component-0.1.0/README.md

@@ -0,0 +1,86 @@
+# postgres-component
+
+Async Postgres connection-lifecycle component for [python-components](https://github.com/lucassant95/python-components).
+
+## Install
+
+```bash
+uv add postgres-component
+```
+
+## Requirements
+
+- Python >= 3.11
+- A running Postgres server
+
+## Usage
+
+```python
+import asyncio
+
+from python_components import System
+from postgres_component import PostgresComponent
+
+database = PostgresComponent(url="postgresql+asyncpg://user:pass@localhost:5432/mydb")
+
+system = System({"database": database})
+
+async def main():
+    async with system:
+        async with database.session() as session:
+            await session.execute(...)  # commits on success, rolls back on exception
+
+asyncio.run(main())
+```
+
+`PostgresComponent` can also be built from individual kwargs instead of a URL:
+
+```python
+PostgresComponent(host="localhost", port=5432, user="user", password="pass", database="mydb")
+```
+
+`url` takes priority over the kwargs when both are given.
+
+### Health route
+
+```python
+from fastapi_component import create_app
+
+app = create_app(system)  # RouteProvider discovery adds GET /health automatically
+```
+
+### Migrations
+
+`PostgresComponent` never runs migrations itself. `migration_wiring()` hands your
+own Alembic `env.py` the same connection config so it doesn't have to be
+re-derived:
+
+```python
+# alembic/env.py
+from postgres_component import create_migration_engine
+
+engine = create_migration_engine(database.migration_wiring())
+# use `engine` with Alembic's async run_sync() pattern
+```
+
+## Semantics and caveats
+
+- **Fail-fast startup.** `start()` runs an explicit `SELECT 1` before considering itself connected — a dead database makes `start()` raise rather than "starting" successfully and failing later on first query.
+- **Managed Session is a unit of work.** `database.session()` begins a transaction, commits on clean exit, and rolls back on exception — one call is one unit of work. For manual control (long-lived reads, streaming), use the raw `database.session_factory` directly.
+- **Errors propagate raw.** SQLAlchemy exceptions (`OperationalError`, `IntegrityError`, etc.) are never wrapped; `get_status()["last_error"]` is updated as a string for introspection, but the original exception type always reaches the caller.
+- **No ORM, no migrations.** The component owns connection lifecycle only. Models and Alembic setup belong to the consuming app; `migration_wiring()` only removes the boilerplate of re-deriving connection config.
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pytest
+uv run ruff format --check .
+uv run ruff check .
+```
+
+Integration tests spin up a real Postgres instance via [testcontainers](https://testcontainers.com/modules/postgres/). For local development against a persistent instance instead, run `docker compose up -d`.
+
+## License
+
+MIT

postgres_component-0.1.0/docker-compose.yml

@@ -0,0 +1,9 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: postgres

postgres_component-0.1.0/docs/adr/0001-sqlalchemy-async-with-asyncpg.md

@@ -0,0 +1,34 @@
+---
+status: accepted
+---
+
+# SQLAlchemy async engine with asyncpg, eager connectivity check on start()
+
+postgres-component needs to pick a layer for talking to Postgres. We chose
+**SQLAlchemy's async engine** over a raw driver (asyncpg directly, matching
+kafka-component's raw-`aiokafka` precedent) because it buys ORM mapping and
+Alembic migration tooling for consumers, and the one real Postgres user in
+this codebase (`k9`) already models its data with SQLAlchemy's ORM. Under
+SQLAlchemy we picked **asyncpg** over psycopg3-async as the DBAPI: it's the
+more common pairing in SQLAlchemy's own async docs and examples.
+
+SQLAlchemy engines are lazy by default — no connection opens until first use.
+That breaks the family's documented fail-fast startup contract (a failing
+`start()` rolls back already-started components and aborts the server before
+it serves traffic), so `PostgresComponent.start()` runs an explicit
+connectivity check (`SELECT 1`) rather than trusting the engine's laziness.
+Query-time exceptions (`OperationalError`, `IntegrityError`, etc.) propagate
+raw — SQLAlchemy's own exception hierarchy is already the right vocabulary,
+and there's no behavioral policy here (unlike kafka's `ErrorPolicy`) to
+justify a wrapping layer.
+
+## Considered Options
+
+- Raw asyncpg, no SQLAlchemy (rejected: no ORM/migration story, and k9's
+  existing Postgres usage is already ORM-shaped)
+- psycopg3-async as the DBAPI (rejected: asyncpg is the more common
+  SQLAlchemy-async pairing, no concrete reason here to deviate)
+- Lazy engine, no startup connectivity check (rejected: silently breaks the
+  family's fail-fast startup guarantee — a dead DB would "start" successfully)
+- Wrapping SQLAlchemy exceptions in component-specific error types (rejected:
+  no behavioral difference to encode, just translation boilerplate)

postgres_component-0.1.0/docs/adr/0002-migrations-stay-app-owned.md

@@ -0,0 +1,31 @@
+---
+status: accepted
+---
+
+# Migrations stay app-owned; component ships wiring only
+
+`PostgresComponent` does not run, own, or auto-trigger schema migrations.
+Consuming apps run their own Alembic setup against the same connection info.
+The component's only concession is an optional **Migration Wiring** helper
+that lets an app's `env.py` reuse the same async engine/driver instead of
+re-deriving it — targeting Alembic's async template (`run_sync`) so no second,
+sync-only driver dependency (e.g. `psycopg2`) is needed alongside `asyncpg`.
+
+The alternative — auto-running migrations inside `start()` — was rejected
+mainly because it's unsafe under concurrent startup: multiple replicas
+booting together would race on the same migration unless the component also
+implemented a distributed lock (e.g. a Postgres advisory lock), which is real
+scope the component doesn't need to own. It would also be the first component
+in the family to mix deploy-time schema DDL into a runtime lifecycle hook —
+none of kafka-component (doesn't create topics) or prometheus-component
+(doesn't push metrics) do anything comparable.
+
+## Considered Options
+
+- Auto-run migrations in `start()`, opt-in flag (rejected: races under
+  multi-replica startup without a distributed lock the component would have
+  to implement; no precedent elsewhere in the family)
+- Fully hands-off, no helper at all (rejected: leaves every consumer
+  re-deriving the same connection wiring in its own `env.py` for no benefit)
+- Component ships its own lightweight SQL-file migrator instead of Alembic
+  (rejected: reinvents a weaker version of an existing, well-known tool)