Django + Django ORM

Drop-in Django database backend that starts Gold Lapel automatically on first connection. Works transparently with the Django ORM, migrations, and manage.py.

Install

pip install goldlapel django

The Django glue ships inside the goldlapel package at goldlapel.django — no extra install step. Install Django separately with regular pip.

Usage

Replace your database engine — everything else stays the same:

# settings.py
DATABASES = {
    "default": {
        "ENGINE": "goldlapel.django",  # was: django.db.backends.postgresql
        "NAME": "mydb",
        "USER": "myuser",
        "PASSWORD": "mypassword",
        "HOST": "localhost",
        "PORT": "5432",
    }
}

Gold Lapel starts when Django opens its first database connection, watches your query patterns, and automatically optimizes your database. The L1 native cache activates automatically — repeated reads serve in microseconds. Every Django ORM call (Model.objects.filter, QuerySet, select_related, raw SQL) flows through the proxy unchanged.

Management commands

manage.py migrate, makemigrations, dbshell, loaddata, and dumpdata all work without any change — they go through the same backend and therefore through Gold Lapel. Writes invalidate the cache automatically; migrations see fresh data.

Configuration

Optional proxy settings live under OPTIONS.goldlapel in your database config:

DATABASES = {
    "default": {
        "ENGINE": "goldlapel.django",
        "NAME": "mydb",
        "USER": "myuser",
        "PASSWORD": "mypassword",
        "HOST": "localhost",
        "PORT": "5432",
        "OPTIONS": {
            "goldlapel": {
                "port": 9000,
                "config": {
                    "mode": "waiter",
                    "pool_size": 50,
                },
                "extra_args": ["--threshold-duration-ms", "200"],
            }
        },
    }
}

The config dict takes the same keys as goldlapel.start(config=...) — see the configuration reference for every setting. extra_args and environment variables (GOLDLAPEL_*) both work as secondary escape hatches.

Multiple Databases

Each database connection needs its own proxy port. Assign a unique port per entry:

DATABASES = {
    "default": {
        "ENGINE": "goldlapel.django",
        "HOST": "db1.example.com",
        "OPTIONS": {"goldlapel": {"port": 7932}},
    },
    "analytics": {
        "ENGINE": "goldlapel.django",
        "HOST": "db2.example.com",
        "OPTIONS": {"goldlapel": {"port": 7942}},
    },
}

Django's database router, read replicas, and multi-tenant patterns all continue to work — each connection gets its own Gold Lapel instance.

Requirements

• Python 3.9+
• Django 4.2+
• goldlapel 0.2+
• PostgreSQL (TCP connections only)

Upgrading from v0.1

The goldlapel[django] install extra was removed in v0.2. Django is now installed separately, and the glue code always ships inside the main goldlapel package:

# v0.1.x (old) — single pinned install extra
pip install goldlapel[django]

# v0.2 (new) — install goldlapel and django separately
pip install goldlapel django

• Install command changed — pip install goldlapel[django] is gone. Install goldlapel and django separately.
• Import path is unchanged — "goldlapel.django" is still the ENGINE value.
• OPTIONS.goldlapel shape is unchanged — existing port / extra_args / config keys work as before.
• Internally the backend now calls the new goldlapel.start() factory — behaviour is identical to v0.1 from Django's perspective.

How It Works

goldlapel.django subclasses Django's built-in PostgreSQL backend. On first connection, it builds the upstream database URL from your DATABASES entry, calls goldlapel.start() to spawn the proxy, and returns a wrapped connection with the L1 native cache built in. All subsequent Django ORM queries flow through Gold Lapel automatically — no changes to models, querysets, or migrations.

GitHub · PyPI