Asqueel

Asqueel is a Python database layer that makes your application's data model reusable across queries, business logic and user interfaces. Declare tables, relationships, calculated fields and UI metadata together, then work with that model through a live db object.

Asqueel is the port of GenroPy's SQL layer to a standalone library.

It addresses a common source of duplication in database applications: the same relationship, calculation or field description gets rewritten in queries, service code and screens. In Asqueel, a related customer name or an invoice calculation can be defined once as a model column and reused wherever you query it. UI code can read the field's label and formatting from the same model. SQL remains available for expressions; Asqueel resolves model names and relation paths and binds query parameters.

Asqueel brings Genropy's approach to database applications into a standalone library. The current checkout supports PostgreSQL and SQLite, with explicit writes and transaction completion. Start with What is Asqueel? for the approach and an example. The manual also covers planned capabilities; Current status identifies what works today and what remains to be implemented.

The alternative hierarchical model supports SELECT compilation and fetch/count execution, including supported to-one relations, formulas, subqueries and filters. It returns mutable Toolbox NamedList rows on PostgreSQL and SQLite; see the scope and legacy comparison. The default renderer is unchanged; to-many operations still have no handlers.

Install

Version 0.6.0 completes native package configuration → live model objects → migration JSON, verified on 74 test_invoice_pg tables across sys, adm and invc. See the native source example and release notes for the delivered scope and deferred compiler/runtime behavior.

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, AsqueelDb


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")


db = AsqueelDb(Shop)
customer = db.table("sales.customer")
query = customer.query(
    columns="$id, $name", where="$id >= :minimum_id",
    minimum_id=1, order_by="$id",
)
print(query.sqltext)  # Compiles without opening a connection.
db.closeConnection()

Against an existing sales.customer table, call query.fetch() to get a list of mutable Toolbox NamedList rows (name and position access). Table writes and reads share the selected thread-local connection, opened lazily. Use db.commit() and db.rollback(). Select a named connection with db.tempEnv(connectionName=...). db.closeConnection() rolls back pending work and keeps the database usable; with session(db): calls it at exit.

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.

Configure, migrate and explore a complete example

The two-schema example separates configuration, schemas, table declarations and business logic. It includes users/access logs and customers/products/invoices/rows, with explicit imports and EnvResolver connection settings.

From this source checkout:

python -m pip install -e ".[postgresql,migration]"
asqueel register gestionale ./examples/two_schemas
asqueel check gestionale
asqueel db plan gestionale
asqueel db apply gestionale
asqueel shell gestionale

Set the example's PG* environment variables for your PostgreSQL server before plan/apply; the database account must have the required privileges. check is offline. The registry in ~/.asqueel stores the folder path, not credentials. The console provides db; the same name works with AsqueelDb("gestionale") in Python. See the complete walkthrough and CLI reference for setup, migrations and transaction behavior.

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.

SQLite configuration and runtime limitations are described in the SQLite guide.