sustained 2.1.0__tar.gz → 2.2.0__tar.gz

{sustained-2.1.0 → sustained-2.2.0}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2.2.0 (2026-08-14)
+
+### Added
+
+- Typed column definitions: models declare `tableColumns` with `Integer`, `BigInteger`, `String`, `Text`, `Boolean`, `Float`, `Numeric`, `Date`, `Timestamp`, and `Json`, including composite primary keys, defaults, unique constraints, foreign key references, and autoincrement. Strict column access derives automatically.
+- Model-driven DDL: `create_table_sql()`, `create_table()`, `drop_table()` with per-dialect type mapping and identity syntax. DuckDB and Presto raise for autoincrement.
+- Migration runner: ordered `Migration` objects with up/down steps (SQL, statement lists, or callables), a self-creating tracking table, transactional application, stop-after targets, and newest-first reverts. `create_table_migration()` derives create/drop pairs from models. No catalog diffing.
+- `ConnectionPool`: thread-safe, lazy, bounded pooling for DB-API connections. `Model.bind()` and all execution entry points accept a pool; transactions pin one checked-out connection to the thread; nested blocks reuse it via savepoints.
+- Async execution: `arun()`, `afirst()`, `ato_dicts()` through an adapter interface with `DbApiAsyncAdapter` (any sync driver via worker threads), `AiosqliteAdapter`, and `AsyncpgAdapter` (`%s` to `$n` conversion). `Model.bind_async()` and `async_transaction()` with ContextVar pinning. Async through-relation eager loading and nested async transactions are not supported yet.
+
 ## 2.1.0 (2026-08-14)
 
 ### Added

{sustained-2.1.0 → sustained-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sustained
-Version: 2.1.0
+Version: 2.2.0
 Summary: A Python query builder inspired by Objection.js
 Project-URL: Homepage, https://github.com/wetherc/sustained
 Project-URL: Issues, https://github.com/wetherc/sustained/issues
@@ -16,7 +16,7 @@ Description-Content-Type: text/markdown
 
 A Python query builder and lightweight ORM inspired by [Objection.js](https://vincit.github.io/objection.js/).
 
-Sustained builds parameterized SQL for the default (ANSI), Postgres, MSSQL, Presto, and DuckDB dialects. It executes queries against any DB-API 2.0 connection with transactions, hydrates rows into model instances or DataFrames, writes data with `insert()`, `update()`, `delete()`, upserts, and `INSERT ... SELECT`, and eager loads relations. Filters compose as typed predicates: `User.query().where((User.c.age > 21) & User.c.name.like('A%'))`.
+Sustained builds parameterized SQL for the default (ANSI), Postgres, MSSQL, Presto, and DuckDB dialects. It executes queries against any DB-API 2.0 connection or connection pool with transactions, hydrates rows into model instances or DataFrames, writes data with `insert()`, `update()`, `delete()`, upserts, and `INSERT ... SELECT`, and eager loads relations. Filters compose as typed predicates: `User.query().where((User.c.age > 21) & User.c.name.like('A%'))`. Models can declare typed columns and generate their DDL, an explicit migration runner manages schema changes, and async services run the same queries through driver adapters with `await query.arun()`.
 
 ## Installation
 

{sustained-2.1.0 → sustained-2.2.0}/README.md

@@ -2,7 +2,7 @@
 
 A Python query builder and lightweight ORM inspired by [Objection.js](https://vincit.github.io/objection.js/).
 
-Sustained builds parameterized SQL for the default (ANSI), Postgres, MSSQL, Presto, and DuckDB dialects. It executes queries against any DB-API 2.0 connection with transactions, hydrates rows into model instances or DataFrames, writes data with `insert()`, `update()`, `delete()`, upserts, and `INSERT ... SELECT`, and eager loads relations. Filters compose as typed predicates: `User.query().where((User.c.age > 21) & User.c.name.like('A%'))`.
+Sustained builds parameterized SQL for the default (ANSI), Postgres, MSSQL, Presto, and DuckDB dialects. It executes queries against any DB-API 2.0 connection or connection pool with transactions, hydrates rows into model instances or DataFrames, writes data with `insert()`, `update()`, `delete()`, upserts, and `INSERT ... SELECT`, and eager loads relations. Filters compose as typed predicates: `User.query().where((User.c.age > 21) & User.c.name.like('A%'))`. Models can declare typed columns and generate their DDL, an explicit migration runner manages schema changes, and async services run the same queries through driver adapters with `await query.arun()`.
 
 ## Installation
 

{sustained-2.1.0 → sustained-2.2.0}/docs/executing.md

@@ -137,6 +137,47 @@ Eager loading needs the join key columns in both result sets, so keep them in yo
 
 pandas and pyarrow are optional; the methods raise a clear error when the library is missing.
 
+## Connection Pooling
+
+`ConnectionPool` creates connections lazily from a factory up to `max_size` and reuses released ones. Bind it like a connection; every statement checks a connection out for its duration.
+
+```python
+from sustained.pool import ConnectionPool
+
+pool = ConnectionPool(lambda: psycopg2.connect(DSN), max_size=10)
+User.bind(pool)
+
+users = User.query().where('active', '=', True).run()
+
+with User.transaction():
+    # One connection is pinned to this thread for the whole block.
+    User.query().insert({...}).run()
+    Account.query().update({...}).where(...).run()
+```
+
+An exhausted pool raises `PoolTimeout` after the configured timeout. `pool.close()` closes idle connections.
+
+## Async Execution
+
+Queries run asynchronously through an adapter. `DbApiAsyncAdapter` wraps any synchronous DB-API connection in a worker thread; `AiosqliteAdapter` and `AsyncpgAdapter` wrap their native drivers. The asyncpg adapter converts `%s` placeholders to `$1..$n`.
+
+```python
+from sustained.aio import DbApiAsyncAdapter
+
+adapter = DbApiAsyncAdapter(sqlite3.connect('app.db', check_same_thread=False))
+User.bind_async(adapter)
+
+users = await User.query().where('active', '=', True).arun()
+user = await User.query().where('id', '=', 1).afirst()
+rows = await User.query().ato_dicts()
+
+async with User.async_transaction():
+    await User.query().insert({...}).arun()
+    await Account.query().update({...}).where(...).arun()
+```
+
+`arun()` mirrors `run()`: hydration, RETURNING rows, batched multi-row inserts, and eager loading of basic relations. Async eager loading of through relations is not supported yet, and async transactions do not nest.
+
 ## Statement Logging
 
 `sustained.execution.set_statement_listener(fn)` registers an observer called after every executed statement with the SQL text, the parameter tuple, and the duration in seconds. Pass `None` to remove it.

{sustained-2.1.0 → sustained-2.2.0}/docs/index.md

@@ -18,6 +18,7 @@ If you are new to Sustained, it's recommended to read the guides in the followin
 5.  **[Filtering](./filtering):** Dive into the various `where` methods for filtering your results.
 6.  **[Relations and Joins](./relations):** Learn how to define relationships between models and join them in your queries.
 7.  **[Executing Queries](./executing):** Run queries against a database, hydrate results into models, write data, and eager load relations.
+8.  **[Schema and Migrations](./schema):** Declare typed columns on models, generate DDL, and run ordered migrations.
 
 ## API Reference
 

sustained-2.2.0/docs/schema.md

@@ -0,0 +1,64 @@
+---
+layout: default
+title: Schema and Migrations
+---
+
+Models can declare their physical shape and generate DDL from it, and the migration runner applies ordered schema changes.
+
+## Typed Columns
+
+Declare `tableColumns` as a dict of column name to a typed definition. The factories are `Integer`, `BigInteger`, `String(length)`, `Text`, `Boolean`, `Float`, `Numeric(precision, scale)`, `Date`, `Timestamp`, and `Json`.
+
+```python
+from sustained import Model
+from sustained.schema import Boolean, Integer, String, Timestamp
+from sustained.types import Expression
+
+class User(Model):
+    tableName = 'users'
+    tableColumns = {
+        'id': Integer(primary_key=True, autoincrement=True),
+        'email': String(120, unique=True, nullable=False),
+        'active': Boolean(default=True),
+        'created_at': Timestamp(default=Expression('CURRENT_TIMESTAMP')),
+    }
+```
+
+Definitions support composite primary keys (mark several columns `primary_key=True`), `unique`, literal defaults or raw `Expression` defaults, and foreign keys through `references='table.column'`. `autoincrement` requires a single integer primary key; DuckDB and Presto raise because they have no identity columns.
+
+A model with `tableColumns` also gets strict column-name access automatically: a typo'd column raises `AttributeError`.
+
+## Generating and Running DDL
+
+```python
+User.create_table_sql()               # dialect-specific CREATE TABLE
+User.create_table(conn)               # execute it
+User.drop_table(conn)                 # DROP TABLE IF EXISTS
+```
+
+Types map per dialect: `BIT`, `NVARCHAR`, and `DATETIME2` on MSSQL; `JSONB` and identity columns on Postgres; plain `INTEGER PRIMARY KEY` rowid behavior on the default dialect.
+
+## Migrations
+
+Migrations are explicit and ordered. Each pairs an id with an up step and an optional down step; steps are a SQL string, a list of statements, or a callable receiving the connection.
+
+```python
+from sustained.migrations import Migration, Migrator, create_table_migration
+
+migrations = [
+    create_table_migration(User),
+    Migration(
+        'add_last_login',
+        up='ALTER TABLE users ADD COLUMN last_login TEXT',
+        down='ALTER TABLE users DROP COLUMN last_login',
+    ),
+]
+
+migrator = Migrator(conn, migrations)
+migrator.up()          # apply all pending
+migrator.up(target='create_users')  # stop after a target
+migrator.status()      # [(id, applied), ...]
+migrator.down()        # revert the newest applied migration
+```
+
+Applied ids live in a tracking table that the migrator creates on first use. Each migration runs inside a transaction, so a failing step leaves the schema at the previous migration. There is no automatic diffing against the database catalog; write migrations explicitly or derive create/drop pairs from models with `create_table_migration()`.

{sustained-2.1.0 → sustained-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sustained"
-version = "2.1.0"
+version = "2.2.0"
 description = "A Python query builder inspired by Objection.js"
 readme = "README.md"
 requires-python = ">=3.9"

sustained-2.2.0/src/sustained/aio.py

@@ -0,0 +1,356 @@
+"""
+Async execution support.
+
+Queries run asynchronously through an adapter that wraps an async database
+driver. Three adapters ship with Sustained:
+
+- DbApiAsyncAdapter wraps any synchronous DB-API 2.0 connection and runs
+  its calls in a worker thread. It works with every driver the sync path
+  supports and is the reference implementation.
+- AiosqliteAdapter wraps an aiosqlite connection.
+- AsyncpgAdapter wraps an asyncpg connection and converts the Postgres
+  compiler's %s placeholders to asyncpg's $1..$n style. A literal %s inside
+  raw SQL text would be converted too; avoid it in raw fragments.
+
+Bind an adapter with Model.bind_async(adapter), then use arun(), afirst(),
+and ato_dicts() on queries. async_transaction() gives atomic blocks; the
+pin travels through a ContextVar, so concurrent tasks do not share it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Any, AsyncIterator, Dict, List, Optional, Tuple, Type
+
+from sustained.execution import notify_statement
+from sustained.types import RelationType
+
+if TYPE_CHECKING:
+    from sustained.builder import QueryBuilder
+    from sustained.model import Model
+
+
+class AsyncAdapter:
+    """
+    The interface async execution needs from a driver. Subclasses implement
+    fetch, execute, executemany, commit, and rollback.
+    """
+
+    async def fetch(
+        self, sql: str, params: Tuple[Any, ...]
+    ) -> Tuple[List[str], List[Any]]:
+        """Runs a statement and returns (column names, rows)."""
+        raise NotImplementedError
+
+    async def execute(self, sql: str, params: Tuple[Any, ...]) -> int:
+        """Runs a statement and returns the affected row count."""
+        raise NotImplementedError
+
+    async def executemany(self, sql: str, seq_of_params: List[Tuple[Any, ...]]) -> int:
+        """Runs a statement for every parameter tuple."""
+        raise NotImplementedError
+
+    async def commit(self) -> None:
+        raise NotImplementedError
+
+    async def rollback(self) -> None:
+        raise NotImplementedError
+
+
+class DbApiAsyncAdapter(AsyncAdapter):
+    """
+    Adapts a synchronous DB-API 2.0 connection to the async interface by
+    running each call in a worker thread. The connection must allow use
+    from other threads, e.g. sqlite3.connect(..., check_same_thread=False).
+    """
+
+    def __init__(self, connection: Any) -> None:
+        self._connection = connection
+        # One statement at a time per connection; DB-API connections are
+        # not safe for concurrent use.
+        self._lock = asyncio.Lock()
+
+    def _fetch_sync(
+        self, sql: str, params: Tuple[Any, ...]
+    ) -> Tuple[List[str], List[Any]]:
+        cursor = self._connection.cursor()
+        cursor.execute(sql, params)
+        columns = [d[0] for d in cursor.description] if cursor.description else []
+        return columns, cursor.fetchall()
+
+    def _execute_sync(self, sql: str, params: Tuple[Any, ...]) -> int:
+        cursor = self._connection.cursor()
+        cursor.execute(sql, params)
+        return int(cursor.rowcount)
+
+    def _executemany_sync(self, sql: str, seq: List[Tuple[Any, ...]]) -> int:
+        cursor = self._connection.cursor()
+        cursor.executemany(sql, seq)
+        return int(cursor.rowcount)
+
+    async def fetch(
+        self, sql: str, params: Tuple[Any, ...]
+    ) -> Tuple[List[str], List[Any]]:
+        async with self._lock:
+            return await asyncio.to_thread(self._fetch_sync, sql, params)
+
+    async def execute(self, sql: str, params: Tuple[Any, ...]) -> int:
+        async with self._lock:
+            return await asyncio.to_thread(self._execute_sync, sql, params)
+
+    async def executemany(self, sql: str, seq_of_params: List[Tuple[Any, ...]]) -> int:
+        async with self._lock:
+            return await asyncio.to_thread(self._executemany_sync, sql, seq_of_params)
+
+    async def commit(self) -> None:
+        async with self._lock:
+            await asyncio.to_thread(self._connection.commit)
+
+    async def rollback(self) -> None:
+        async with self._lock:
+            await asyncio.to_thread(self._connection.rollback)
+
+
+class AiosqliteAdapter(AsyncAdapter):
+    """Adapts an aiosqlite connection."""
+
+    def __init__(self, connection: Any) -> None:
+        self._connection = connection
+
+    async def fetch(
+        self, sql: str, params: Tuple[Any, ...]
+    ) -> Tuple[List[str], List[Any]]:
+        cursor = await self._connection.execute(sql, params)
+        columns = [d[0] for d in cursor.description] if cursor.description else []
+        rows = await cursor.fetchall()
+        return columns, list(rows)
+
+    async def execute(self, sql: str, params: Tuple[Any, ...]) -> int:
+        cursor = await self._connection.execute(sql, params)
+        return int(cursor.rowcount)
+
+    async def executemany(self, sql: str, seq_of_params: List[Tuple[Any, ...]]) -> int:
+        cursor = await self._connection.executemany(sql, seq_of_params)
+        return int(cursor.rowcount)
+
+    async def commit(self) -> None:
+        await self._connection.commit()
+
+    async def rollback(self) -> None:
+        await self._connection.rollback()
+
+
+def convert_format_to_numbered(sql: str) -> str:
+    """Converts %s placeholders to $1..$n for asyncpg."""
+    pieces = sql.split("%s")
+    out = [pieces[0]]
+    for index, piece in enumerate(pieces[1:], start=1):
+        out.append(f"${index}")
+        out.append(piece)
+    return "".join(out)
+
+
+class AsyncpgAdapter(AsyncAdapter):
+    """
+    Adapts an asyncpg connection. Statements arrive with the Postgres
+    compiler's %s placeholders and are converted to $1..$n.
+    """
+
+    def __init__(self, connection: Any) -> None:
+        self._connection = connection
+
+    async def fetch(
+        self, sql: str, params: Tuple[Any, ...]
+    ) -> Tuple[List[str], List[Any]]:
+        records = await self._connection.fetch(convert_format_to_numbered(sql), *params)
+        if not records:
+            return [], []
+        columns = list(records[0].keys())
+        return columns, [tuple(r) for r in records]
+
+    async def execute(self, sql: str, params: Tuple[Any, ...]) -> int:
+        status = await self._connection.execute(
+            convert_format_to_numbered(sql), *params
+        )
+        # asyncpg returns a status string such as 'INSERT 0 3' or 'DELETE 2'.
+        try:
+            return int(status.rsplit(" ", 1)[-1])
+        except (ValueError, AttributeError):
+            return -1
+
+    async def executemany(self, sql: str, seq_of_params: List[Tuple[Any, ...]]) -> int:
+        await self._connection.executemany(
+            convert_format_to_numbered(sql), seq_of_params
+        )
+        # asyncpg's executemany reports no row count.
+        return -1
+
+    async def commit(self) -> None:
+        # asyncpg runs in autocommit outside explicit transactions.
+        pass
+
+    async def rollback(self) -> None:
+        pass
+
+
+# Adapter pinned by an open async_transaction() block. A ContextVar keeps
+# the pin scoped to the current task tree.
+_pinned_adapter: ContextVar[Optional[AsyncAdapter]] = ContextVar(
+    "sustained_pinned_adapter", default=None
+)
+# Adapters with an open transaction; arun() skips per-statement commits.
+_active_async_transactions: Dict[int, AsyncAdapter] = {}
+
+
+def resolve_adapter(
+    explicit: Optional[AsyncAdapter], model_class: Type["Model"]
+) -> AsyncAdapter:
+    """Resolves the adapter: explicit, then pinned, then the model binding."""
+    if explicit is not None:
+        return explicit
+    pinned = _pinned_adapter.get()
+    if pinned is not None:
+        return pinned
+    bound = getattr(model_class, "_async_adapter", None)
+    if bound is None:
+        raise RuntimeError(
+            "No async adapter. Bind one with Model.bind_async(adapter) "
+            "or pass it to arun()."
+        )
+    return bound  # type: ignore[no-any-return]
+
+
+def in_async_transaction(adapter: AsyncAdapter) -> bool:
+    """Reports whether the adapter has an open async_transaction() block."""
+    return _active_async_transactions.get(id(adapter)) is adapter
+
+
+@asynccontextmanager
+async def async_transaction(adapter: AsyncAdapter) -> AsyncIterator[AsyncAdapter]:
+    """
+    Runs the block atomically on the adapter: commit on success, rollback
+    on exception. The adapter pins to the current task context, so arun()
+    calls inside the block use it without passing it around. Savepoint
+    nesting is not supported; nested blocks raise.
+    """
+    if in_async_transaction(adapter):
+        raise RuntimeError(
+            "async_transaction() does not support nesting on one adapter."
+        )
+    key = id(adapter)
+    _active_async_transactions[key] = adapter
+    token = _pinned_adapter.set(adapter)
+    try:
+        # Explicit statements rather than adapter.commit(), because drivers
+        # in autocommit mode (asyncpg) treat commit() as a no-op.
+        await adapter.execute("BEGIN", ())
+        try:
+            yield adapter
+        except BaseException:
+            await adapter.execute("ROLLBACK", ())
+            raise
+        await adapter.execute("COMMIT", ())
+    finally:
+        _pinned_adapter.reset(token)
+        del _active_async_transactions[key]
+
+
+async def run_async(
+    query: "QueryBuilder", adapter: Optional[AsyncAdapter] = None
+) -> Any:
+    """
+    Executes a built query on an async adapter. SELECT statements return
+    hydrated model instances with eager relations attached; writes return
+    the affected row count or RETURNING rows as dicts.
+    """
+    resolved = resolve_adapter(adapter, query._model_class)
+
+    use_executemany = (
+        query._stmt_type == "insert"
+        and len(query._insert_rows) > 1
+        and not query._returning_columns
+    )
+    started = time.perf_counter()
+    if query._stmt_type == "select":
+        sql, params = query.to_sql()
+        columns, rows = await resolved.fetch(sql, params)
+        notify_statement(sql, params, time.perf_counter() - started)
+        models = [query._model_class(**dict(zip(columns, row))) for row in rows]
+        for relation_name in query._eager_relations:
+            await _eager_load_async(query._model_class, resolved, models, relation_name)
+        return models
+
+    if use_executemany:
+        template = query.clone()
+        template._insert_rows = [query._insert_rows[0]]
+        sql, _ = template.to_sql()
+        column_names = list(query._insert_rows[0].keys())
+        seq = [tuple(row[c] for c in column_names) for row in query._insert_rows]
+        result: Any = await resolved.executemany(sql, seq)
+        notify_statement(sql, (), time.perf_counter() - started)
+    elif query._returning_columns:
+        sql, params = query.to_sql()
+        columns, rows = await resolved.fetch(sql, params)
+        notify_statement(sql, params, time.perf_counter() - started)
+        result = [dict(zip(columns, row)) for row in rows]
+    else:
+        sql, params = query.to_sql()
+        result = await resolved.execute(sql, params)
+        notify_statement(sql, params, time.perf_counter() - started)
+
+    if not in_async_transaction(resolved):
+        await resolved.commit()
+    return result
+
+
+async def _eager_load_async(
+    model_class: Type["Model"],
+    adapter: AsyncAdapter,
+    parents: List["Model"],
+    relation_name: str,
+) -> None:
+    """Async mirror of the sync eager loader for basic relations."""
+    from sustained.execution import _collect_parent_keys, _split_column_ref
+    from sustained.model import resolve_model_reference
+
+    if not parents:
+        return
+    relation = model_class.relationMappings[relation_name]
+    join_info = relation["join"]
+    if "through" in join_info:
+        raise NotImplementedError(
+            "Async eager loading of through relations is not supported yet."
+        )
+    related_cls = resolve_model_reference(
+        relation["modelClass"], context_module=model_class.__module__
+    )
+    from_table, from_col = _split_column_ref(join_info["from"], relation_name)
+    to_table, to_col = _split_column_ref(join_info["to"], relation_name)
+    if from_table == model_class.tableName:
+        parent_col, child_col = from_col, to_col
+    else:
+        parent_col, child_col = to_col, from_col
+
+    parent_keys = _collect_parent_keys(parents, parent_col, relation_name)
+    unique_keys = [k for k in dict.fromkeys(parent_keys) if k is not None]
+    is_many = relation["relation"] == RelationType.HasManyRelation
+    if not unique_keys:
+        for parent in parents:
+            setattr(parent, relation_name, [] if is_many else None)
+        return
+
+    children = await run_async(
+        related_cls.query().whereIn(child_col, unique_keys), adapter
+    )
+    grouped: Dict[Any, List["Model"]] = {}
+    for child in children:
+        grouped.setdefault(child.__dict__.get(child_col), []).append(child)
+    for parent, key in zip(parents, parent_keys):
+        matches = grouped.get(key, [])
+        if is_many:
+            setattr(parent, relation_name, matches)
+        else:
+            setattr(parent, relation_name, matches[0] if matches else None)