sustained 2.0.0__tar.gz → 2.2.0__tar.gz

{sustained-2.0.0 → sustained-2.2.0}/.pre-commit-config.yaml

@@ -31,8 +31,11 @@ repos:
   - repo: local
     hooks:
       - id: unit-tests
-        name: Run unit tests
-        entry: bash -c "PYTHONPATH=src python3 -m unittest discover -s tests"
+        name: Run unit tests with coverage
+        entry: >
+          bash -c "PYTHONPATH=src python3 -m coverage run --branch
+          --source=src/sustained -m unittest discover -s tests
+          && python3 -m coverage report --fail-under=90 > /dev/null"
         language: system
         types: [python]
         pass_filenames: false

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

@@ -1,5 +1,37 @@
 # 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
+
+- Typed predicates: `Model.c.age > 21` and `col()` build composable `Predicate` objects combinable with `&`, `|`, `~`; accepted by `where()` and `having()`.
+- `whereRaw()` / `havingRaw()`: raw predicates with `?` value markers that parameterize like every other clause.
+- `Model.transaction()` context manager with savepoint nesting; `run()` defers commits inside a transaction.
+- `set_statement_listener()` observer with SQL, parameters, and duration for every executed statement.
+- Upserts: `insert().onConflict(cols).merge()` / `.ignore()`. ON CONFLICT on Postgres/SQLite/DuckDB, MERGE on MSSQL, DialectError on Presto.
+- `insert_from()` (INSERT ... SELECT) and `create_table_as()` (CTAS; MSSQL raises).
+- Multi-row inserts execute through the driver's `executemany()` when there is no RETURNING clause.
+- Result formats: `to_dicts()`, `to_df()` (pandas optional), `to_arrow()` (pyarrow optional).
+- DuckDB dialect: quoting, native ILIKE, qmark placeholders, upserts, RETURNING, CTAS, QUALIFY.
+- Recursive CTEs via `with_(..., recursive=True)`; MSSQL renders plain WITH.
+- Set operations: `intersect()` and `except_()`.
+- Analyst clauses: `distinctOn()`, `groupByRollup()`, `groupByCube()`, `groupByGroupingSets()`, `qualify()`.
+- `for_update(skip_locked, nowait)` row locking on Postgres.
+- `total()` count helper and `cursor_page()` keyset pagination.
+- `explain(analyze=False)` plan inspection.
+- Through-relation (`ManyToManyRelation`) eager loading in `withGraphFetched()`.
+- Per-dialect function name translation: `NOW()` renders as `GETDATE()` on MSSQL and the reverse; `LENGTH()` renders as `LEN()` on MSSQL.
+
 ## 2.0.0 (2026-08-14)
 
 ### Breaking changes

{sustained-2.0.0 → sustained-2.2.0}/DEVELOPERS.md

@@ -21,7 +21,8 @@ The `QueryBuilder` (`sustained/builder.py`) is the central component of the libr
 
 -   **State Management:** It does not manage the complex state of the query directly. Instead, it holds instances of several specialized `*ClauseBuilder` objects.
 -   **Composition:** When a method like `.where()` or `.select()` is called on the `QueryBuilder`, it delegates that call to the appropriate internal builder (e.g., `self._where_builder` or `self._select_clause_builder`).
--   **Assembly:** When `str(query)` is finally called, the `QueryBuilder` is responsible for assembling the final SQL string by calling `str()` on each of its internal builders in the correct order and passing the result through the `Compiler`.
+-   **Assembly:** Rendering happens through a `RenderContext` (`sustained/rendering.py`) that carries the compiler and the value-handling mode. `str(query)` renders with values inlined as SQL literals. `to_sql()` renders with dialect placeholders and returns the collected parameters. Clauses that hold user values store deferred render functions instead of finished strings, so both modes share one code path.
+-   **Execution:** `run()` and `first()` (`sustained/execution.py`) execute the parameterized statement on a DB-API 2.0 connection and hydrate result rows into model instances.
 
 ### The `*ClauseBuilder`s
 
@@ -47,9 +48,25 @@ Understanding the lifecycle of a query is key to understanding the architecture.
 1.  **Instantiation:** A user calls `MyModel.query()`. The `Model` creates a `QueryBuilder` instance, passing it the currently configured `Dialect`.
 2.  **Construction:** The user chains methods like `.select()`, `.where()`, and `.orderBy()`. Each of these calls is delegated to the corresponding internal `*ClauseBuilder`, which updates its internal state.
 3.  **Compilation:** The user calls `str(query_builder)` to get the final SQL string.
-4.  **Assembly:** The `QueryBuilder.__str__()` method is invoked. It calls `str()` on each of its internal builders (`_select_clause_builder`, `_where_builder`, etc.) to get their rendered SQL fragments.
-5.  **Dialect-Specific Rendering:** For parts of the query that are dialect-dependent (like `LIMIT`/`OFFSET`), the `QueryBuilder` calls methods on its configured `Compiler` instance (e.g., `self._compiler.compile_limit_offset(...)`).
-6.  **Final String:** The `QueryBuilder` joins all the rendered fragments together into the final, complete SQL string.
+4.  **Assembly:** `QueryBuilder._render_sql(ctx)` walks the statement in SQL order. It hoists CTEs, renders each internal builder, and threads the `RenderContext` into every clause that holds user values. `__str__()` calls it with an inline-literal context; `to_sql()` calls it with a parameterizing context and returns `(sql, params)`.
+5.  **Dialect-Specific Rendering:** For parts of the query that are dialect-dependent (like `LIMIT`/`OFFSET`, identifier quoting, booleans, and ILIKE), the builders call methods on the configured `Compiler` instance.
+6.  **Final String:** The `QueryBuilder` joins all the rendered fragments together into the final, complete SQL statement.
+
+## Development Setup
+
+Tests, linting, formatting, and type checking are enforced locally through pre-commit hooks. Install the tools and the hooks once:
+
+```bash
+pip install pre-commit coverage
+pre-commit install
+```
+
+The unit-test hook runs the suite under coverage and fails the commit when total branch coverage drops below 90 percent. Run it manually with:
+
+```bash
+PYTHONPATH=src python3 -m coverage run --branch --source=src/sustained -m unittest discover -s tests
+python3 -m coverage report
+```
 
 ## Extending the ORM
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sustained
-Version: 2.0.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, and Presto dialects. It can also execute queries against any DB-API 2.0 connection, hydrate rows into model instances, write data with `insert()`, `update()`, and `delete()`, and eager load relations.
+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.0.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, and Presto dialects. It can also execute queries against any DB-API 2.0 connection, hydrate rows into model instances, write data with `insert()`, `update()`, and `delete()`, and eager load relations.
+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.2.0/docs/executing.md

@@ -0,0 +1,183 @@
+---
+layout: default
+title: Executing Queries
+---
+
+Sustained can execute the queries it builds. It works with any DB-API 2.0 connection, such as `sqlite3`, `psycopg`, or `pyodbc`. Every statement runs parameterized: user values travel as parameters, never as text inside the SQL.
+
+The connection's parameter style must match the dialect. The default and MSSQL dialects use `?` (qmark). The Postgres dialect uses `%s` (format).
+
+## Binding a Connection
+
+Bind a connection once with `Model.bind()`. Every query on that model can then run without passing the connection each time.
+
+```python
+import sqlite3
+from sustained import Model
+
+class User(Model):
+    tableName = 'users'
+
+conn = sqlite3.connect('app.db')
+User.bind(conn)
+```
+
+Bind on `Model` itself to share one connection across all models. Bind on a subclass to scope it. Call `Model.unbind()` to remove a binding. You can also pass a connection directly to `run()` or `first()`, which overrides any binding.
+
+## Running SELECT Queries
+
+`run()` executes the query and hydrates each row into a model instance. Column names come from the cursor description.
+
+```python
+users = User.query().where('active', '=', True).orderBy('name').run()
+
+for user in users:
+    print(user.name)
+```
+
+`first()` runs the query with `LIMIT 1` and returns one instance, or `None` when there is no match. The original query is not changed.
+
+```python
+user = User.query().where('email', '=', 'ada@example.com').first()
+```
+
+## Writing Data
+
+`insert()`, `update()`, and `delete()` turn the builder into a write statement. They use the same `where()` methods as SELECT and the same parameterized rendering.
+
+```python
+# INSERT INTO users (name, email) VALUES (?, ?)
+User.query().insert({'name': 'Ada', 'email': 'ada@example.com'}).run()
+
+# Multi-row insert. All rows must have the same columns.
+User.query().insert([
+    {'name': 'Ada'},
+    {'name': 'Grace'},
+]).run()
+
+# UPDATE users SET active = ? WHERE id = ?
+User.query().update({'active': False}).where('id', '=', 1).run()
+
+# DELETE FROM users WHERE active = ?
+User.query().delete().where('active', '=', False).run()
+```
+
+Write statements commit after they run and return the affected row count. Multi-row inserts without a RETURNING clause execute through the driver's `executemany()` with a single-row template, which is the fast path for bulk loads.
+
+### Transactions
+
+`Model.transaction()` opens a context that commits when the block finishes and rolls back when it raises. Statements inside the block share one transaction; `run()` stops committing per statement. Nested blocks use savepoints, so an inner failure rolls back only the inner block.
+
+```python
+with User.transaction():
+    Account.query().update({'balance': 0}).where('id', '=', 1).run()
+    AuditLog.query().insert({'event': 'reset', 'account_id': 1}).run()
+```
+
+### Upserts
+
+Chain `onConflict(columns)` after `insert()`, then choose `merge()` to update the existing row or `ignore()` to skip it. `merge()` updates every inserted column except the conflict columns, or an explicit list.
+
+```python
+User.query().insert({'email': 'a@x.com', 'name': 'Ada'}) \
+    .onConflict('email').merge().run()
+```
+
+Postgres, SQLite, and DuckDB render `ON CONFLICT`; MSSQL renders a `MERGE` statement; Presto raises.
+
+### INSERT ... SELECT and CREATE TABLE AS
+
+`insert_from(columns, query)` inserts the result of another query. `create_table_as(name, temporary=False)` turns a SELECT into a CTAS statement. MSSQL raises for CTAS; use `SELECT INTO` through raw SQL there.
+
+```python
+inactive = User.query().select('id', 'name').where('active', '=', False)
+Archive.query().insert_from(['id', 'name'], inactive).run()
+
+User.query().select('id').where('active', '=', True).create_table_as('active_ids').run()
+```
+
+### Safety Rule for UPDATE and DELETE
+
+An `update()` or `delete()` without a `where()` clause raises a `ValueError`, because an unfiltered write usually means a missing filter. To write every row on purpose, add an always-true raw predicate:
+
+```python
+User.query().update({'active': True}).where(QueryBuilder.raw('1'), '=', 1).run()
+```
+
+### RETURNING
+
+`returning()` adds a `RETURNING` clause on dialects that support it. The statement then returns a list of dicts instead of a row count. MSSQL and Presto raise a `DialectError`.
+
+```python
+rows = User.query().insert({'name': 'Ada'}).returning('id').run()
+# [{'id': 42}]
+```
+
+## Eager Loading Relations
+
+`withGraphFetched()` loads relations from `relationMappings` when the query runs. Each relation costs one extra query. `HasManyRelation` attaches a list to each instance. The to-one relation types attach a single instance or `None`.
+
+```python
+owners = Owner.query().withGraphFetched('pets').run()
+
+for owner in owners:
+    for pet in owner.pets:
+        print(owner.name, pet.name)
+```
+
+Eager loading needs the join key columns in both result sets, so keep them in your `select()` or select all columns. Through relations (`ManyToManyRelation`) load with one query that joins the related table to the through table.
+
+## Result Formats
+
+`run()` returns model instances. For other shapes:
+
+*   **`to_dicts()`**: rows as plain dicts keyed by column name.
+*   **`to_df()`**: a pandas DataFrame, keeping the query's column names even when empty. Requires pandas.
+*   **`to_arrow()`**: a pyarrow Table. Requires pyarrow.
+
+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.0.0 → sustained-2.2.0}/docs/filtering.md

@@ -52,6 +52,32 @@ Movie.query().where("tagline", "=", None)
 
 Column names quote per dialect when they are plain identifier paths. Values render as SQL literals in `str(query)` and as placeholders in `to_sql()`. See [Executing Queries](./executing).
 
+## Typed Predicates
+
+Every model exposes a typed column namespace at `Model.c`, and the `col()` helper wraps any dotted path. Python comparison operators build `Predicate` objects, which combine with `&` (AND), `|` (OR), and `~` (NOT). Pass the result to `where()` or `having()`.
+
+```python
+from sustained import col
+
+# SELECT * FROM movies WHERE ((rating > 8 AND genre = 'Sci-Fi') OR NOT (archived = TRUE))
+Movie.query().where(
+    (Movie.c.rating > 8) & (Movie.c.genre == "Sci-Fi") | ~(Movie.c.archived == True)
+)
+```
+
+Column methods cover the rest of the operators: `.like()`, `.not_like()`, `.ilike()`, `.in_()`, `.not_in()`, `.between()`, `.not_between()`, `.is_null()`, `.not_null()`. Values parameterize in `to_sql()` and columns quote per dialect. Comparing with `== None` or `!= None` renders `IS NULL` / `IS NOT NULL`. A `Predicate` raises `TypeError` in a boolean context, which catches accidental use of the `and`/`or` keywords.
+
+## Raw Predicates with Bound Values: `whereRaw`
+
+For a predicate the builder cannot express, use `whereRaw(sql, params)`. Mark each value with `?`; the values travel as parameters, never as text in the SQL. `havingRaw` works the same way for HAVING.
+
+```python
+# SELECT * FROM movies WHERE (release_year % ? = ?)
+Movie.query().whereRaw("release_year % ? = ?", [2, 0])
+```
+
+The marker count must match the parameter count, and the fragment renders wrapped in parentheses.
+
 ## `whereIn` and `whereNotIn`
 
 To filter against a list of values, use the `whereIn` and `whereNotIn` methods.

{sustained-2.0.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.0.0 → sustained-2.2.0}/docs/queries.md

@@ -388,6 +388,15 @@ print(posts_query)
 #   ON posts.user_id = active_users.id
 ```
 
+### Recursive CTEs
+
+Pass `recursive=True` for a self-referencing CTE. The WITH clause renders as `WITH RECURSIVE`, except on MSSQL, where T-SQL spells recursive CTEs with plain `WITH`.
+
+```python
+tree = Employee.query().select('id', 'manager_id')  # anchor plus recursion via raw()
+query = Employee.query().with_('tree', tree, recursive=True).from_('tree')
+```
+
 ## Combining Queries with UNION
 
 You can combine multiple queries into a single result set using `UNION` and `UNION ALL`.
@@ -422,6 +431,30 @@ print(all_users)
 final_query = active_users.union(pending_users).offset(50)
 ```
 
+### INTERSECT and EXCEPT
+
+`intersect()` keeps only rows present in every query. `except_()` removes rows that appear in the given queries. The trailing underscore avoids the Python `except` keyword. Both work like `union()`.
+
+## Analyst Clauses
+
+*   **`distinctOn(*columns)`**: Postgres/DuckDB `SELECT DISTINCT ON (...)`, which keeps the first row per group; pair it with `orderBy()` on the same leading columns. Other dialects raise `DialectError`.
+*   **`groupByRollup(*columns)` / `groupByCube(*columns)` / `groupByGroupingSets(*tuples)`**: subtotal and multi-grain aggregation forms of GROUP BY.
+*   **`qualify(condition)`**: filters on window function results without a wrapping subquery. Takes a `Predicate` or a raw string. Supported on DuckDB.
+*   **`for_update(skip_locked=False, nowait=False)`**: row locking on Postgres; rejected with unions and on dialects without it.
+
+## Counting and Keyset Pagination
+
+`total()` runs `SELECT COUNT(*)` over the query with ORDER BY, LIMIT, and OFFSET stripped, and returns the count without changing the query. `cursor_page(column, page_size, after=None)` applies keyset pagination: it orders by the column, filters rows greater than the last seen value, and limits to the page size. On large tables this avoids the scan cost that grows with OFFSET.
+
+```python
+first_page = User.query().cursor_page('id', 100).run()
+second_page = User.query().cursor_page('id', 100, after=first_page[-1].id).run()
+```
+
+## Inspecting Plans
+
+`explain()` runs the dialect's EXPLAIN on the query and returns the plan rows. `explain(analyze=True)` uses EXPLAIN ANALYZE, which actually executes the statement. MSSQL raises because T-SQL has no EXPLAIN.
+
 ## SQL Dialects
 
 Sustained supports generating SQL for different database dialects. This allows you to take advantage of dialect-specific features and syntax. By default, Sustained generates standard ANSI SQL.
@@ -432,6 +465,7 @@ Currently, the following dialects are supported:
 *   **`Dialects.PRESTO`**: SQL dialect for the Presto query engine.
 *   **`Dialects.MSSQL`**: SQL dialect for Microsoft SQL Server.
 *   **`Dialects.POSTGRES`**: SQL dialect for PostgreSQL.
+*   **`Dialects.DUCKDB`**: SQL dialect for DuckDB.
 
 ### Setting the Dialect
 

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.0.0 → sustained-2.2.0}/pyproject.toml

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

{sustained-2.0.0 → sustained-2.2.0}/src/sustained/__init__.py

@@ -16,9 +16,12 @@ from sustained.expressions import (
     AggregateExpression,
     CaseExpression,
     Column,
+    ColumnExpr,
     Func,
     Literal,
+    Predicate,
     WindowExpression,
+    col,
 )
 from sustained.model import Model, create_model
 from sustained.types import (
@@ -36,6 +39,9 @@ __all__ = [
     "DialectError",
     # from expressions
     "Column",
+    "ColumnExpr",
+    "Predicate",
+    "col",
     "Func",
     "Literal",
     "AggregateExpression",