Asqueel

Define SQL models in Python, compile parameterized queries, and work with PostgreSQL through a synchronous API. Asqueel keeps logical names, physical database names, relationships, and column UI metadata in a shared model.

The developer manual describes the intended delivery contract, including designed features. See Current status for implementation availability and open decisions.

Install

python -m pip install "asqueel[postgresql]"

Use asqueel for model building and offline compilation only. Add the migration extra to use the separate schema migration integration. From a checkout, run python -m pip install -e ".[postgresql]" in the repository root.

Build an application database

Declare the model and connection configuration in one recipe:

from asqueel import SqlDatabaseConfig, build_database


class Shop(SqlDatabaseConfig):
    def main(self, root):
        db = root.db("shop", conninfo="dbname=shop")
        customer = db.schemas().schema("sales").tables().table("customer", pkey="id")
        columns = customer.columns()
        columns.column("id", dtype="L")
        columns.column("name", dtype="T", x_ui={"label": "Customer name"})


with build_database(Shop) as db:
    customer = db.table("sales.customer")
    query = customer.query(
        columns="$id, $name", where="$id >= :minimum_id",
        params={"minimum_id": 1}, order_by="$id",
    )
    print(query.sqltext)  # Compiles without opening a connection.

Against an existing sales.customer table, call query.fetch() to get a list of dictionaries. Table writes and reads share a lazy session. Use db.commit() and db.rollback(), or group operations with with db.transaction():. Closing the database rolls back pending work; with db: does not commit it.

Construction does not connect or create tables. The runnable quickstart includes explicit disposable schema setup and cleanup. Configuration explains layered recipes and live table objects. The separate compiler and low-level runtime remain available for advanced integrations.

Query expressions are application code; pass external values through parameters rather than SQL interpolation.

Learn and use Asqueel

Start with What is Asqueel? and the object model, run the quickstart, then follow the customers and invoices tutorial. The tutorial includes a complete runnable script with assertions, transaction examples and disposable-schema cleanup.

For advanced integration, see cascading grammars, the compiler, low-level execution and adapters.

The public Sphinx site contains these English guides and the API reference. To build it locally:

python -m pip install -e ".[docs]"
python -m sphinx -W --keep-going -b html docs docs/_build/html

Open docs/_build/html/index.html. Internal design notes remain in the repository and are excluded from the public documentation build.

Development checkout

For development with the migration integration, install its checkout and Asqueel with the development dependencies (replace the example path with your checkout):

pip install -e "../asqueel-migration[postgresql,validation]" -e ".[dev]"

License

Apache License 2.0 — Copyright Softwell S.r.l.