https://github.com/ediksimonian/django-couchbase-orm
Django database backend for Couchbase — full ORM support, migrations, Wagtail compatible
https://github.com/ediksimonian/django-couchbase-orm
couchbase database-backend django django-orm nosql orm python wagtail
Last synced: 3 days ago
JSON representation
Django database backend for Couchbase — full ORM support, migrations, Wagtail compatible
- Host: GitHub
- URL: https://github.com/ediksimonian/django-couchbase-orm
- Owner: EdikSimonian
- License: apache-2.0
- Created: 2026-04-01T23:49:05.000Z (15 days ago)
- Default Branch: main
- Last Pushed: 2026-04-10T03:41:01.000Z (7 days ago)
- Last Synced: 2026-04-10T10:23:29.073Z (7 days ago)
- Topics: couchbase, database-backend, django, django-orm, nosql, orm, python, wagtail
- Language: Python
- Homepage: https://django-couchbase-orm-production.up.railway.app
- Size: 3.73 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# django-couchbase-orm
[](https://github.com/EdikSimonian/django-couchbase-orm/actions/workflows/ci.yml)
[](https://github.com/EdikSimonian/django-couchbase-orm/actions/workflows/ci.yml)
[](https://pypi.org/project/django-couchbase-orm/)
[](https://pypi.org/project/django-couchbase-orm/)
[](https://github.com/EdikSimonian/django-couchbase-orm/blob/main/LICENSE)
> **Live Demo:** [django-couchbase-orm-production.up.railway.app](https://django-couchbase-orm-production.up.railway.app)
> A full Django + Wagtail CMS + DRF beer catalog running on Couchbase Capella. Browse [beers](https://django-couchbase-orm-production.up.railway.app/beers/), read the [blog](https://django-couchbase-orm-production.up.railway.app/blog/), or explore the [Wagtail admin](https://django-couchbase-orm-production.up.railway.app/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](https://github.com/EdikSimonian/django-couchbase-orm/blob/main/docs/database-backend.md) | [Document API](https://github.com/EdikSimonian/django-couchbase-orm/blob/main/docs/document-api.md) | [Wagtail](https://github.com/EdikSimonian/django-couchbase-orm/blob/main/docs/wagtail.md) | [Hybrid Architecture](https://github.com/EdikSimonian/django-couchbase-orm/blob/main/docs/hybrid.md) | [Testing](https://github.com/EdikSimonian/django-couchbase-orm/blob/main/docs/testing.md)
## Two Ways to Use It
### 1. Django Database Backend
Standard Django models work transparently with Couchbase. Admin, forms, DRF, Wagtail - everything just works.
```python
# 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.
```python
# 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
```bash
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](https://django-couchbase-orm-production.up.railway.app/admin/) for a working example.
```python
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:
```python
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
```python
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)
```python
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
```python
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 |
```bash
# 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](https://github.com/EdikSimonian/django-couchbase-orm/blob/main/docs/testing.md) for full details.
## Example Project
The [`example/`](https://github.com/EdikSimonian/django-couchbase-orm/tree/main/example) directory contains a complete Django + Wagtail + DRF project (BrewSync) deployed at the [live demo](https://django-couchbase-orm-production.up.railway.app). 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
```bash
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