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.

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 alpha targets PostgreSQL, 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.

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, 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",
    params={"minimum_id": 1}, order_by="$id",
)
print(query.sqltext)  # Compiles without opening a connection.
db.close()

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.

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 (the CLI is not assumed to be in older PyPI releases):

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.