Skip to content

README.md

Latest commit

 

History

History
190 lines (137 loc) · 5.85 KB

README.md

File metadata and controls

190 lines (137 loc) · 5.85 KB

Alchemy QL

Lightweight GraphQL engine powered by SQLAlchemy

CI Package version Supported Python versions

🚀 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

📘 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.