Initial commit

Author: antoineleclair

.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# mypy
+.mypy_cache/
+
+# Distribution
+dist/
+build/

DEVELOPMENT.md

@@ -0,0 +1,90 @@
+# Development Guide
+
+## Prerequisites
+
+- Python 3.13+
+- [uv](https://github.com/astral-sh/uv) - Fast Python package manager
+- Docker (for integration tests)
+
+## Setup
+
+Start by also cloning [dqlite-wire](https://github.com/letsdiscodev/python-dqlite-wire),
+[dqlite-client](https://github.com/letsdiscodev/python-dqlite-client)
+and [dqlite-dbapi](https://github.com/letsdiscodev/python-dqlite-dbapi).
+
+```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create virtual environment and install dependencies
+uv venv --python 3.13
+uv pip install -e "../python-dqlite-wire" -e "../python-dqlite-client" -e "../python-dqlite-dbapi" -e ".[dev]"
+```
+
+## Development Tools
+
+| Tool | Purpose | Command |
+|------|---------|---------|
+| **pytest** | Testing framework | `pytest` |
+| **ruff** | Linter (replaces flake8, isort, etc.) | `ruff check` |
+| **ruff format** | Code formatter (replaces black) | `ruff format` |
+| **mypy** | Static type checker | `mypy src` |
+
+## Running Tests
+
+```bash
+# Run unit tests only
+.venv/bin/pytest tests/ --ignore=tests/integration
+
+# Run all tests (requires Docker cluster)
+cd ../dqlite-test-cluster && docker compose up -d
+.venv/bin/pytest tests/
+```
+
+## Linting & Formatting
+
+```bash
+# Lint
+.venv/bin/ruff check src tests
+
+# Auto-fix lint issues
+.venv/bin/ruff check --fix src tests
+
+# Format
+.venv/bin/ruff format src tests
+```
+
+## Type Checking
+
+```bash
+.venv/bin/mypy src
+```
+
+## Pre-commit Workflow
+
+```bash
+.venv/bin/ruff format src tests
+.venv/bin/ruff check --fix src tests
+.venv/bin/mypy src
+.venv/bin/pytest tests/ --ignore=tests/integration
+```
+
+## SQLAlchemy URL Format
+
+```
+# Sync
+dqlite://host:port/database
+
+# Async
+dqlite+aio://host:port/database
+```
+
+## Dialect Registration
+
+The dialects are registered via entry points in `pyproject.toml`:
+
+```toml
+[project.entry-points."sqlalchemy.dialects"]
+dqlite = "sqlalchemydqlite:DqliteDialect"
+"dqlite.aio" = "sqlalchemydqlite.aio:DqliteDialect_aio"
+```

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antoine Leclair and Greg Sadetsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,44 @@
+# sqlalchemy-dqlite
+
+SQLAlchemy 2.0 dialect for [dqlite](https://dqlite.io/).
+
+## Installation
+
+```bash
+pip install sqlalchemy-dqlite
+```
+
+## Usage
+
+```python
+from sqlalchemy import create_engine, text
+
+# Sync
+engine = create_engine("dqlite://localhost:9001/mydb")
+with engine.connect() as conn:
+    result = conn.execute(text("SELECT 1"))
+    print(result.fetchone())
+
+# Async
+from sqlalchemy.ext.asyncio import create_async_engine
+
+async_engine = create_async_engine("dqlite+aio://localhost:9001/mydb")
+async with async_engine.connect() as conn:
+    result = await conn.execute(text("SELECT 1"))
+    print(result.fetchone())
+```
+
+## URL Format
+
+```
+dqlite://host:port/database
+dqlite+aio://host:port/database
+```
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for setup and contribution guidelines.
+
+## License
+
+MIT

pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sqlalchemy-dqlite"
+version = "0.1.0"
+description = "SQLAlchemy 2.0 dialect for dqlite distributed SQLite"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+authors = [{ name = "Antoine Leclair", email = "antoineleclair@gmail.com" }]
+keywords = ["dqlite", "sqlite", "distributed", "database", "sqlalchemy", "orm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Database :: Database Engines/Servers",
+    "Topic :: Database :: Front-Ends",
+    "Typing :: Typed",
+]
+dependencies = ["dqlite-dbapi>=0.1.0", "sqlalchemy>=2.0"]
+
+[project.urls]
+Homepage = "https://github.com/antoineleclair/sqlalchemy-dqlite"
+Repository = "https://github.com/antoineleclair/sqlalchemy-dqlite"
+Issues = "https://github.com/antoineleclair/sqlalchemy-dqlite/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-cov>=4.0", "pytest-asyncio>=0.23", "mypy>=1.0", "ruff>=0.4"]
+
+[project.entry-points."sqlalchemy.dialects"]
+dqlite = "sqlalchemydqlite:DqliteDialect"
+"dqlite.aio" = "sqlalchemydqlite.aio:DqliteDialect_aio"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sqlalchemydqlite"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.mypy]
+strict = true
+python_version = "3.13"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["sqlalchemydqlite", "dqlitedbapi", "dqliteclient", "dqlitewire"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true

src/sqlalchemydqlite/__init__.py

@@ -0,0 +1,7 @@
+"""SQLAlchemy 2.0 dialect for dqlite."""
+
+from sqlalchemydqlite.base import DqliteDialect
+
+__all__ = ["DqliteDialect"]
+
+__version__ = "0.1.0"

src/sqlalchemydqlite/aio.py

@@ -0,0 +1,57 @@
+"""Async dqlite dialect for SQLAlchemy."""
+
+from typing import Any
+
+from sqlalchemy import pool
+from sqlalchemy.dialects.sqlite.base import SQLiteDialect
+from sqlalchemy.engine import URL
+from sqlalchemy.pool import AsyncAdaptedQueuePool
+
+
+class DqliteDialect_aio(SQLiteDialect):  # noqa: N801
+    """Async SQLAlchemy dialect for dqlite.
+
+    Use with SQLAlchemy's async engine:
+        create_async_engine("dqlite+aio://host:port/database")
+    """
+
+    name = "dqlite"
+    driver = "dqlitedbapi_aio"
+    is_async = True
+
+    # dqlite uses qmark parameter style
+    paramstyle = "qmark"
+
+    @classmethod
+    def get_pool_class(cls, url: URL) -> type[pool.Pool]:
+        return AsyncAdaptedQueuePool
+
+    @classmethod
+    def import_dbapi(cls) -> Any:
+        from dqlitedbapi import aio
+
+        return aio
+
+    def create_connect_args(self, url: URL) -> tuple[list[Any], dict[str, Any]]:
+        """Create connection arguments from URL.
+
+        URL format: dqlite+aio://host:port/database
+        """
+        host = url.host or "localhost"
+        port = url.port or 9001
+        database = url.database or "default"
+
+        address = f"{host}:{port}"
+
+        return [], {
+            "address": address,
+            "database": database,
+        }
+
+    def get_driver_connection(self, connection: Any) -> Any:
+        """Return the driver-level connection."""
+        return connection
+
+
+# Register the dialect
+dialect = DqliteDialect_aio