djraphdb 0.1.0

Graph queries that sit alongside your Django ORM

djraphdb

Graph queries that sit alongside your Django ORM.

djraphdb is a clean, idiomatic service layer for using Neo4j alongside Django's relational ORM. It is not a database backend — it is a parallel query interface that respects Django conventions while embracing Cypher and graph-native patterns. You keep your existing Django models and migrations; djraphdb gives your Neo4j queries the same first-class treatment.

Features

• Multi-database connections — manage multiple named Neo4j connections with connection pooling and retry
• GraphService — clean read/write/transaction API with typed result mapping (dataclasses, NamedTuples, Pydantic)
• GraphNode — declarative ORM-style node models with field descriptors and CRUD operations
• CypherQuery builder — fluent query builder with first-class .raw() support for complex Cypher
• Decorators — @graph_read, @graph_write, @graph_transaction for declarative graph access in views
• Middleware — per-request session and transaction scoping
• Health checks — connectivity probes, Django system checks, and an optional health endpoint
• Signals — Django signals for query execution, slow queries, and connection lifecycle
• Management commands — graph_info, graph_clear, graph_seed
• Testing utilities — GraphTestCase, MockGraphService, GraphFixtureLoader for easy testing
• Django integration — INSTALLED_APPS, app lifecycle hooks, settings system

Why djraphdb?

	djraphdb	neomodel	Raw neo4j driver
Django integration	✓ Full	Partial	None
Multi-database	✓	✗	Manual
Raw Cypher	✓ First-class	Limited	✓
Type-safe results	✓	Partial	✗
Testing utilities	✓	✗	✗
Django signals	✓	✗	✗
Health checks	✓	✗	✗
ORM replacement	✗ (by design)	Partial	✗

Why not a full Django database backend?

Django's ORM assumes relational algebra: tables, foreign keys, GROUP BY. Mapping these concepts to Neo4j's graph model would be a leaky abstraction requiring months of work. djraphdb takes a pragmatic approach: a clean service layer that sits alongside your existing Django ORM, giving graph queries a first-class API without fighting the relational model.

Quickstart

pip install djraphdb

Add "djraphdb" to your INSTALLED_APPS and configure the connection:

# settings.py
import os

INSTALLED_APPS = [
    ...
    "djraphdb",
]

DJRAPHDB = {
    "URI": os.environ["NEO4J_URI"],
    "AUTH": (os.environ["NEO4J_USER"], os.environ["NEO4J_PASSWORD"]),
    "DATABASE": "neo4j",
}

Run your first query:

from djraphdb.service import GraphService

service = GraphService()
people = service.read("MATCH (p:Person) RETURN p.name AS name, p.age AS age")

Declare a node model:

from djraphdb.nodes import GraphNode
from djraphdb.fields import StringProperty, IntegerProperty, UUIDProperty

class Person(GraphNode):
    uid = UUIDProperty()
    name = StringProperty(required=True)
    age = IntegerProperty()

alice = Person(name="Alice", age=30)
alice.save()
alice = Person.nodes.get(name="Alice")

Documentation

Full documentation: djraphdb.readthedocs.io

• Getting Started — full tutorial
• Configuration — all DJRAPHDB settings
• GraphService — primary query interface
• GraphNode — declarative node models
• Query Builder — CypherQuery API
• Testing — GraphTestCase, fixtures, MockGraphService

See CHANGELOG.md for the full version history.

Development

Clone the repo and install dev dependencies:

git clone https://github.com/josephbrockw/djraphdb.git
cd djraphdb
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Command	What it does
make test	Run unit tests (no Docker required)
make test-integration	Run integration tests (requires Docker)
make test-all	Run all tests
make lint	Run ruff check and mypy

See docs/contributing.md for the full development guide.