alchemyql 0.0.4

Lightweight Graph QL engine powered by SQL Alchemy

Alchemy QL

Lightweight GraphQL engine powered by SQLAlchemy

---

🚀 Key Features

Alchemy QL's key features include:

• Read Only - Provides read-only graphql interface into your database
• Data Type Support - Currently supported data types:
  • Built in types: int, float, bool, str, bytes
  • Date types: date, datetime, time
  • Enums
  • JSON fields
  • Relationships
• Query Options - Currently supported query options:
  • Filtering
  • Ordering
  • Pagination (using offset & limit)
• Sync & Async support
• Fragment Query support
• Optimised SQL Queries
• ORM Support - Currently supported sqlalchemy orm:
  • Declarative base with mapping
  • Classic declarative base

---

ℹ️ Installation

# Using pip
pip install alchemyql

# Using poetry
poetry add alchemyql

# Using uv
uv add alchemyql

# With FastAPI Extension
uv add alchemyql[fastapi]

---

📦 Dependencies

• Sqlalchemy (v2)
• Graph QL Core

---

📘 How to use

Step 1 - Create your Alchemy QL engine (sync or async):

from alchemyql import AlchemyQLSync, AlchemyQLAsync

sync_engine = AlchemyQLSync()
async_engine = AlchemyQLAsync()

Step 2 - Register your sqlalchemy tables:

from your_db import Table

engine.register(
    Table, 
    query_name="tables",
    include_fields=["field_one", "field_two"],
    filter_fields=["field_one"],
    order_fields=["field_one"],
    pagination=True,
    max_limit=100
    ...
)

Step 3 - Build your schema:

engine.build_schema()

Step 4 - Run queries:

query = "query { table { field } }"
db = session_factory() # SQLAlchemy DB session

# Sync Variation
res = sync_engine.execute_query(query=query, db_session=db)

# Async Variation
res = await async_engine.execute_query(query=query, db_session=db)

---

📘 Supported Options

Engine Creation:

Key	Type	Default	Description
max_query_depth	int	None	The maximum depth allowed for nested queries

Registering Table:

Key	Type	Default	Description
graphql_name	str	None	Customise the graphql type name (defaults to sql tablename)
query_name	str	None	Customise the top-level graphql query field name (defaults to graphql name + "s")
description	str	None	Customise the graphql type descripton
query	bool	True	Whether to allow direct querying of table
include_fields	list[str]	None	Allow only specific fields to be exposed
exclude_fields	list[str]	[]	Block specific fields from being exposed
relationships	list[str]	[]	Relationships to be exposed (target table must be registered aswell)
filter_fields	list[str]	[]	Allow filtering for specific fields
order_fields	list[str]	[]	Allow ordering for specific fields
default_order	dict[str, Order]	None	Default order to apply to queries
pagination	bool	False	Whether to support pagination
default_limit	int	None	Default number of records that can be returned in 1 query
max_limit	int	None	Maximum number of records that can be returned in 1 query

NOTE: if you do not specify include_fields or exclude_fields it will default expose all fields.

NOTE: if you specify query=False, then all filtering & ordering & pagination is disabled. This is for the case where a table should only be available via a relationship

Filtering Options:

Type	Supported Filters
int	eq, ne, gt, ge, lt, le, in
float	eq, ne, gt, ge, lt, le, in
bool	eq, ne
str	eq, ne, contains, startswith, endswith, icontains, istartswith, iendswith, in
date	eq, ne, gt, ge, lt, le, in
datetime	eq, ne, gt, ge, lt, le, in
time	eq, ne, gt, ge, lt, le, in
Enum	eq, ne, in

All other types are not currently supported for filtering.

---

📘 Logging

AlchemyQL uses the "alchemyql" logger.

Other docs can be found in: docs/

---

Security Notes

AlchemyQL is read-only, but it can still expose sensitive data if tables, fields, or relationships are registered too broadly.

• Prefer include_fields for public APIs so new database columns are not exposed automatically.
• Register only relationships that are safe for callers to traverse.
• Use max_query_depth, pagination, default_limit, and max_limit for externally reachable endpoints.
• Keep filter_fields and order_fields limited to fields that are indexed or safe to reveal.
• Add authentication and authorization at the framework layer, for example with the FastAPI router auth_dependency.

---

📘 Extensions

AlchemyQL has the following extensions:

• FastAPI - sync and async pre-created routers available (see Doc )

---

ℹ️ License

This project is licensed under the terms of the MIT license.