Sustained.py

A Python query builder and lightweight ORM inspired by 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 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 declare typed columns and manage their own schema: Migrator.sync(models) diffs the live database, generates the migration, applies it, and down() rolls it back, with destructive changes gated behind explicit opt-ins. Async services run the same queries through driver adapters with await query.arun().

Installation

python3 -m pip install sustained

Local Installation from Source

To install sustained from source for local development:

Clone the repository:

git clone https://github.com/wetherc/sustained.git
cd sustained

Install in editable mode:
```
python3 -m pip install -e .
```

Usage

from sustained import Model, RelationType, create_model

class Person(Model):
    database = 'my_db'
    tableSchema = 'public'
    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


# Build a more complex query with a CTE and a raw join
active_owners = Person.query().select('id').where('status', '=', 'active')

query = (
    Animal.query()
    .with_('active_owners', active_owners)
    .join('active_owners', 'animals.ownerId', '=', 'active_owners.id')
    .select('animals.name')
)

print(query)
# WITH active_owners AS (
#   SELECT id
#   FROM persons
#   WHERE status = 'active'
# )
# SELECT animals.name
# FROM animals
# JOIN active_owners
#   ON animals.ownerId = active_owners.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',)

See the documentation for models, filtering, grouping, relations, and execution guides.

Development

This project uses pre-commit to enforce code quality and run tests before committing code.

Pre-commit Hooks Setup

Install pre-commit:
```
pip install pre-commit
```
Install the Git hooks: From the root of the project directory, run:
```
pre-commit install
```

Release files for sustained 2.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sustained 2.4.0
File	Size	Uploaded
sustained-2.4.0.tar.gz	119.9 kB	Aug 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for sustained 2.4.0
File	Interpreter	ABI	Platform	Reset
sustained-2.4.0-py3-none-any.whl 78.5 kB Aug 14, 2026	Python 3	none	any	Details

Total release size: 198.4 kB

Release files / sustained-2.4.0.tar.gz

Download URL	sustained-2.4.0.tar.gz
Size	119.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`2eb5e1ca6fe31b0025ab721a59b2fb3c67173ee12b25aa04b1e7aad002284e03`
BLAKE2b-256 checksum How to use checksums	`4db96f07248207742bbc4a364fefd5c22582a4e0f8333424bd18205ef530252b`
Upload date	Aug 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.6`

Release files / sustained-2.4.0-py3-none-any.whl

Download URL	sustained-2.4.0-py3-none-any.whl
Size	78.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`42b99facf6b992d820572895df89df74e35f9f6c1d4cb4998118b58d1c4295ed`
BLAKE2b-256 checksum How to use checksums	`eaa3c7867c447c7b1a12b7a71af9e08019231b3d5b29215f20f809227d492af4`
Upload date	Aug 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.6`