SQLAlchemy

Gold Lapel ships SQLAlchemy support inside the Python wrapper — no separate plugin to install. Change one import; Core, the ORM, and async engines all carry on as before.

Install

pip install goldlapel

The same install you'd use anywhere else in Python. Install SQLAlchemy and your Postgres driver of choice (psycopg2, psycopg3, or asyncpg) separately — the SQLAlchemy glue lives inside the goldlapel package at goldlapel.sqlalchemy.

Quick start (sync)

Import create_engine from goldlapel.sqlalchemy instead of sqlalchemy — everything else stays the same. The L1 native cache activates with the proxy; repeated reads serve in microseconds.

from sqlalchemy import create_engine
engine = create_engine("postgresql://user:pass@host:5432/mydb")

from goldlapel.sqlalchemy import create_engine
engine = create_engine("postgresql://user:pass@host:5432/mydb")

Full sync example:

from goldlapel.sqlalchemy import create_engine
from sqlalchemy import text

engine = create_engine("postgresql://user:pass@host:5432/mydb")

with engine.connect() as conn:
    result = conn.execute(text("SELECT * FROM users"))

Quick start (async)

Use create_async_engine for async applications. Dialect suffixes like +asyncpg are handled for you:

from goldlapel.sqlalchemy import create_async_engine
from sqlalchemy import text

engine = create_async_engine("postgresql+asyncpg://user:pass@host:5432/mydb")

async with engine.connect() as conn:
    result = await conn.execute(text("SELECT * FROM users"))

The sync Engine path uses the in-process L1 native cache (microsecond reads). AsyncEngine queries route through the Gold Lapel proxy for L2 caching and optimization — native L1 cache for async engines lands in a follow-up release.

SQLAlchemy ORM

The ORM sits on top of the engine, so once the engine is wired through Gold Lapel, everything above it — Session, declarative models, Query, select(), relationships — flows through automatically:

from goldlapel.sqlalchemy import create_engine
from sqlalchemy.orm import DeclarativeBase, Session, Mapped, mapped_column

class Base(DeclarativeBase): ...

class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    email: Mapped[str]

engine = create_engine("postgresql://user:pass@host:5432/mydb")

with Session(engine) as session:
    users = session.query(User).filter(User.email.like("%@example.com")).all()

FastAPI

A complete async setup with session management:

from fastapi import FastAPI
from goldlapel.sqlalchemy import create_async_engine
from sqlalchemy.ext.asyncio import async_sessionmaker
from sqlalchemy import text

engine = create_async_engine("postgresql+asyncpg://user:pass@host:5432/mydb")
SessionLocal = async_sessionmaker(engine)

app = FastAPI()

@app.get("/users")
async def list_users():
    async with SessionLocal() as session:
        result = await session.execute(text("SELECT * FROM users"))
        return result.mappings().all()

Alternative: init()

Rewrites DATABASE_URL to route through the proxy, so any engine you create afterward connects through Gold Lapel without the wrapper import:

import goldlapel.sqlalchemy
import os

goldlapel.sqlalchemy.init()

# Now create your engine as usual — it connects through Gold Lapel
from sqlalchemy import create_engine
engine = create_engine(os.environ["DATABASE_URL"])

Options

Optional proxy settings via keyword arguments on create_engine / create_async_engine:

engine = create_engine(
    "postgresql://user:pass@host:5432/mydb",
    goldlapel_port=9000,
    goldlapel_config={"mode": "waiter", "pool_size": 50},
    goldlapel_extra_args=["--threshold-duration-ms", "200"],
)

The same options are available on init() with shorter names:

goldlapel.sqlalchemy.init(
    port=9000,
    config={"mode": "waiter", "pool_size": 50},
    extra_args=["--threshold-duration-ms", "200"],
)

Dialect suffixes

SQLAlchemy dialect suffixes (+asyncpg, +psycopg, +pg8000) are handled for you. Pass your usual SQLAlchemy connection URL — Gold Lapel strips the suffix when building the upstream connection and preserves it for the local proxy connection.

Tuning

goldlapel_config takes the same dict as goldlapel.start(config=...) — see the configuration reference for every setting. goldlapel_extra_args and GOLDLAPEL_* environment variables are also available.

Requirements

• Python 3.9+
• SQLAlchemy 1.4+
• goldlapel 0.2+
• PostgreSQL (TCP connections)

How it works

goldlapel.sqlalchemy wraps SQLAlchemy's create_engine and create_async_engine. When you create an engine, it extracts the database connection details from your URL, calls goldlapel.start() to spawn the proxy, and wires a connection with the L1 native cache into the engine (sync path). Subsequent queries — Core or ORM — flow through Gold Lapel.

The init() alternative takes a different approach: it rewrites DATABASE_URL in your environment so any engine you create afterward connects through the proxy without the wrapper import.

For the underlying Python wrapper API — goldlapel.start(), async support, and the wrapper helpers — see the Python guide.

GitHub · PyPI