{"id":47736674,"url":"https://github.com/ediksimonian/django-couchbase-orm","last_synced_at":"2026-04-14T07:06:13.518Z","repository":{"id":348623277,"uuid":"1198964187","full_name":"EdikSimonian/django-couchbase-orm","owner":"EdikSimonian","description":"Django database backend for Couchbase — full ORM support, migrations, Wagtail compatible","archived":false,"fork":false,"pushed_at":"2026-04-10T03:41:01.000Z","size":3914,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T10:23:29.073Z","etag":null,"topics":["couchbase","database-backend","django","django-orm","nosql","orm","python","wagtail"],"latest_commit_sha":null,"homepage":"https://django-couchbase-orm-production.up.railway.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EdikSimonian.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T23:49:05.000Z","updated_at":"2026-04-10T03:41:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/EdikSimonian/django-couchbase-orm","commit_stats":null,"previous_names":["ediksimonian/django-cb"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/EdikSimonian/django-couchbase-orm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdikSimonian%2Fdjango-couchbase-orm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdikSimonian%2Fdjango-couchbase-orm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdikSimonian%2Fdjango-couchbase-orm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdikSimonian%2Fdjango-couchbase-orm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EdikSimonian","download_url":"https://codeload.github.com/EdikSimonian/django-couchbase-orm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EdikSimonian%2Fdjango-couchbase-orm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31785685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T02:24:21.117Z","status":"ssl_error","status_checked_at":"2026-04-14T02:24:20.627Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["couchbase","database-backend","django","django-orm","nosql","orm","python","wagtail"],"created_at":"2026-04-02T22:46:20.486Z","updated_at":"2026-04-14T07:06:13.513Z","avatar_url":"https://github.com/EdikSimonian.png","language":"Python","readme":"# django-couchbase-orm\n\n[![CI](https://github.com/EdikSimonian/django-couchbase-orm/actions/workflows/ci.yml/badge.svg)](https://github.com/EdikSimonian/django-couchbase-orm/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/EdikSimonian/81d4c53b76d523240e3213a0a9f4b3b7/raw/coverage.json)](https://github.com/EdikSimonian/django-couchbase-orm/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/django-couchbase-orm?cacheSeconds=60)](https://pypi.org/project/django-couchbase-orm/)\n[![Python](https://img.shields.io/pypi/pyversions/django-couchbase-orm)](https://pypi.org/project/django-couchbase-orm/)\n[![License](https://img.shields.io/github/license/EdikSimonian/django-couchbase-orm)](https://github.com/EdikSimonian/django-couchbase-orm/blob/main/LICENSE)\n\n\u003e **Live Demo:** [django-couchbase-orm-production.up.railway.app](https://django-couchbase-orm-production.up.railway.app)\n\u003e 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/).\n\nUse Couchbase as your Django database. Drop-in backend for `django.db.models.Model` plus a standalone Document API for Couchbase-native patterns.\n\n**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)\n\n## Two Ways to Use It\n\n### 1. Django Database Backend\n\nStandard Django models work transparently with Couchbase. Admin, forms, DRF, Wagtail - everything just works.\n\n```python\n# settings.py\nDATABASES = {\n    \"default\": {\n        \"ENGINE\": \"django_couchbase_orm.db.backends.couchbase\",\n        \"NAME\": \"mybucket\",\n        \"USER\": \"Administrator\",\n        \"PASSWORD\": \"password\",\n        \"HOST\": \"couchbase://localhost\",\n    }\n}\nDEFAULT_AUTO_FIELD = \"django_couchbase_orm.db.backends.couchbase.fields.CouchbaseAutoField\"\n\n# models.py - standard Django models, no changes needed\nfrom django.db import models\n\nclass Article(models.Model):\n    title = models.CharField(max_length=200)\n    body = models.TextField()\n    author = models.ForeignKey(\"auth.User\", on_delete=models.CASCADE)\n    published = models.BooleanField(default=False)\n    created_at = models.DateTimeField(auto_now_add=True)\n```\n\nEverything works: `makemigrations`, `migrate`, `createsuperuser`, Django admin, ModelForms, DRF serializers, Wagtail CMS.\n\n### 2. Document API\n\nFor Couchbase-native patterns - subdoc operations, KV fast-path, embedded documents.\n\n```python\n# settings.py\nCOUCHBASE = {\n    \"default\": {\n        \"CONNECTION_STRING\": \"couchbase://localhost\",\n        \"USERNAME\": \"Administrator\",\n        \"PASSWORD\": \"password\",\n        \"BUCKET\": \"mybucket\",\n    }\n}\n\n# documents.py\nfrom django_couchbase_orm import Document, StringField, FloatField\n\nclass Beer(Document):\n    name = StringField(required=True)\n    abv = FloatField()\n    style = StringField()\n\n    class Meta:\n        collection_name = \"beers\"\n```\n\nBoth APIs can coexist in the same project. They share the same Couchbase connection.\n\n## Install\n\n```bash\npip install django-couchbase-orm\n```\n\nRequires Python 3.10+, Django 4.2+, Couchbase SDK 4.1+.\n\n## Django Backend Features\n\nEverything you'd expect from a Django database backend:\n\n- `manage.py migrate` creates Couchbase collections\n- `manage.py createsuperuser` works\n- `ForeignKey`, `ManyToManyField` with JOINs via N1QL\n- `select_related()`, `prefetch_related()`\n- `annotate()`, `aggregate()` with `Count`, `Sum`, `Avg`, `Min`, `Max`\n- `Q()` objects, `F()` expressions\n- All lookups: `exact`, `icontains`, `startswith`, `in`, `isnull`, `regex`, etc.\n- `values()`, `values_list()`, `distinct()`, `only()`, `defer()`\n- `bulk_create()`, `bulk_update()`\n- Django admin: list, add, edit, delete, search\n- Django auth: users, groups, permissions\n- Django sessions (DB backend)\n- ContentTypes framework\n- ModelForm, DRF ModelSerializer\n- Wagtail CMS (page tree, publishing, admin)\n\n### SQL-to-N1QL Translation\n\nThe backend transparently handles the differences between SQL and N1QL:\n\n| SQL | N1QL (handled automatically) |\n|-----|-----|\n| `INSERT INTO` | `UPSERT INTO` (idempotent) |\n| `SUBSTRING(s, pos)` | `SUBSTR(s, pos-1)` (0-indexed) |\n| `IS NULL` | `IS NOT VALUED` (handles MISSING) |\n| `CAST(x AS INT)` | `TONUMBER(x)` |\n| `AUTO_INCREMENT` | Atomic counter (`binary.increment`) |\n| Sequential IDs | `CouchbaseAutoField` (integer PKs) |\n\n### Wagtail Support\n\nWagtail CMS works fully with the Couchbase backend. See the [live demo](https://django-couchbase-orm-production.up.railway.app/admin/) for a working example.\n\n```python\nINSTALLED_APPS = [\n    ...\n    \"wagtail\", \"wagtail.admin\", \"wagtail.images\",\n    \"wagtail.documents\", \"wagtail.search\",\n]\n\n# manage.py migrate - creates all Wagtail collections\n# manage.py createsuperuser - create admin user\n# Page tree, publishing, editing, images, documents all work\n```\n\n### Couchbase Capella (Cloud)\n\nWorks with Couchbase Capella out of the box:\n\n```python\nDATABASES = {\n    \"default\": {\n        \"ENGINE\": \"django_couchbase_orm.db.backends.couchbase\",\n        \"NAME\": \"my-bucket\",\n        \"USER\": \"dbuser\",\n        \"PASSWORD\": \"dbpassword\",\n        \"HOST\": \"couchbases://cb.xxxxx.cloud.couchbase.com\",\n    }\n}\n```\n\n## Document API Features\n\nFor when you need Couchbase-native performance:\n\n- KV-optimized `get(pk=...)` (~1ms vs ~50ms for N1QL)\n- Sub-document operations (partial reads/writes)\n- Embedded documents\n- Django-style QuerySet with N1QL\n- Signals: `pre_save`, `post_save`, `pre_delete`, `post_delete`\n- Async support (`asave`, `adelete`, `alist`, `acount`)\n- Custom migrations framework (`cb_makemigrations`, `cb_migrate`)\n\n### Quick Example\n\n```python\nfrom django_couchbase_orm import Document, StringField, FloatField, Q\n\n# CRUD\nbeer = Beer(name=\"IPA\", abv=6.5, style=\"IPA\")\nbeer.save()\nbeer = Beer.objects.get(pk=\"beer-id\")   # fast KV lookup\nbeer.abv = 7.0\nbeer.save()\nbeer.delete()\n\n# Queries\nBeer.objects.filter(style=\"IPA\", abv__gte=6.0).order_by(\"-abv\")[:20]\nBeer.objects.filter(Q(style=\"IPA\") | Q(style=\"Pale Ale\")).count()\nBeer.objects.aggregate(avg_abv=Avg(\"abv\"), total=Count(\"*\"))\n\n# Sub-document operations\nbeer.subdoc.upsert(\"ratings.average\", 4.5)\nbeer.subdoc.increment(\"view_count\", 1)\nbeer.subdoc.array_append(\"tags\", \"hoppy\")\n```\n\n## Configuration\n\n### Database Backend (recommended)\n\n```python\nDATABASES = {\n    \"default\": {\n        \"ENGINE\": \"django_couchbase_orm.db.backends.couchbase\",\n        \"NAME\": \"mybucket\",          # Couchbase bucket\n        \"USER\": \"Administrator\",\n        \"PASSWORD\": \"password\",\n        \"HOST\": \"couchbase://localhost\",\n        \"OPTIONS\": {\n            \"SCOPE\": \"_default\",     # optional\n        },\n    }\n}\nDEFAULT_AUTO_FIELD = \"django_couchbase_orm.db.backends.couchbase.fields.CouchbaseAutoField\"\n```\n\n### Document API\n\n```python\nCOUCHBASE = {\n    \"default\": {\n        \"CONNECTION_STRING\": \"couchbase://localhost\",\n        \"USERNAME\": \"Administrator\",\n        \"PASSWORD\": \"password\",\n        \"BUCKET\": \"mybucket\",\n        \"SCOPE\": \"_default\",\n    }\n}\n```\n\nIf you use the database backend, the Document API auto-derives its config from `DATABASES` - no need to set both.\n\n## Fields (Document API)\n\n| Field | Type | Options |\n|-------|------|---------|\n| `StringField` | `str` | `min_length`, `max_length`, `regex` |\n| `IntegerField` | `int` | `min_value`, `max_value` |\n| `FloatField` | `float` | `min_value`, `max_value` |\n| `BooleanField` | `bool` | |\n| `UUIDField` | `uuid.UUID` | `auto=True` |\n| `DateTimeField` | `datetime` | `auto_now`, `auto_now_add` |\n| `DateField` | `date` | `auto_now`, `auto_now_add` |\n| `ListField` | `list` | `field` for typed elements |\n| `DictField` | `dict` | |\n| `EmbeddedDocumentField` | nested | |\n| `ReferenceField` | FK-like | |\n\n## Known Limitations\n\n- **Transactions**: Couchbase ACID transactions require multi-node clusters. `atomic()` runs as a no-op on single-node setups.\n- **Window functions**: N1QL doesn't support `OVER()` clauses.\n- **Page moves**: Wagtail page tree moves use raw SQL with reserved words. Use delete + recreate as a workaround.\n- **Correlated subqueries with GROUP BY**: Some complex query patterns return empty results gracefully instead of crashing.\n- **Multi-table inheritance**: Works but may have performance implications with N1QL JOINs.\n\n## Tests\n\n**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.\n\n| Suite | Tests | What's Covered |\n|-------|------:|----------------|\n| Document API | 784 | Fields, QuerySet, Manager, Document CRUD, signals, pagination, migrations, auth, sessions |\n| Django Backend | 156 | Connection, cursor, CRUD, JOINs, M2M, admin, forms, migrations, subqueries, bulk ops |\n| Edge Cases | 128 | Boundary conditions, type coercion, null handling, return types, regression tests |\n| Coverage Gaps | 114 | N1QL builders, paginator, signals, document options, aggregate+filter combos |\n| Wagtail CRUD | 28 | Page create, publish, edit, unpublish, delete, revisions, admin forms |\n| Security | 27 | Injection prevention, password isolation, backtick escaping |\n| Concurrency | 18 | Multi-threaded CRUD, connection pool thread safety, race conditions, auto-increment contention |\n\n```bash\n# Start Couchbase\ndocker compose -f docker-compose.test.yml up -d\n./scripts/setup-test-couchbase.sh\n\n# Run all tests\nCB_BUCKET=testbucket pytest tests/ --ignore=tests/testapp --ignore=tests/wagtailapp\n\n# Coverage\nCB_BUCKET=testbucket coverage run -m pytest tests/ \u0026\u0026 coverage report --include=\"src/*\"\n```\n\nSee [Testing Guide](https://github.com/EdikSimonian/django-couchbase-orm/blob/main/docs/testing.md) for full details.\n\n## Example Project\n\nThe [`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:\n\n- Wagtail CMS with HomePage, BlogIndexPage, BlogPage\n- Beer catalog with Brewery/Beer models\n- DRF REST API (`/api/beers/`, `/api/breweries/`)\n- Dark brewery theme with search and filtering\n- Deployed on Railway with Couchbase Capella\n\n## Development\n\n```bash\ngit clone https://github.com/EdikSimonian/django-couchbase-orm.git\ncd django-couchbase-orm\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e \".[dev]\"\npytest\n```\n\n## License\n\nApache 2.0\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fediksimonian%2Fdjango-couchbase-orm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fediksimonian%2Fdjango-couchbase-orm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fediksimonian%2Fdjango-couchbase-orm/lists"}