Django YDB Backend

A Django database backend for YDB, a distributed SQL database. It lets Django applications use YDB through the standard ORM — models, migrations, queries, relations, and the contrib apps.

Features

Django ORM for CRUD, relations, and the standard contrib apps (admin, auth, sessions)
Most built-in Django field types (see Fields)
Migrations with YDB-specific adaptations
Native, race-free UPSERT via YDBManager
Multiple authentication methods

Quick start

Install

pip install django-ydb-backend

Run YDB locally

To develop against a local database, start YDB in Docker:

docker run -d --name ydb-local --hostname localhost \
  -p 2136:2136 -p 8765:8765 \
  -e YDB_USE_IN_MEMORY_PDISKS=true \
  ydbplatform/local-ydb:latest

This serves a ready-to-use database at /local on localhost:2136 — the values used in the configuration below.

Configure

Point a Django database at YDB in settings.py:

DATABASES = {
    "default": {
        "ENGINE": "ydb_backend.backend",
        "NAME": "ydb_db",
        "HOST": "localhost",
        "PORT": "2136",
        "DATABASE": "/local",
    }
}

See Configuration for the available authentication methods.

Define a model

from django.db import models

class Product(models.Model):
    sku = models.CharField(max_length=20, primary_key=True)
    name = models.CharField(max_length=100)
    price = models.IntegerField()

Give every model at least one non-primary-key field — YDB cannot insert a row whose only column is an auto-generated primary key.

Migrate and query

python manage.py makemigrations
python manage.py migrate

Product.objects.create(sku="A1", name="Widget", price=9)
Product.objects.filter(price__lt=10)
Product.objects.get(sku="A1")

Before you go to production

YDB differs from PostgreSQL/MySQL in a few ways that affect application design:

It does not enforce foreign keys, uniqueness, or check constraints — enforce these in application code.
It has no savepoints: nested atomic() rollback and Django’s TestCase do not work — use TransactionTestCase for database tests.
Primary-key-only and multi-table-inheritance models cannot be inserted.

See Compatibility and limitations for the full list and the supported version matrix.