Metadata-Version: 2.4
Name: rn-forge-sqlalchemy
Version: 0.2.2
Summary: Async SQLAlchemy models, upsert and keyset pagination over rn-forge-web
Author: Rohit Narayanan
Author-email: Rohit Narayanan <rohit.nn@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Dist: rn-forge-web>=0.3.0,<0.4
Requires-Dist: sqlalchemy[asyncio]>=2.0
Requires-Python: >=3.14
Project-URL: Documentation, https://rn-forge.github.io/pykit/packages/rn-forge-sqlalchemy/latest/
Project-URL: Source, https://github.com/rn-forge/pykit/tree/main/packages/rn-forge-sqlalchemy
Project-URL: Changelog, https://github.com/rn-forge/pykit/blob/main/packages/rn-forge-sqlalchemy/CHANGELOG.md
Project-URL: Issues, https://github.com/rn-forge/pykit/issues
Description-Content-Type: text/markdown

# rn-forge-sqlalchemy

[Documentation](https://rn-forge.github.io/pykit/packages/rn-forge-sqlalchemy/latest/)
·
[Changelog](https://github.com/rn-forge/pykit/blob/main/packages/rn-forge-sqlalchemy/CHANGELOG.md)
·
[Source](https://github.com/rn-forge/pykit/tree/main/packages/rn-forge-sqlalchemy)
· [All pykit packages](https://rn-forge.github.io/pykit/)

Async SQLAlchemy building blocks that match the `rn-forge-web` wire: audit and
version columns, a bulk upsert for imports, and keyset pagination over web's
opaque page token.

| Module | What it holds |
| -- | -- |
| `models` | `Base` (Alembic naming convention), `UTCDateTime`, `AuditMixin` (`create_time`, `update_time`, `created_by`, `updated_by`), `VersionMixin` |
| `concurrency` | `update_versioned` — optimistic concurrency, raising `rn_forge.web.VersionConflict` (412) |
| `upsert` | `upsert` — create or update rows by natural key, counting created, updated and skipped |
| `pagination` | `keyset`, `next_page_token` — AIP-132 `orderBy` and AIP-158 tokens over a `Select` |

Everything works on **PostgreSQL and SQLite**, through `AsyncSession` only.

## Where it sits

```text
commons ──► web ──► sqlalchemy      (this package)
              ├───► django
              └───► fastapi
```

It depends on `rn-forge-web` and SQLAlchemy. It imports neither
`rn_forge.fastapi` nor `rn_forge.django`, nor either framework;
`uv run lint-imports` proves it. An application wires this package to its
framework itself: the FastAPI guide shows the import and list endpoints.

## Installation

Require the packages by version range:

```toml
dependencies = [
  "rn-forge-sqlalchemy>=0.2,<0.3",
  "rn-forge-web>=0.3,<0.4",
]
```

Application code catches `rn_forge.web.VersionConflict` and passes
`rn_forge.web` pagination terms, so declare `rn-forge-web` as well.

No database driver is declared. Add `asyncpg` for PostgreSQL or `aiosqlite` for
SQLite.

## Testing

```bash
uv run pytest packages/rn-forge-sqlalchemy
RN_FORGE_TEST_POSTGRES_DSN=postgresql+asyncpg://user:pw@localhost/db \
  uv run pytest packages/rn-forge-sqlalchemy -m postgres
```

The default run uses SQLite. Tests marked `postgres` run only when the DSN is
set.

## Not included

The SQL idempotency store, session and unit-of-work helpers, readiness checks
and multi-tenant scoping wait for an application that needs them.
