sqlalchemy-dqlite 0.1.1__tar.gz

sqlalchemy_dqlite-0.1.1/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+on: push
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        persist-credentials: false
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.x"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v5
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+    name: >-
+      Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sqlalchemy-dqlite
+    permissions:
+      id-token: write
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v6
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

sqlalchemy_dqlite-0.1.1/.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/

sqlalchemy_dqlite-0.1.1/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"
+```

sqlalchemy_dqlite-0.1.1/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.

sqlalchemy_dqlite-0.1.1/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: sqlalchemy-dqlite
+Version: 0.1.1
+Summary: SQLAlchemy 2.0 dialect for dqlite distributed SQLite
+Project-URL: Homepage, https://github.com/antoineleclair/sqlalchemy-dqlite
+Project-URL: Repository, https://github.com/antoineleclair/sqlalchemy-dqlite
+Project-URL: Issues, https://github.com/antoineleclair/sqlalchemy-dqlite/issues
+Author-email: Antoine Leclair <antoineleclair@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: database,distributed,dqlite,orm,sqlalchemy,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: dqlite-dbapi>=0.1.0
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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

sqlalchemy_dqlite-0.1.1/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

sqlalchemy_dqlite-0.1.1/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sqlalchemy-dqlite"
+version = "0.1.1"
+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

sqlalchemy_dqlite-0.1.1/src/sqlalchemydqlite/__init__.py

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

sqlalchemy_dqlite-0.1.1/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

sqlalchemy_dqlite-0.1.1/src/sqlalchemydqlite/base.py

@@ -0,0 +1,122 @@
+"""Base 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.engine.interfaces import DBAPIConnection, IsolationLevel
+
+
+class DqliteDialect(SQLiteDialect):
+    """SQLAlchemy dialect for dqlite.
+
+    Inherits from SQLite dialect since dqlite is compatible with SQLite.
+    """
+
+    name = "dqlite"
+    driver = "dqlitedbapi"
+
+    # dqlite uses qmark parameter style
+    paramstyle = "qmark"
+
+    # Enable SQLAlchemy statement caching
+    supports_statement_cache = True
+
+    # Default to NullPool since dqlite handles connection pooling internally
+    @classmethod
+    def get_pool_class(cls, url: URL) -> type[pool.Pool]:
+        return pool.NullPool
+
+    @classmethod
+    def import_dbapi(cls) -> Any:
+        import dqlitedbapi
+
+        return dqlitedbapi
+
+    def create_connect_args(self, url: URL) -> tuple[list[Any], dict[str, Any]]:
+        """Create connection arguments from URL.
+
+        URL format: dqlite://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_isolation_level(self, dbapi_connection: DBAPIConnection) -> IsolationLevel:
+        """Return the isolation level.
+
+        dqlite doesn't support PRAGMA read_uncommitted, so we return
+        SERIALIZABLE as the default isolation level.
+        """
+        return "SERIALIZABLE"
+
+    def set_isolation_level(self, dbapi_connection: DBAPIConnection, level: str | None) -> None:
+        """Set isolation level.
+
+        dqlite doesn't support changing isolation levels via PRAGMA,
+        so this is a no-op. dqlite uses SERIALIZABLE isolation by default.
+        """
+        pass
+
+    def do_rollback(self, dbapi_connection: DBAPIConnection) -> None:
+        """Rollback the current transaction.
+
+        dqlite throws an error if we try to rollback when no transaction
+        is active, so we catch and ignore that specific error.
+        """
+        try:
+            dbapi_connection.rollback()
+        except Exception as e:
+            # Ignore "no transaction is active" errors
+            if "no transaction is active" not in str(e):
+                raise
+
+    def do_commit(self, dbapi_connection: DBAPIConnection) -> None:
+        """Commit the current transaction.
+
+        dqlite throws an error if we try to commit when no transaction
+        is active, so we catch and ignore that specific error.
+        """
+        try:
+            dbapi_connection.commit()
+        except Exception as e:
+            # Ignore "no transaction is active" errors
+            if "no transaction is active" not in str(e):
+                raise
+
+    def do_ping(self, dbapi_connection: Any) -> bool:
+        """Check if the connection is still alive."""
+        try:
+            cursor = dbapi_connection.cursor()
+            cursor.execute("SELECT 1")
+            cursor.close()
+            return True
+        except Exception:
+            return False
+
+    def _get_server_version_info(self, connection: Any) -> tuple[int, ...]:
+        """Return the server version as a tuple.
+
+        dqlite uses SQLite internally, so we return SQLite version.
+        """
+        cursor = connection.connection.dbapi_connection.cursor()
+        cursor.execute("SELECT sqlite_version()")
+        row = cursor.fetchone()
+        cursor.close()
+
+        if row:
+            version_str = row[0]
+            return tuple(int(x) for x in version_str.split("."))
+        return (3, 0, 0)
+
+
+# Register the dialect
+dialect = DqliteDialect

sqlalchemy_dqlite-0.1.1/src/sqlalchemydqlite/requirements.py

@@ -0,0 +1,45 @@
+"""SQLAlchemy test suite requirements for dqlite dialect."""
+
+from sqlalchemy.testing.requirements import SuiteRequirements
+
+
+class Requirements(SuiteRequirements):
+    """Test suite requirements for dqlite dialect.
+
+    Override requirements that dqlite doesn't support.
+    """
+
+    @property
+    def datetime_literals(self) -> bool:
+        """dqlite/SQLite doesn't have native datetime literals."""
+        return False
+
+    @property
+    def time_microseconds(self) -> bool:
+        """SQLite stores time as text without microseconds."""
+        return False
+
+    @property
+    def datetime_historic(self) -> bool:
+        """SQLite date range limitation."""
+        return False
+
+    @property
+    def unicode_ddl(self) -> bool:
+        """SQLite supports unicode in DDL."""
+        return True
+
+    @property
+    def savepoints(self) -> bool:
+        """dqlite supports savepoints."""
+        return True
+
+    @property
+    def two_phase_transactions(self) -> bool:
+        """dqlite doesn't support two-phase transactions."""
+        return False
+
+    @property
+    def temp_table_reflection(self) -> bool:
+        """SQLite supports temp table reflection."""
+        return True

sqlalchemy_dqlite-0.1.1/tests/conftest.py

@@ -0,0 +1,15 @@
+"""Pytest configuration for sqlalchemy-dqlite tests."""
+
+import os
+
+import pytest
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    config.addinivalue_line("markers", "integration: marks tests as requiring dqlite cluster")
+
+
+@pytest.fixture
+def cluster_address() -> str:
+    """Get the test cluster address."""
+    return os.environ.get("DQLITE_TEST_CLUSTER", "localhost:9001")

sqlalchemy_dqlite-0.1.1/tests/integration/conftest.py

@@ -0,0 +1,17 @@
+"""Integration test fixtures for sqlalchemy-dqlite."""
+
+import pytest
+
+
+@pytest.fixture
+def engine_url(cluster_address: str) -> str:
+    """Get SQLAlchemy engine URL."""
+    host, port = cluster_address.split(":")
+    return f"dqlite://{host}:{port}/test"
+
+
+@pytest.fixture
+def async_engine_url(cluster_address: str) -> str:
+    """Get async SQLAlchemy engine URL."""
+    host, port = cluster_address.split(":")
+    return f"dqlite+aio://{host}:{port}/test"

sqlalchemy_dqlite-0.1.1/tests/integration/test_async_context.py

@@ -0,0 +1,28 @@
+"""Integration tests for sync engine used inside an async context."""
+
+import asyncio
+
+import pytest
+from sqlalchemy import create_engine, text
+
+
+@pytest.mark.integration
+class TestSyncEngineInAsyncContext:
+    def test_sync_engine_inside_running_loop(self, engine_url: str) -> None:
+        """Sync engine must work when called from inside a running event loop.
+
+        This simulates the scenario where a sync SQLAlchemy engine is used
+        during app startup inside an async server like uvicorn.
+        """
+
+        async def _run_inside_loop() -> str:
+            engine = create_engine(engine_url)
+            with engine.connect() as conn:
+                result = conn.execute(text("SELECT 'ok'"))
+                row = result.fetchone()
+            engine.dispose()
+            assert row is not None
+            return str(row[0])
+
+        result = asyncio.run(_run_inside_loop())
+        assert result == "ok"

sqlalchemy_dqlite-0.1.1/tests/integration/test_orm_operations.py

@@ -0,0 +1,278 @@
+"""Integration tests for ORM operations."""
+
+import datetime
+
+import pytest
+from sqlalchemy import (
+    BigInteger,
+    Boolean,
+    Column,
+    DateTime,
+    Float,
+    Integer,
+    LargeBinary,
+    String,
+    Text,
+    create_engine,
+    text,
+)
+from sqlalchemy.orm import Session, declarative_base
+
+Base = declarative_base()
+
+
+class User(Base):  # type: ignore[valid-type,misc]
+    __tablename__ = "users"
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String(100))
+    email = Column(String(100))
+
+
+class UnicodeTest(Base):  # type: ignore[valid-type,misc]
+    __tablename__ = "unicode_test"
+
+    id = Column(Integer, primary_key=True)
+    content = Column(Text)
+
+
+class BlobTest(Base):  # type: ignore[valid-type,misc]
+    __tablename__ = "blob_test"
+
+    id = Column(Integer, primary_key=True)
+    data = Column(LargeBinary)
+
+
+class NumericTest(Base):  # type: ignore[valid-type,misc]
+    __tablename__ = "numeric_test"
+
+    id = Column(Integer, primary_key=True)
+    int_val = Column(Integer)
+    bigint_val = Column(BigInteger)
+    float_val = Column(Float)
+    bool_val = Column(Boolean)
+
+
+class DateTimeTest(Base):  # type: ignore[valid-type,misc]
+    __tablename__ = "datetime_test"
+
+    id = Column(Integer, primary_key=True)
+    created_at = Column(DateTime)
+    updated_at = Column(DateTime, nullable=True)
+
+
+@pytest.mark.integration
+class TestORMOperations:
+    def test_create_engine(self, engine_url: str) -> None:
+        engine = create_engine(engine_url)
+        assert engine is not None
+        engine.dispose()
+
+    def test_raw_sql(self, engine_url: str) -> None:
+        engine = create_engine(engine_url)
+
+        with engine.connect() as conn:
+            result = conn.execute(text("SELECT 1"))
+            row = result.fetchone()
+            assert row is not None
+            assert row[0] == 1
+
+        engine.dispose()
+
+    def test_create_table_and_insert(self, engine_url: str) -> None:
+        engine = create_engine(engine_url)
+
+        # Create tables
+        Base.metadata.create_all(engine)
+
+        # Insert data
+        with Session(engine) as session:
+            user = User(name="Alice", email="alice@example.com")
+            session.add(user)
+            session.commit()
+
+            # Query data
+            users = session.query(User).filter_by(name="Alice").all()
+            assert len(users) == 1
+            assert users[0].email == "alice@example.com"
+
+        # Cleanup
+        Base.metadata.drop_all(engine)
+        engine.dispose()
+
+    def test_unicode_text(self, engine_url: str) -> None:
+        """Test Unicode text handling including emojis, CJK, RTL."""
+        engine = create_engine(engine_url)
+        Base.metadata.create_all(engine)
+
+        unicode_values = [
+            # Emojis (4-byte UTF-8)
+            "Hello 🎉 World",
+            "🎉🎊🎁🎂",
+            # CJK characters
+            "中文测试",
+            "日本語テスト",
+            "한국어 테스트",
+            # RTL languages
+            "العربية",
+            "עברית",
+            # Mixed scripts
+            "Hello 世界 🌍",
+            # Combining characters
+            "café résumé naïve",
+        ]
+
+        with Session(engine) as session:
+            for val in unicode_values:
+                # Insert
+                record = UnicodeTest(content=val)
+                session.add(record)
+                session.commit()
+
+                # Query and verify
+                result = session.query(UnicodeTest).filter_by(content=val).first()
+                assert result is not None, f"Failed to find: {repr(val)}"
+                assert result.content == val, f"Mismatch for: {repr(val)}"
+
+                # Cleanup
+                session.delete(result)
+                session.commit()
+
+        Base.metadata.drop_all(engine)
+        engine.dispose()
+
+    def test_binary_blob(self, engine_url: str) -> None:
+        """Test binary blob handling including null bytes."""
+        engine = create_engine(engine_url)
+        Base.metadata.create_all(engine)
+
+        blob_values = [
+            b"simple",
+            b"\x00\x01\x02\x03",  # Null bytes
+            b"\xff\xfe\xfd",  # High bytes
+            bytes(range(256)),  # All byte values
+        ]
+
+        with Session(engine) as session:
+            for val in blob_values:
+                # Insert
+                record = BlobTest(data=val)
+                session.add(record)
+                session.commit()
+
+                # Query and verify
+                result = session.query(BlobTest).order_by(BlobTest.id.desc()).first()
+                assert result is not None
+                assert result.data == val, f"Mismatch for blob: {repr(val)}"
+
+        Base.metadata.drop_all(engine)
+        engine.dispose()
+
+    def test_numeric_types(self, engine_url: str) -> None:
+        """Test integer, bigint, float, and boolean types.
+
+        Note: dqlite has a known limitation where BOOLEAN NULL values are
+        returned as False (type BOOLEAN with value 0) instead of NULL.
+        This is because dqlite returns the column's declared type even for
+        NULL values, and 0 is indistinguishable from NULL for BOOLEAN columns.
+        """
+        engine = create_engine(engine_url)
+        Base.metadata.create_all(engine)
+
+        test_cases = [
+            # (int, bigint, float, bool)
+            (0, 0, 0.0, False),
+            (1, 1, 1.0, True),
+            (-1, -1, -1.0, False),
+            (2147483647, 9223372036854775807, 3.14159265358979, True),
+            (-2147483648, -9223372036854775808, -3.14159265358979, False),
+        ]
+
+        with Session(engine) as session:
+            for int_val, bigint_val, float_val, bool_val in test_cases:
+                record = NumericTest(
+                    int_val=int_val,
+                    bigint_val=bigint_val,
+                    float_val=float_val,
+                    bool_val=bool_val,
+                )
+                session.add(record)
+                session.commit()
+
+                # Query and verify
+                result = session.query(NumericTest).order_by(NumericTest.id.desc()).first()
+                assert result is not None
+                assert result.int_val == int_val
+                assert result.bigint_val == bigint_val
+                if float_val is not None:
+                    assert abs(result.float_val - float_val) < 1e-9
+                assert result.bool_val == bool_val
+
+        Base.metadata.drop_all(engine)
+        engine.dispose()
+
+    def test_datetime_types(self, engine_url: str) -> None:
+        """Test DateTime column type.
+
+        Note: dqlite has a known limitation where DATETIME NULL values are
+        returned as empty string instead of NULL. This causes SQLAlchemy's
+        DateTime processor to fail when parsing. Avoid using NULL datetime
+        values with dqlite - use a sentinel value if needed.
+        """
+        engine = create_engine(engine_url)
+        Base.metadata.create_all(engine)
+
+        test_dates = [
+            datetime.datetime(2024, 1, 15, 10, 30, 45),
+            datetime.datetime(1970, 1, 1, 0, 0, 0),  # Unix epoch
+            datetime.datetime(2038, 1, 19, 3, 14, 7),  # Near Y2038
+            datetime.datetime.now().replace(microsecond=0),
+        ]
+
+        with Session(engine) as session:
+            for dt in test_dates:
+                # Note: We set updated_at to a value, not NULL, due to dqlite limitation
+                record = DateTimeTest(created_at=dt, updated_at=dt)
+                session.add(record)
+                session.commit()
+
+                # Query and verify
+                result = session.query(DateTimeTest).order_by(DateTimeTest.id.desc()).first()
+                assert result is not None
+
+                # SQLite stores datetime as text, compare with second precision
+                assert result.created_at.year == dt.year
+                assert result.created_at.month == dt.month
+                assert result.created_at.day == dt.day
+                assert result.created_at.hour == dt.hour
+                assert result.created_at.minute == dt.minute
+                assert result.created_at.second == dt.second
+
+        Base.metadata.drop_all(engine)
+        engine.dispose()
+
+    def test_null_handling(self, engine_url: str) -> None:
+        """Test NULL values across different column types."""
+        engine = create_engine(engine_url)
+        Base.metadata.create_all(engine)
+
+        with Session(engine) as session:
+            # Insert record with all nullable fields as NULL
+            record = NumericTest(
+                int_val=None,
+                bigint_val=None,
+                float_val=None,
+                bool_val=None,
+            )
+            session.add(record)
+            session.commit()
+
+            result = session.query(NumericTest).first()
+            assert result is not None
+            assert result.int_val is None
+            assert result.bigint_val is None
+            assert result.float_val is None
+            assert result.bool_val is None
+
+        Base.metadata.drop_all(engine)
+        engine.dispose()

sqlalchemy_dqlite-0.1.1/tests/test_dialect.py

@@ -0,0 +1,94 @@
+"""Tests for dqlite dialect."""
+
+from sqlalchemy.engine import URL
+
+from sqlalchemydqlite import DqliteDialect
+from sqlalchemydqlite.aio import DqliteDialect_aio
+
+
+class TestDqliteDialect:
+    def test_dialect_name(self) -> None:
+        dialect = DqliteDialect()
+        assert dialect.name == "dqlite"
+
+    def test_dialect_driver(self) -> None:
+        dialect = DqliteDialect()
+        assert dialect.driver == "dqlitedbapi"
+
+    def test_paramstyle(self) -> None:
+        dialect = DqliteDialect()
+        assert dialect.paramstyle == "qmark"
+
+    def test_import_dbapi(self) -> None:
+        dbapi = DqliteDialect.import_dbapi()
+        assert hasattr(dbapi, "connect")
+        assert hasattr(dbapi, "apilevel")
+        assert dbapi.apilevel == "2.0"
+
+    def test_create_connect_args_default(self) -> None:
+        dialect = DqliteDialect()
+        url = URL.create("dqlite")
+
+        args, kwargs = dialect.create_connect_args(url)
+
+        assert args == []
+        assert kwargs["address"] == "localhost:9001"
+        assert kwargs["database"] == "default"
+
+    def test_create_connect_args_custom(self) -> None:
+        dialect = DqliteDialect()
+        url = URL.create("dqlite", host="node1", port=9002, database="mydb")
+
+        args, kwargs = dialect.create_connect_args(url)
+
+        assert kwargs["address"] == "node1:9002"
+        assert kwargs["database"] == "mydb"
+
+
+class TestDqliteDialectAio:
+    def test_dialect_name(self) -> None:
+        dialect = DqliteDialect_aio()
+        assert dialect.name == "dqlite"
+
+    def test_dialect_is_async(self) -> None:
+        dialect = DqliteDialect_aio()
+        assert dialect.is_async is True
+
+    def test_import_dbapi(self) -> None:
+        dbapi = DqliteDialect_aio.import_dbapi()
+        assert hasattr(dbapi, "aconnect")
+
+    def test_import_dbapi_has_paramstyle(self) -> None:
+        """Async dbapi module must expose paramstyle for SQLAlchemy dialect init."""
+        dbapi = DqliteDialect_aio.import_dbapi()
+        assert dbapi.paramstyle == "qmark"
+
+    def test_import_dbapi_has_module_attributes(self) -> None:
+        """Async dbapi module must expose PEP 249 attributes for SQLAlchemy."""
+        dbapi = DqliteDialect_aio.import_dbapi()
+        assert dbapi.apilevel == "2.0"
+        assert dbapi.threadsafety == 1
+
+    def test_create_async_engine(self) -> None:
+        """create_async_engine must not raise during dialect initialization."""
+        from sqlalchemy.ext.asyncio import create_async_engine
+
+        engine = create_async_engine("dqlite+aio://localhost:19001/test")
+        assert engine.dialect.name == "dqlite"
+        assert engine.dialect.driver == "dqlitedbapi_aio"
+
+
+class TestURLParsing:
+    def test_parse_basic_url(self) -> None:
+        url = URL.create("dqlite", host="localhost", port=9001, database="test")
+        assert url.host == "localhost"
+        assert url.port == 9001
+        assert url.database == "test"
+
+    def test_url_string_format(self) -> None:
+        url = URL.create("dqlite", host="node1", port=9001, database="mydb")
+        assert str(url) == "dqlite://node1:9001/mydb"
+
+    def test_aio_url_string_format(self) -> None:
+        url = URL.create("dqlite+aio", host="node1", port=9001, database="mydb")
+        assert str(url) == "dqlite+aio://node1:9001/mydb"