django-pyturso

django-pyturso is a Django database backend for the embedded Turso database engine exposed by pyturso. It will let a Django project use its ordinary ORM, migrations, forms, admin, and transaction APIs against a local Turso database file.

This repository is deliberately scoped to embedded, local Turso. It does not provide Turso Cloud access, libSQL-over-HTTP support, replication, sync, or a project-specific compatibility layer.

Status

The pre-release backend is implemented and covered by focused tests for ORM, migrations, transactions, Django integration, driver behavior, and package installation. Publication remains a separate, explicitly authorized action.

The v1 contract intentionally excludes writing non-NULL Django BinaryField values because the stable pyturso 0.7 line does not expose the required PEP 249 Binary() constructor. The backend deliberately does not patch or wrap the real turso module. See the compatibility document before evaluating the package.

Quickstart

In your Django project's PDM environment, install the package:

pdm add "django-pyturso>=0.3.0"

Configure a Django database with no external service:

DATABASES = {
    "default": {
        "ENGINE": "django_pyturso",
        "NAME": BASE_DIR / "db.sqlite3",
    }
}

The package requires CPython 3.14 or later, Django 6.1.2 or later, and embedded local Turso through pyturso. Cloud transports, remote sync, SQLite fallbacks, compatibility shims, and other experimental engine features are excluded. MVCC concurrent transactions are available through explicit configuration for one process per database.

Repository checks

To work on this repository, install Perfect Doc and put it on PATH before running the checks.

pdm install --group dev
pdm run check

Navigation

• Architecture
• Backend contract
• Configuration
• Compatibility status
• Test runner
• Testing
• Security and supply chain
• Post-v1 roadmap
• Releasing
• Documentation index
• Agent operating guide