django-couchbase-orm 1.1.0

Couchbase database backend for Django. Drop-in replacement for SQL databases with full ORM support, plus a standalone Document API.

django-couchbase-orm

Live Demo: django-couchbase-orm-production.up.railway.app A full Django + Wagtail CMS + DRF beer catalog running on Couchbase Capella. Browse beers, read the blog, or explore the Wagtail admin.

Use Couchbase as your Django database. Drop-in backend for django.db.models.Model plus a standalone Document API for Couchbase-native patterns.

Docs: Database Backend | Document API | Wagtail | Hybrid Architecture | Testing

Two Ways to Use It

1. Django Database Backend

Standard Django models work transparently with Couchbase. Admin, forms, DRF, Wagtail - everything just works.

# settings.py
DATABASES = {
    "default": {
        "ENGINE": "django_couchbase_orm.db.backends.couchbase",
        "NAME": "mybucket",
        "USER": "Administrator",
        "PASSWORD": "password",
        "HOST": "couchbase://localhost",
    }
}
DEFAULT_AUTO_FIELD = "django_couchbase_orm.db.backends.couchbase.fields.CouchbaseAutoField"

# models.py - standard Django models, no changes needed
from django.db import models

class Article(models.Model):
    title = models.CharField(max_length=200)
    body = models.TextField()
    author = models.ForeignKey("auth.User", on_delete=models.CASCADE)
    published = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)

Everything works: makemigrations, migrate, createsuperuser, Django admin, ModelForms, DRF serializers, Wagtail CMS.

2. Document API

For Couchbase-native patterns - subdoc operations, KV fast-path, embedded documents.

# settings.py
COUCHBASE = {
    "default": {
        "CONNECTION_STRING": "couchbase://localhost",
        "USERNAME": "Administrator",
        "PASSWORD": "password",
        "BUCKET": "mybucket",
    }
}

# documents.py
from django_couchbase_orm import Document, StringField, FloatField

class Beer(Document):
    name = StringField(required=True)
    abv = FloatField()
    style = StringField()

    class Meta:
        collection_name = "beers"

Both APIs can coexist in the same project. They share the same Couchbase connection.

Install

pip install django-couchbase-orm

Requires Python 3.10+, Django 4.2+, Couchbase SDK 4.1+.

Django Backend Features

Everything you'd expect from a Django database backend:

• manage.py migrate creates Couchbase collections
• manage.py createsuperuser works
• ForeignKey, ManyToManyField with JOINs via N1QL
• select_related(), prefetch_related()
• annotate(), aggregate() with Count, Sum, Avg, Min, Max
• Q() objects, F() expressions
• All lookups: exact, icontains, startswith, in, isnull, regex, etc.
• values(), values_list(), distinct(), only(), defer()
• bulk_create(), bulk_update()
• Django admin: list, add, edit, delete, search
• Django auth: users, groups, permissions
• Django sessions (DB backend)
• ContentTypes framework
• ModelForm, DRF ModelSerializer
• Wagtail CMS (page tree, publishing, admin)

SQL-to-N1QL Translation

The backend transparently handles the differences between SQL and N1QL:

SQL	N1QL (handled automatically)
INSERT INTO	UPSERT INTO (idempotent)
SUBSTRING(s, pos)	SUBSTR(s, pos-1) (0-indexed)
IS NULL	IS NOT VALUED (handles MISSING)
CAST(x AS INT)	TONUMBER(x)
AUTO_INCREMENT	Atomic counter (binary.increment)
Sequential IDs	CouchbaseAutoField (integer PKs)

Wagtail Support

Wagtail CMS works fully with the Couchbase backend. See the live demo for a working example.

INSTALLED_APPS = [
    ...
    "wagtail", "wagtail.admin", "wagtail.images",
    "wagtail.documents", "wagtail.search",
]

# manage.py migrate - creates all Wagtail collections
# manage.py createsuperuser - create admin user
# Page tree, publishing, editing, images, documents all work

Couchbase Capella (Cloud)

Works with Couchbase Capella out of the box:

DATABASES = {
    "default": {
        "ENGINE": "django_couchbase_orm.db.backends.couchbase",
        "NAME": "my-bucket",
        "USER": "dbuser",
        "PASSWORD": "dbpassword",
        "HOST": "couchbases://cb.xxxxx.cloud.couchbase.com",
    }
}

Document API Features

For when you need Couchbase-native performance:

• KV-optimized get(pk=...) (~1ms vs ~50ms for N1QL)
• Sub-document operations (partial reads/writes)
• Embedded documents
• Django-style QuerySet with N1QL
• Signals: pre_save, post_save, pre_delete, post_delete
• Async support (asave, adelete, alist, acount)
• Custom migrations framework (cb_makemigrations, cb_migrate)

Quick Example

from django_couchbase_orm import Document, StringField, FloatField, Q

# CRUD
beer = Beer(name="IPA", abv=6.5, style="IPA")
beer.save()
beer = Beer.objects.get(pk="beer-id")   # fast KV lookup
beer.abv = 7.0
beer.save()
beer.delete()

# Queries
Beer.objects.filter(style="IPA", abv__gte=6.0).order_by("-abv")[:20]
Beer.objects.filter(Q(style="IPA") | Q(style="Pale Ale")).count()
Beer.objects.aggregate(avg_abv=Avg("abv"), total=Count("*"))

# Sub-document operations
beer.subdoc.upsert("ratings.average", 4.5)
beer.subdoc.increment("view_count", 1)
beer.subdoc.array_append("tags", "hoppy")

Configuration

Database Backend (recommended)

DATABASES = {
    "default": {
        "ENGINE": "django_couchbase_orm.db.backends.couchbase",
        "NAME": "mybucket",          # Couchbase bucket
        "USER": "Administrator",
        "PASSWORD": "password",
        "HOST": "couchbase://localhost",
        "OPTIONS": {
            "SCOPE": "_default",     # optional
        },
    }
}
DEFAULT_AUTO_FIELD = "django_couchbase_orm.db.backends.couchbase.fields.CouchbaseAutoField"

Document API

COUCHBASE = {
    "default": {
        "CONNECTION_STRING": "couchbase://localhost",
        "USERNAME": "Administrator",
        "PASSWORD": "password",
        "BUCKET": "mybucket",
        "SCOPE": "_default",
    }
}

If you use the database backend, the Document API auto-derives its config from DATABASES - no need to set both.

Fields (Document API)

Field	Type	Options
StringField	str	min_length, max_length, regex
IntegerField	int	min_value, max_value
FloatField	float	min_value, max_value
BooleanField	bool
UUIDField	uuid.UUID	auto=True
DateTimeField	datetime	auto_now, auto_now_add
DateField	date	auto_now, auto_now_add
ListField	list	field for typed elements
DictField	dict
EmbeddedDocumentField	nested
ReferenceField	FK-like

Known Limitations

• Transactions: Couchbase ACID transactions require multi-node clusters. atomic() runs as a no-op on single-node setups.
• Window functions: N1QL doesn't support OVER() clauses.
• Page moves: Wagtail page tree moves use raw SQL with reserved words. Use delete + recreate as a workaround.
• Correlated subqueries with GROUP BY: Some complex query patterns return empty results gracefully instead of crashing.
• Multi-table inheritance: Works but may have performance implications with N1QL JOINs.

Tests

1,258 tests across 42 test modules, tested on Python 3.10 - 3.13. All tests run against a real Dockerized Couchbase instance — no mocks for query execution.

Suite	Tests	What's Covered
Document API	784	Fields, QuerySet, Manager, Document CRUD, signals, pagination, migrations, auth, sessions
Django Backend	156	Connection, cursor, CRUD, JOINs, M2M, admin, forms, migrations, subqueries, bulk ops
Edge Cases	128	Boundary conditions, type coercion, null handling, return types, regression tests
Coverage Gaps	114	N1QL builders, paginator, signals, document options, aggregate+filter combos
Wagtail CRUD	28	Page create, publish, edit, unpublish, delete, revisions, admin forms
Security	27	Injection prevention, password isolation, backtick escaping
Concurrency	18	Multi-threaded CRUD, connection pool thread safety, race conditions, auto-increment contention

# Start Couchbase
docker compose -f docker-compose.test.yml up -d
./scripts/setup-test-couchbase.sh

# Run all tests
CB_BUCKET=testbucket pytest tests/ --ignore=tests/testapp --ignore=tests/wagtailapp

# Coverage
CB_BUCKET=testbucket coverage run -m pytest tests/ && coverage report --include="src/*"

See Testing Guide for full details.

Example Project

The example/ directory contains a complete Django + Wagtail + DRF project (BrewSync) deployed at the live demo. It includes:

• Wagtail CMS with HomePage, BlogIndexPage, BlogPage
• Beer catalog with Brewery/Beer models
• DRF REST API (/api/beers/, /api/breweries/)
• Dark brewery theme with search and filtering
• Deployed on Railway with Couchbase Capella

Development

git clone https://github.com/EdikSimonian/django-couchbase-orm.git
cd django-couchbase-orm
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

Apache 2.0