sustained 2.3.0__tar.gz → 2.5.0__tar.gz

{sustained-2.3.0 → sustained-2.5.0}/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 2.5.0 (2026-08-14)
+
+### Added
+
+- AWS Athena dialect (`Dialects.ATHENA`): inherits Presto's query behavior with Athena's differences. `%s` placeholders matching pyathena, MERGE upserts on Iceberg tables, and Athena's type spellings (INT, STRING, DOUBLE, DECIMAL; JSON maps to STRING).
+- `TableOptions(location, partitioned_by, properties)`: storage clauses declared as a model's `tableOptions` and rendered as PARTITIONED BY, LOCATION, and TBLPROPERTIES on Athena. Other dialects raise when options are set. Partition entries pass through as written so Iceberg transforms work.
+- Athena DDL: `ADD COLUMNS` spelling for added columns, `CHANGE COLUMN` for Iceberg type widenings. Constraints (primary key, unique, default, foreign key, NOT NULL, autoincrement) and indexes raise `DialectError` at build time because Athena cannot enforce them. Renames, nullability changes, `type_casts` hints, RETURNING, and temporary CTAS raise with directions.
+- Migrations on engines without transactions: the migrator now consults the dialect and runs each step bare on Athena instead of wrapping it in a transaction, never calling rollback. `Migrator` and `AsyncMigrator` accept `tracking_table_options` for the tracking table's storage clauses, and create it without constraints on constraint-free engines.
+- The function registry recognizes Athena wherever it recognizes Presto, including `NOW()` and the `GETDATE()` translation.
+- Schema diffing normalizes Athena's STRING type, so tables created from models diff clean through `information_schema`.
+
+## 2.4.0 (2026-08-14)
+
+### Added
+
+- Constraint-aware introspection: primary keys, unique constraints, foreign keys, column defaults, and indexes are read from SQLite PRAGMA tables or information_schema, with graceful degradation and system schemas filtered.
+- Type and nullability changes now generate migrations: in-place reversible ALTER COLUMN on Postgres (with `type_casts` USING hints), MSSQL, and DuckDB; automatic table rebuild with row copy on SQLite.
+- Rename hints: `renames={'table.old': 'new'}` and `table_renames` produce reversible RENAME statements (sp_rename on MSSQL) instead of destructive drop-plus-add.
+- Declared indexes on models via `Index`; created with the table and diffed for additions, definition changes, and opt-in drops, all reversible.
+- `backfill` on ColumnDef: NOT NULL adds and tightenings emit add-nullable, UPDATE, SET NOT NULL, or fold into the SQLite rebuild.
+- Length and precision changes detected when both sides report them.
+- Constraint notes: PK, FK, unique, and default drift reported in the diff, never auto-migrated.
+- Offline scripts: `migration_sql()` and `Migrator.script()` render the SQL a run would execute for DBA review.
+- `AsyncMigrator`: the migration runner on an AsyncAdapter with transactional application and awaited callable steps.
+
 ## 2.3.0 (2026-08-14)
 
 ### Added

sustained-2.5.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: sustained
+Version: 2.5.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
+Author-email: Christopher Wetherill <git@tbmh.org>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Sustained.py
+
+A Python query builder and lightweight ORM inspired by [Objection.js](https://vincit.github.io/objection.js/).
+
+You describe a query as chained Python methods. Sustained renders the SQL for your dialect, runs it parameterized against any DB-API 2.0 connection or pool, and hydrates the rows into your model classes.
+
+```python
+adults = User.query().where(User.c.age >= 18).orderBy('name').run()
+```
+
+## What it does
+
+- **SQL building** for the default (ANSI), Postgres, MSSQL, Presto, AWS Athena, and DuckDB dialects: joins, CTEs (including recursive), unions, window functions, CASE expressions, and subqueries. Features a dialect lacks raise `DialectError` at build time.
+- **Safe execution**: every statement runs parameterized. Transactions nest through savepoints. `update()` and `delete()` refuse to run without a WHERE clause.
+- **Writes**: `insert()`, `update()`, `delete()`, upserts with `onConflict()`, `INSERT ... SELECT`, CTAS, and RETURNING.
+- **Typed filters**: `User.query().where((User.c.age > 21) & User.c.name.like('A%'))`.
+- **Results as** model instances, dicts, pandas DataFrames, or pyarrow Tables, with `withGraphFetched()` eager loading.
+- **Schema migrations**: models declare typed columns and indexes; `Migrator.sync(models)` diffs the live database, generates the migration, applies it, and `down()` rolls it back. Destructive changes are gated behind explicit opt-ins.
+- **Async**: the same queries run through driver adapters (`asyncpg`, `aiosqlite`, or any sync driver in a worker thread) with `await query.arun()`.
+
+## What it does not do
+
+No lazy loading, no dirty tracking or `save()`, no identity map, no result caching, no cross-dialect emulation of missing features, and no guessed migrations: drops, renames, and NOT NULL backfills all require explicit opt-ins or hints. Writes and schema changes only happen when you spell them out.
+
+## Installation
+
+```bash
+python3 -m pip install sustained
+```
+
+## Usage
+
+```python
+from sustained import Model, RelationType
+
+class Person(Model):
+    tableName = 'persons'
+
+class Animal(Model):
+    tableName = 'animals'
+    relationMappings = {
+        'owner': {
+            'relation': RelationType.BelongsToOneRelation,
+            'modelClass': Person,
+            'join': {
+                'from': 'animals.ownerId',
+                'to': 'persons.id'
+            }
+        }
+    }
+
+# Build a query
+query = Animal.query().select('animals.name', 'persons.name').leftOuterJoinRelated('owner')
+
+print(query)
+# SELECT animals.name, persons.name
+# FROM animals
+# LEFT OUTER JOIN persons
+#   ON animals.ownerId = persons.id
+
+
+# Execute against any DB-API 2.0 connection
+import sqlite3
+
+conn = sqlite3.connect('app.db')
+Animal.bind(conn)
+
+# Parameterized execution with model hydration
+animals = Animal.query().where('species', '=', 'dog').orderBy('name').run()
+
+# Or take the SQL and parameters and execute them yourself
+sql, params = Animal.query().where('species', '=', 'dog').to_sql()
+# sql:    "SELECT * FROM animals WHERE species = ?"
+# params: ('dog',)
+```
+
+Models can manage their own schema:
+
+```python
+from sustained.migrations import Migrator
+from sustained.schema import Integer, String, Text
+
+class User(Model):
+    tableName = 'users'
+    tableColumns = {
+        'id': Integer(primary_key=True, autoincrement=True),
+        'email': String(120, unique=True, nullable=False),
+    }
+
+migrator = Migrator(conn, [])
+migrator.sync([User])              # creates the users table
+
+User.tableColumns['bio'] = Text()
+migrator.sync([User])              # adds only the bio column
+migrator.down()                    # rolls it back
+```
+
+## Documentation
+
+The [documentation](https://sustained.tbmh.org/) covers [models](https://sustained.tbmh.org/models), [queries](https://sustained.tbmh.org/queries), [filtering](https://sustained.tbmh.org/filtering), [grouping](https://sustained.tbmh.org/grouping), [relations and joins](https://sustained.tbmh.org/relations), [execution, pooling, and async](https://sustained.tbmh.org/executing), and [schema and migrations](https://sustained.tbmh.org/schema). The [API reference](https://sustained.tbmh.org/reference) lists every public method by task.
+
+## Development
+
+To install from source:
+
+```bash
+git clone https://github.com/wetherc/sustained.git
+cd sustained
+python3 -m pip install -e .
+```
+
+This project uses `pre-commit` to format code, lint, type check, and run the test suite before each commit:
+
+```bash
+pip install pre-commit
+pre-commit install
+```

sustained-2.5.0/README.md

@@ -0,0 +1,117 @@
+# Sustained.py
+
+A Python query builder and lightweight ORM inspired by [Objection.js](https://vincit.github.io/objection.js/).
+
+You describe a query as chained Python methods. Sustained renders the SQL for your dialect, runs it parameterized against any DB-API 2.0 connection or pool, and hydrates the rows into your model classes.
+
+```python
+adults = User.query().where(User.c.age >= 18).orderBy('name').run()
+```
+
+## What it does
+
+- **SQL building** for the default (ANSI), Postgres, MSSQL, Presto, AWS Athena, and DuckDB dialects: joins, CTEs (including recursive), unions, window functions, CASE expressions, and subqueries. Features a dialect lacks raise `DialectError` at build time.
+- **Safe execution**: every statement runs parameterized. Transactions nest through savepoints. `update()` and `delete()` refuse to run without a WHERE clause.
+- **Writes**: `insert()`, `update()`, `delete()`, upserts with `onConflict()`, `INSERT ... SELECT`, CTAS, and RETURNING.
+- **Typed filters**: `User.query().where((User.c.age > 21) & User.c.name.like('A%'))`.
+- **Results as** model instances, dicts, pandas DataFrames, or pyarrow Tables, with `withGraphFetched()` eager loading.
+- **Schema migrations**: models declare typed columns and indexes; `Migrator.sync(models)` diffs the live database, generates the migration, applies it, and `down()` rolls it back. Destructive changes are gated behind explicit opt-ins.
+- **Async**: the same queries run through driver adapters (`asyncpg`, `aiosqlite`, or any sync driver in a worker thread) with `await query.arun()`.
+
+## What it does not do
+
+No lazy loading, no dirty tracking or `save()`, no identity map, no result caching, no cross-dialect emulation of missing features, and no guessed migrations: drops, renames, and NOT NULL backfills all require explicit opt-ins or hints. Writes and schema changes only happen when you spell them out.
+
+## Installation
+
+```bash
+python3 -m pip install sustained
+```
+
+## Usage
+
+```python
+from sustained import Model, RelationType
+
+class Person(Model):
+    tableName = 'persons'
+
+class Animal(Model):
+    tableName = 'animals'
+    relationMappings = {
+        'owner': {
+            'relation': RelationType.BelongsToOneRelation,
+            'modelClass': Person,
+            'join': {
+                'from': 'animals.ownerId',
+                'to': 'persons.id'
+            }
+        }
+    }
+
+# Build a query
+query = Animal.query().select('animals.name', 'persons.name').leftOuterJoinRelated('owner')
+
+print(query)
+# SELECT animals.name, persons.name
+# FROM animals
+# LEFT OUTER JOIN persons
+#   ON animals.ownerId = persons.id
+
+
+# Execute against any DB-API 2.0 connection
+import sqlite3
+
+conn = sqlite3.connect('app.db')
+Animal.bind(conn)
+
+# Parameterized execution with model hydration
+animals = Animal.query().where('species', '=', 'dog').orderBy('name').run()
+
+# Or take the SQL and parameters and execute them yourself
+sql, params = Animal.query().where('species', '=', 'dog').to_sql()
+# sql:    "SELECT * FROM animals WHERE species = ?"
+# params: ('dog',)
+```
+
+Models can manage their own schema:
+
+```python
+from sustained.migrations import Migrator
+from sustained.schema import Integer, String, Text
+
+class User(Model):
+    tableName = 'users'
+    tableColumns = {
+        'id': Integer(primary_key=True, autoincrement=True),
+        'email': String(120, unique=True, nullable=False),
+    }
+
+migrator = Migrator(conn, [])
+migrator.sync([User])              # creates the users table
+
+User.tableColumns['bio'] = Text()
+migrator.sync([User])              # adds only the bio column
+migrator.down()                    # rolls it back
+```
+
+## Documentation
+
+The [documentation](https://sustained.tbmh.org/) covers [models](https://sustained.tbmh.org/models), [queries](https://sustained.tbmh.org/queries), [filtering](https://sustained.tbmh.org/filtering), [grouping](https://sustained.tbmh.org/grouping), [relations and joins](https://sustained.tbmh.org/relations), [execution, pooling, and async](https://sustained.tbmh.org/executing), and [schema and migrations](https://sustained.tbmh.org/schema). The [API reference](https://sustained.tbmh.org/reference) lists every public method by task.
+
+## Development
+
+To install from source:
+
+```bash
+git clone https://github.com/wetherc/sustained.git
+cd sustained
+python3 -m pip install -e .
+```
+
+This project uses `pre-commit` to format code, lint, type check, and run the test suite before each commit:
+
+```bash
+pip install pre-commit
+pre-commit install
+```

{sustained-2.3.0 → sustained-2.5.0}/docs/_layouts/default.html

@@ -23,14 +23,17 @@
 
         <p>{{ site.description | default: site.github.project_tagline }}</p>
 
-        <span>
+        <nav>
           <ul>
             <li><a href="index">Home</a></li>
             <li><a href="models">Models</a></li>
             <li><a href="queries">Building Queries</a></li>
             <li><a href="filtering">Filtering Queries</a></li>
-            <li><a href="relations">Relations</a></li>
             <li><a href="grouping">Grouping</a></li>
+            <li><a href="relations">Relations and Joins</a></li>
+            <li><a href="executing">Executing Queries</a></li>
+            <li><a href="schema">Schema and Migrations</a></li>
+            <li><a href="reference">API Reference</a></li>
           </ul>
         </nav>
 

{sustained-2.3.0 → sustained-2.5.0}/docs/assets/css/style.scss

@@ -25,8 +25,8 @@ nav ul {
 }
 
 nav ul li {
-  display: inline-block;
-  margin-right: 15px;
+  display: block;
+  margin-bottom: 5px;
 }
 
 nav ul li a {
@@ -38,3 +38,11 @@ nav ul li a {
 nav ul li a:hover {
   text-decoration: underline;
 }
+
+/* The minimal theme bolds links on hover. Bold text is wider, so table
+   columns jitter as the pointer moves over them. Underline instead. */
+section a:hover,
+section a:focus {
+  font-weight: normal;
+  text-decoration: underline;
+}

{sustained-2.3.0 → sustained-2.5.0}/docs/executing.md

@@ -5,7 +5,7 @@ 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).
+The connection's parameter style must match the dialect. The default and MSSQL dialects use `?` (qmark). The Postgres and Athena dialects use `%s` (format), matching psycopg and pyathena.
 
 ## Binding a Connection
 

{sustained-2.3.0 → sustained-2.5.0}/docs/filtering.md

@@ -156,7 +156,8 @@ You can nest these groups as deeply as you need.
 #     (genre = 'Drama' AND rating > 8)
 #   )
 
-query = Movie.query()
+query = (
+    Movie.query()
     .where("status", "=", "available")
     .andWhere(lambda q: (
         q.where(lambda group1: (
@@ -165,7 +166,8 @@ query = Movie.query()
             group2.where("genre", "=", "Drama").andWhere("rating", ">", 8)
         ))
     ))
-
+)
+```
 
 ## `whereLike` and `whereILike`
 

{sustained-2.3.0 → sustained-2.5.0}/docs/grouping.md

@@ -43,10 +43,12 @@ print(query)
 #   GROUP BY customer_id
 #   HAVING COUNT(id) > 5
 #      AND SUM(total_amount) > 100
-query = Order.query()
+query = (
+    Order.query()
     .groupBy("customer_id")
     .having("COUNT(id)", ">", 5)
     .andHaving("SUM(total_amount)", ">", 100)
+)
 print(query)
 
 # Use `orHaving` to add an alternative condition
@@ -54,10 +56,12 @@ print(query)
 #   GROUP BY customer_id
 #   HAVING AVG(item_price) < 50
 #       OR MAX(quantity) > 10
-query = Order.query()
+query = (
+    Order.query()
     .groupBy("customer_id")
     .having("AVG(item_price)", "<", 50)
     .orHaving("MAX(quantity)", ">", 10)
+)
 print(query)
 ```
 > **Note:** The first `having` call in a chain cannot be an `orHaving` or `andHaving`. It must be a plain `having`.
@@ -75,10 +79,9 @@ This generates a `HAVING col IN (...)` clause, useful for checking if an aggrega
 # GROUP BY order_status
 # HAVING order_status IN ('completed', 'shipped')
 query = (
-    Order
-        .query()
-        .groupBy("order_status")
-        .havingIn("order_status", ["completed", "shipped"]
+    Order.query()
+    .groupBy("order_status")
+    .havingIn("order_status", ["completed", "shipped"])
 )
 print(query)
 
@@ -87,10 +90,12 @@ print(query)
 #   GROUP BY product_category
 #   HAVING SUM(sales_count) > 100
 #     AND product_category IN ('Electronics', 'Books')
-query = Order.query()
+query = (
+    Order.query()
     .groupBy("product_category")
     .having("SUM(sales_count)", ">", 100)
     .andHavingIn("product_category", ["Electronics", "Books"])
+)
 print(query)
 ```
 
@@ -162,13 +167,15 @@ This is useful for creating conditions like `... AND (condition A OR condition B
 # HAVING COUNT(id) > 5
 #    AND (SUM(total_amount) < 100 OR MAX(quantity) <= 2)
 
-query = Order.query()
+query = (
+    Order.query()
     .groupBy("customer_id")
     .having("COUNT(id)", ">", 5)
     .andHaving(lambda q: (
         q.having("SUM(total_amount)", "<", 100)
          .orHaving("MAX(quantity)", "<=", 2)
     ))
+)
 print(query)
 ```
 
@@ -185,7 +192,8 @@ You can nest these groups as deeply as needed to construct intricate `HAVING` lo
 #     (inventory_count < 10 AND product_type = 'clearance')
 #   )
 
-query = Order.query()
+query = (
+    Order.query()
     .groupBy("product_type")
     .having("total_revenue", ">", 10000)
     .andHaving(lambda q: (
@@ -197,5 +205,6 @@ query = Order.query()
                   .andHaving("product_type", "=", "clearance")
         ))
     ))
+)
 print(query)
 ```

sustained-2.5.0/docs/index.md

@@ -0,0 +1,54 @@
+---
+layout: default
+title: Sustained Documentation
+---
+
+Sustained is a Python query builder and lightweight ORM inspired by [Objection.js](https://vincit.github.io/objection.js/). You describe a query as chained Python methods; Sustained renders the SQL for your dialect, runs it parameterized, and hydrates the rows into your model classes.
+
+```python
+adults = User.query().where(User.c.age >= 18).orderBy('name').run()
+```
+
+## What Sustained does
+
+- **Builds SQL programmatically.** Selects, aggregates, window functions, CASE expressions, every join type, CTEs (including recursive), unions, INTERSECT and EXCEPT, subqueries in SELECT, FROM, WHERE, and JOIN clauses.
+- **Targets six dialects.** ANSI (default), PostgreSQL, MSSQL, Presto, AWS Athena, and DuckDB. Quoting, placeholders, upsert syntax, LIMIT/OFFSET spelling, and function names all follow the dialect. Unsupported features raise `DialectError` at build time instead of failing in the database.
+- **Executes queries safely.** Every statement runs parameterized against any DB-API 2.0 connection or a `ConnectionPool`. Transactions nest through savepoints. `update()` and `delete()` refuse to run without a WHERE clause.
+- **Writes data.** `insert()`, `update()`, `delete()`, upserts through `onConflict()`, `INSERT ... SELECT`, CREATE TABLE AS, and RETURNING.
+- **Hydrates results.** Rows become model instances, plain dicts, pandas DataFrames, or pyarrow Tables. Relations eager load with `withGraphFetched()`.
+- **Manages schema.** Models declare typed columns and indexes. `Migrator.sync()` diffs the live database against your models, generates a migration, applies it, and `down()` rolls it back. Destructive changes are opt-in.
+- **Runs async.** The same queries run through driver adapters with `await query.arun()`, including asyncpg and aiosqlite, plus an `AsyncMigrator`.
+
+## What Sustained does not do
+
+These are design decisions, not roadmap gaps. Knowing them up front saves you a search later.
+
+- **No lazy loading or identity map.** A hydrated model instance is a plain object. Accessing an unloaded relation does not trigger a query; use `withGraphFetched()` or a join.
+- **No dirty tracking or `save()`.** Writes are explicit statements: `User.query().update({...}).where(...)`. Sustained never writes anything you did not spell out.
+- **No connection management beyond the pool.** You create connections (or a factory for the pool); Sustained never reads connection strings or config files.
+- **No cross-dialect emulation of missing features.** If MSSQL has no RETURNING, `returning()` raises `DialectError` there. Sustained tells you at build time rather than emulating with extra queries.
+- **No guessed migrations.** Autogeneration refuses to invent anything lossy. Drops need `allow_drops=True`, renames need explicit hints, and NOT NULL changes need a `backfill` value. Constraint drift is reported, never silently migrated.
+- **No query result caching.** Every `run()` hits the database.
+
+## Finding your way
+
+| You want to | Read |
+| --- | --- |
+| Map classes to tables, catch column typos | [Models](./models) |
+| Build a SELECT: columns, functions, CTEs, unions, pagination | [Queries](./queries) |
+| Filter rows: where methods and typed predicates | [Filtering](./filtering) |
+| Aggregate and filter groups | [Grouping](./grouping) |
+| Join tables and define relations | [Relations and Joins](./relations) |
+| Run queries, write data, transactions, pooling, async | [Executing Queries](./executing) |
+| Create tables, generate and roll back migrations | [Schema and Migrations](./schema) |
+| Look up any method by name | [API Reference](./reference) |
+
+New to Sustained? Read the pages in the order above. Each builds on the one before it.
+
+## Installing
+
+```bash
+python3 -m pip install sustained
+```
+
+Sustained has no required dependencies. pandas and pyarrow are optional, only needed for `to_df()` and `to_arrow()`.

{sustained-2.3.0 → sustained-2.5.0}/docs/models.md

@@ -119,7 +119,17 @@ Person.id          # "persons.id"
 Person.firstNam    # AttributeError
 ```
 
-The `create_model` function accepts the same declaration through its `columns` argument.
+The `create_model` function accepts the same declaration through its `columns` argument. Models that declare typed columns in `tableColumns` (see [Schema and Migrations](./schema)) get the strict column set derived automatically.
+
+## Typed Column References
+
+Beyond plain name strings, every model exposes a typed column namespace at `Model.c`. Python comparison operators on these references build `Predicate` objects for `where()` and `having()`:
+
+```python
+User.query().where((User.c.age > 21) & User.c.name.like('A%'))
+```
+
+See [Filtering](./filtering#typed-predicates) for the full operator set.
 
 ## The Model Registry
 

{sustained-2.3.0 → sustained-2.5.0}/docs/queries.md

@@ -214,6 +214,17 @@ query = User.query().select_func(
 
 A string argument that is not a plain column name raises a `ValueError` when the query renders. This protects you from a literal that silently becomes a column, or the reverse.
 
+Every registered function is also available as a method of its own name, so these two lines build the same query:
+
+```python
+User.query().select_func('COALESCE', 'nickname', 'first_name', alias='d')
+User.query().coalesce('nickname', 'first_name', alias='d')
+```
+
+The shortcuts include `lower()`, `upper()`, `coalesce()`, `concat()`, `substring()`, `trim()`, `length()`, `round()`, `abs()`, `ceiling()`, `floor()`, `mod()`, `now()`, and `getdate()`.
+
+Some functions translate per dialect: `now()` renders as `GETDATE()` on MSSQL, `getdate()` renders as `NOW()` on Postgres, and `length()` renders as `LEN()` on MSSQL. You write the name you know, and the dialect gets the spelling it needs. A registered function raises `DialectError` on a dialect that has no spelling for it, so `now()` fails on the default dialect at build time instead of in the database.
+
 ##### Dialect Validation
 
 A key feature of `.select_func()` is its runtime dialect validation. The method checks the function name against an internal `FunctionRegistry`.
@@ -256,7 +267,7 @@ While `.select_func()` can be used for any function, the `FunctionRegistry` incl
 You can use a `Subquery` object to embed a subquery directly into your `SELECT` list.
 
 ```python
-from sustained import Subquery
+from sustained.expressions import Subquery
 
 # SELECT
 #   id,
@@ -463,6 +474,7 @@ Currently, the following dialects are supported:
 
 *   **`Dialects.DEFAULT`**: Standard ANSI SQL (Default)
 *   **`Dialects.PRESTO`**: SQL dialect for the Presto query engine.
+*   **`Dialects.ATHENA`**: SQL dialect for AWS Athena (Trino-based). Inherits Presto's query behavior with Athena's DDL, `%s` placeholders for pyathena, and MERGE upserts on Iceberg tables.
 *   **`Dialects.MSSQL`**: SQL dialect for Microsoft SQL Server.
 *   **`Dialects.POSTGRES`**: SQL dialect for PostgreSQL.
 *   **`Dialects.DUCKDB`**: SQL dialect for DuckDB.
@@ -529,6 +541,6 @@ sql, params = User.query().select('name').where('id', '=', 1).to_sql()
 cursor.execute(sql, params)
 ```
 
-The placeholder style follows the dialect: `?` by default and for MSSQL, `%s` for Postgres.
+The placeholder style follows the dialect: `?` by default and for MSSQL, `%s` for Postgres and Athena.
 
 Sustained can also execute queries for you and hydrate the results into model instances. See [Executing Queries](./executing) for `Model.bind()`, `run()`, `first()`, and eager loading, and for the `insert()`, `update()`, and `delete()` statement builders.