GINO Documentation

GINO (GINO Is Not ORM) is a lightweight asynchronous ORM for Python. Key features include:

• SQLAlchemy Integration: Uses SQLAlchemy core for query building and supports the SQLAlchemy ecosystem (e.g., Alembic for migrations).
• Asynchronous Engine: Provides an asynchronous SQLAlchemy-alike engine, connection, and dialect API.
• Model Support: Asynchronous-friendly CRUD objective models.
• Database Support: Robust PostgreSQL JSONB support. Supports PostgreSQL with asyncpg and MySQL with aiomysql.
• Management: Well-considered contextual connection and transaction management.
• Framework Compatibility: Community support for Starlette/FastAPI, aiohttp, Sanic, Tornado, and Quart.

GINO (GINO Is Not ORM) is a lightweight asynchronous ORM built on top of SQLAlchemy core for Python asyncio.

Key Compatibility Notes:

• Built on: SQLAlchemy core
• Runtime: asyncio
• Supported Dialect: Currently supports only asyncpg.

GINO supports three levels of integration depending on your needs:

1. Minimalist: Use GINO only for asynchronous execution while following SQLAlchemy Core principles.
2. Table-only: Define tables without using object mapping (avoids 'objects' entirely).
3. Full-power: Use the non-typical asynchronous ORM features for maximum convenience.

To build one-to-many relationships, use the distinct() method on a model loader. This allows GINO to combine multiple rows into a single parent instance by using a setter or method to collect children.

When using Parent.distinct(Parent.id).load(add_child=Child), GINO reuses the same parent instance for rows with the same ID and calls the add_child setter/method for each associated child found in the result set.

query = Child.outerjoin(Parent).select()
parents = await query.gino.load(
    Parent.distinct(Parent.id).load(add_child=Child)
).all()

To load a tree-like structure (where a model references itself), you must use an alias for the parent model to avoid name collisions in the SQL join. This is currently an experimental feature.

Use Model.alias() to create the alias and .on() to define the self-referencing join condition.

class Category(db.Model):
    __tablename__ = 'categories'
    id = db.Column(db.Integer, primary_key=True)
    parent_id = db.Column(db.Integer, db.ForeignKey('categories.id'))

# Load leaf categories with their parents
Parent = Category.alias()
query = Category.load(parent=Parent.on(
    Category.parent_id == Parent.id
)).where(
    ~Category.id.in_(db.select([Category.alias().parent_id]))
)

async for c in query.gino.iterate():
    print(f'Leaf: {c.id}, Parent: {c.parent.id}')

You can integrate GINO with a Starlette application using two patterns: direct initialization or an application factory pattern. The gino-starlette extension provides middleware that handles database setup and cleanup based on the provided configuration.

from starlette.applications import Starlette
from gino.ext.starlette import Gino

# Pattern 1: Direct initialization
app = Starlette()
db = Gino(app, **kwargs)

# Pattern 2: Application factory pattern
app = Starlette()
db = Gino(**kwargs)
db.init_app(app)

Install GINO using pip to get started with an asynchronous ORM built on top of SQLAlchemy core for Python asyncio. GINO supports PostgreSQL (via asyncpg) and MySQL (via aiomysql).

$ pip install gino

Organize your project using a src layout. Create a main.py to define the application factory and an asgi.py to instantiate the app for the ASGI server.

# src/gino_fastapi_demo/main.py
from fastapi import FastAPI

def get_app():
    app = FastAPI(title="GINO FastAPI Demo")
    return app

# src/gino_fastapi_demo/asgi.py
from .main import get_app

app = get_app()