Sustained.py

A Python query builder and lightweight ORM inspired by 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.

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.0.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.0.0
File	Size	Uploaded
sustained-2.0.0.tar.gz	65.9 kB	Aug 14, 2026	Details

Built distribution (wheel)

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

Total release size: 108.7 kB

Release files / sustained-2.0.0.tar.gz

Download URL	sustained-2.0.0.tar.gz
Size	65.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`f5c78380c6bb4b7af4d77e67fa0412ec2dc597faf1e7a689a3282c49f646a4f6`
BLAKE2b-256 checksum How to use checksums	`f0afcbe78a342396356f344a4080ee7a4f27b4e80385a8eb814deb58a97ff349`
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.0.0-py3-none-any.whl

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