Metadata-Version: 2.4
Name: djraphdb
Version: 0.1.0
Summary: Graph queries that sit alongside your Django ORM
Project-URL: Homepage, https://github.com/josephbrockw/djraphdb
Project-URL: Documentation, https://djraphdb.readthedocs.io
Project-URL: Repository, https://github.com/josephbrockw/djraphdb
Project-URL: Changelog, https://github.com/josephbrockw/djraphdb/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/josephbrockw/djraphdb/issues
Author: Joe Wilkinson
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: django>=4.2.17
Requires-Dist: neo4j>=5.0
Provides-Extra: dev
Requires-Dist: django-stubs>=4.2; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-django>=4.5; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Requires-Dist: testcontainers[neo4j]>=3.7; extra == 'dev'
Description-Content-Type: text/markdown

# djraphdb

[![PyPI version](https://img.shields.io/pypi/v/djraphdb.svg)](https://pypi.org/project/djraphdb/)
[![Python versions](https://img.shields.io/pypi/pyversions/djraphdb.svg)](https://pypi.org/project/djraphdb/)
[![Django versions](https://img.shields.io/pypi/djversions/djraphdb.svg)](https://pypi.org/project/djraphdb/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![CI](https://github.com/josephbrockw/djraphdb/actions/workflows/ci.yml/badge.svg)

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:

```python
# 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:

```python
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:

```python
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](https://djraphdb.readthedocs.io)

- [Getting Started](docs/getting-started.md) — full tutorial
- [Configuration](docs/configuration.md) — all `DJRAPHDB` settings
- [GraphService](docs/services.md) — primary query interface
- [GraphNode](docs/graph-nodes.md) — declarative node models
- [Query Builder](docs/query-builder.md) — CypherQuery API
- [Testing](docs/testing.md) — GraphTestCase, fixtures, MockGraphService

See [CHANGELOG.md](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](docs/contributing.md) for the full development guide.
