etchdb 0.1.0__tar.gz

etchdb-0.1.0/.gitignore

@@ -0,0 +1,69 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Unit test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.pyre/
+.pytype/
+
+# Linting
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv (library: consumers decide their own lockfile)
+.uv/
+uv.lock
+
+# Local notes / scratch / handoffs (not part of public history)
+scratch/
+TODO.local.md
+.local/

etchdb-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

etchdb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hannu Varjoranta
+
+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.

etchdb-0.1.0/Makefile

@@ -0,0 +1,61 @@
+.PHONY: help install test test-unit test-integration coverage db-up db-down lint typecheck fix build deploy clean
+.DEFAULT_GOAL := help
+
+help:
+	@echo "etchdb development targets"
+	@echo ""
+	@echo "  make install           install package + dev deps in a uv venv"
+	@echo "  make test              run the full test suite (postgres tests skip if DB is down)"
+	@echo "  make test-unit         run only the dialect-neutral unit tests"
+	@echo "  make test-integration  bring up postgres, then run integration tests"
+	@echo "  make coverage          run the test suite with line-coverage reporting"
+	@echo "  make db-up             start the postgres container on localhost:5532"
+	@echo "  make db-down           stop and remove the postgres container + volumes"
+	@echo "  make lint              check lint + formatting"
+	@echo "  make typecheck         run static type checking (ty)"
+	@echo "  make fix               auto-format + auto-fix lint"
+	@echo "  make build             build sdist + wheel into dist/"
+	@echo "  make deploy            build then upload to PyPI (needs UV_PUBLISH_TOKEN)"
+	@echo "  make clean             remove build artifacts"
+
+install:
+	uv sync --extra dev --extra all
+
+test:
+	uv run pytest
+
+test-unit:
+	uv run pytest tests/unit -v
+
+test-integration: db-up
+	uv run pytest tests/integration -v
+
+coverage:
+	uv run pytest --cov=etchdb --cov-report=term-missing
+
+db-up:
+	docker compose up -d --wait postgres
+	@echo "postgres ready on localhost:5532"
+
+db-down:
+	docker compose down -v
+
+lint:
+	uv run ruff check .
+	uv run ruff format --check .
+
+typecheck:
+	uv run ty check src
+
+fix:
+	uv run ruff format .
+	uv run ruff check --fix .
+
+build: clean
+	uv build
+
+deploy: build
+	uv publish
+
+clean:
+	rm -rf dist/ build/ src/*.egg-info

etchdb-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: etchdb
+Version: 0.1.0
+Summary: Minimal async DB layer for Python. Typed CRUD over Pydantic, raw SQL when you need it
+Project-URL: Homepage, https://github.com/varjoranta/etchdb
+Project-URL: Repository, https://github.com/varjoranta/etchdb
+Project-URL: Issues, https://github.com/varjoranta/etchdb/issues
+Author-email: Hannu Varjoranta <hannu@varjosoft.com>
+License: MIT License
+        
+        Copyright (c) 2026 Hannu Varjoranta
+        
+        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.
+License-File: LICENSE
+Keywords: async,asyncpg,database,orm,postgresql,psycopg,pydantic,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: all
+Requires-Dist: aiosqlite>=0.19.0; extra == 'all'
+Requires-Dist: asyncpg>=0.30.0; extra == 'all'
+Requires-Dist: psycopg[binary]>=3.2; extra == 'all'
+Provides-Extra: asyncpg
+Requires-Dist: asyncpg>=0.30.0; extra == 'asyncpg'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Requires-Dist: ty; extra == 'dev'
+Provides-Extra: psycopg
+Requires-Dist: psycopg[binary]>=3.2; extra == 'psycopg'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.19.0; extra == 'sqlite'
+Description-Content-Type: text/markdown
+
+# etchdb
+
+Minimal async DB layer for Python. Typed CRUD over Pydantic. Raw SQL when you need it.
+
+## Status
+
+Alpha. v0.1.0 on PyPI. Built in public from day one; expect tightening between alpha releases.
+
+## Example
+
+```python
+from etchdb import DB, Row
+
+class User(Row):
+    __table__ = "users"
+    id: int | None = None             # leave unset and the DB allocates it (SERIAL / INTEGER PK)
+    name: str
+    email: str | None = None
+
+# Connect (driver inferred from URL scheme)
+db = await DB.from_url("postgresql+asyncpg://user@host/db")
+
+# Typed CRUD
+alice = await db.insert(User(name="Alice"))           # alice.id is now populated by the DB
+user = await db.get(User, id=alice.id)                # one row or None
+users = await db.query(User)                          # list of rows
+await db.update(User(id=alice.id, name="Alice B"))    # partial: email is preserved
+await db.delete(alice)
+
+# Typed-result raw SQL (covers most joins)
+users = await db.fetch_models(User, """
+    SELECT u.* FROM users u JOIN orders o ON o.user_id = u.id
+    WHERE o.created_at > $1
+""", since)
+
+# Untyped raw SQL (mirrors asyncpg)
+rows = await db.fetch("SELECT count(*) FROM events WHERE site_id = $1", site_id)
+val = await db.fetchval("SELECT count(*) FROM users")
+await db.execute("UPDATE users SET active = false WHERE id = $1", uid)
+
+# Transactions
+async with db.transaction() as tx:
+    await tx.insert(User(name="Carol"))
+    await tx.execute("INSERT INTO audit_log (...) VALUES (...)")
+
+# Inspect SQL before executing (etchdb's defining feature)
+q = db.compose("get", User, id=1)
+print(q.sql)     # SELECT id, name, email FROM users WHERE id = $1
+print(q.params)  # [1]
+```
+
+`insert` only emits the columns you actually set, so an unset `id` lets the database allocate one (SERIAL or INTEGER PRIMARY KEY). `update` does the same: a column you didn't touch keeps its current value rather than being clobbered. An explicit `None` counts as set in both cases.
+
+## Install
+
+Drivers are optional extras. Install only what you use:
+
+```bash
+pip install etchdb[asyncpg]    # asyncpg + Postgres
+pip install etchdb[psycopg]    # psycopg3 + Postgres
+pip install etchdb[sqlite]     # aiosqlite + SQLite
+pip install etchdb[all]        # everything
+```
+
+The top-level `etchdb` namespace depends only on Pydantic. Driver subpackages import their driver eagerly with a clear error if it is not installed.
+
+```python
+from etchdb import DB, Row                    # always safe
+from etchdb.asyncpg import AsyncpgAdapter     # requires asyncpg
+
+# Bring your own pool
+db = DB(AsyncpgAdapter.from_pool(my_pool))
+```
+
+## Why
+
+Most Python ORMs are heavy, opinionated, and leak at the seams when you reach for pgvector or PostGIS. Raw asyncpg works, but every project ends up writing the same Pydantic-bridge code. etchdb closes that gap without becoming a framework.
+
+The design also targets AI-assisted development: predictable verbs, no metaclass magic, no implicit context vars, no lazy loading, every typed operation produces inspectable SQL. Code an LLM can write correctly on the first attempt.
+
+## Goals
+
+- Driver-agnostic (asyncpg or psycopg3, swap freely)
+- Multi-dialect (Postgres primary, SQLite secondary, MySQL maybe)
+- Async native, no sync wrappers
+- Typed CRUD via Pydantic; raw SQL as first-class escape valve
+- Inspectable SQL: every typed op exposes its `(sql, params)` without executing
+
+## Non-goals
+
+- Query builder beyond simple CRUD (use raw SQL for joins)
+- Implicit relationships, lazy loading, eager loading
+- Sync support
+- A second canonical way to do anything
+
+## Migrations
+
+Out of scope for v0.1. A small forward-only, file-based migration helper (no autogenerate, no rollback, no DAG) is planned for a later release. etchdb owns no schema state today, so any external tool slots in fine in the meantime: Alembic if you also use SQLAlchemy, dbmate or sqitch if you don't, or a few `db.execute` calls in your bootstrap path.
+
+## Built with AI assistance
+
+Built with Claude Code as the primary development assistant. Design, code, and commits are reviewed and shipped by Hannu Varjoranta. Building in public, openly using AI tooling, is part of the project's premise.
+
+## License
+
+MIT.

etchdb-0.1.0/README.md

@@ -0,0 +1,106 @@
+# etchdb
+
+Minimal async DB layer for Python. Typed CRUD over Pydantic. Raw SQL when you need it.
+
+## Status
+
+Alpha. v0.1.0 on PyPI. Built in public from day one; expect tightening between alpha releases.
+
+## Example
+
+```python
+from etchdb import DB, Row
+
+class User(Row):
+    __table__ = "users"
+    id: int | None = None             # leave unset and the DB allocates it (SERIAL / INTEGER PK)
+    name: str
+    email: str | None = None
+
+# Connect (driver inferred from URL scheme)
+db = await DB.from_url("postgresql+asyncpg://user@host/db")
+
+# Typed CRUD
+alice = await db.insert(User(name="Alice"))           # alice.id is now populated by the DB
+user = await db.get(User, id=alice.id)                # one row or None
+users = await db.query(User)                          # list of rows
+await db.update(User(id=alice.id, name="Alice B"))    # partial: email is preserved
+await db.delete(alice)
+
+# Typed-result raw SQL (covers most joins)
+users = await db.fetch_models(User, """
+    SELECT u.* FROM users u JOIN orders o ON o.user_id = u.id
+    WHERE o.created_at > $1
+""", since)
+
+# Untyped raw SQL (mirrors asyncpg)
+rows = await db.fetch("SELECT count(*) FROM events WHERE site_id = $1", site_id)
+val = await db.fetchval("SELECT count(*) FROM users")
+await db.execute("UPDATE users SET active = false WHERE id = $1", uid)
+
+# Transactions
+async with db.transaction() as tx:
+    await tx.insert(User(name="Carol"))
+    await tx.execute("INSERT INTO audit_log (...) VALUES (...)")
+
+# Inspect SQL before executing (etchdb's defining feature)
+q = db.compose("get", User, id=1)
+print(q.sql)     # SELECT id, name, email FROM users WHERE id = $1
+print(q.params)  # [1]
+```
+
+`insert` only emits the columns you actually set, so an unset `id` lets the database allocate one (SERIAL or INTEGER PRIMARY KEY). `update` does the same: a column you didn't touch keeps its current value rather than being clobbered. An explicit `None` counts as set in both cases.
+
+## Install
+
+Drivers are optional extras. Install only what you use:
+
+```bash
+pip install etchdb[asyncpg]    # asyncpg + Postgres
+pip install etchdb[psycopg]    # psycopg3 + Postgres
+pip install etchdb[sqlite]     # aiosqlite + SQLite
+pip install etchdb[all]        # everything
+```
+
+The top-level `etchdb` namespace depends only on Pydantic. Driver subpackages import their driver eagerly with a clear error if it is not installed.
+
+```python
+from etchdb import DB, Row                    # always safe
+from etchdb.asyncpg import AsyncpgAdapter     # requires asyncpg
+
+# Bring your own pool
+db = DB(AsyncpgAdapter.from_pool(my_pool))
+```
+
+## Why
+
+Most Python ORMs are heavy, opinionated, and leak at the seams when you reach for pgvector or PostGIS. Raw asyncpg works, but every project ends up writing the same Pydantic-bridge code. etchdb closes that gap without becoming a framework.
+
+The design also targets AI-assisted development: predictable verbs, no metaclass magic, no implicit context vars, no lazy loading, every typed operation produces inspectable SQL. Code an LLM can write correctly on the first attempt.
+
+## Goals
+
+- Driver-agnostic (asyncpg or psycopg3, swap freely)
+- Multi-dialect (Postgres primary, SQLite secondary, MySQL maybe)
+- Async native, no sync wrappers
+- Typed CRUD via Pydantic; raw SQL as first-class escape valve
+- Inspectable SQL: every typed op exposes its `(sql, params)` without executing
+
+## Non-goals
+
+- Query builder beyond simple CRUD (use raw SQL for joins)
+- Implicit relationships, lazy loading, eager loading
+- Sync support
+- A second canonical way to do anything
+
+## Migrations
+
+Out of scope for v0.1. A small forward-only, file-based migration helper (no autogenerate, no rollback, no DAG) is planned for a later release. etchdb owns no schema state today, so any external tool slots in fine in the meantime: Alembic if you also use SQLAlchemy, dbmate or sqitch if you don't, or a few `db.execute` calls in your bootstrap path.
+
+## Built with AI assistance
+
+Built with Claude Code as the primary development assistant. Design, code, and commits are reviewed and shipped by Hannu Varjoranta. Building in public, openly using AI tooling, is part of the project's premise.
+
+## License
+
+MIT.

etchdb-0.1.0/docker-compose.yml

@@ -0,0 +1,16 @@
+services:
+  postgres:
+    image: postgres:18-trixie
+    container_name: etchdb-postgres-test
+    environment:
+      POSTGRES_DB: etchdb_test
+      POSTGRES_USER: etchdb
+      POSTGRES_PASSWORD: etchdb-test-password
+    ports:
+      - "5532:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U etchdb -d etchdb_test"]
+      interval: 1s
+      timeout: 1s
+      retries: 30
+    restart: unless-stopped

etchdb-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[project]
+name = "etchdb"
+version = "0.1.0"
+description = "Minimal async DB layer for Python. Typed CRUD over Pydantic, raw SQL when you need it"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Hannu Varjoranta", email = "hannu@varjosoft.com" },
+]
+keywords = [
+    "postgresql",
+    "asyncpg",
+    "psycopg",
+    "pydantic",
+    "async",
+    "database",
+    "sqlite",
+    "orm",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+    "Topic :: Database :: Database Engines/Servers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "License :: OSI Approved :: MIT License",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+asyncpg = ["asyncpg>=0.30.0"]
+psycopg = ["psycopg[binary]>=3.2"]
+sqlite = ["aiosqlite>=0.19.0"]
+all = [
+    "asyncpg>=0.30.0",
+    "psycopg[binary]>=3.2",
+    "aiosqlite>=0.19.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.5.0",
+    "ty",
+]
+
+[project.urls]
+Homepage = "https://github.com/varjoranta/etchdb"
+Repository = "https://github.com/varjoranta/etchdb"
+Issues = "https://github.com/varjoranta/etchdb/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/etchdb"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

etchdb-0.1.0/src/etchdb/__init__.py

@@ -0,0 +1,9 @@
+"""etchdb: minimal async DB layer for Python."""
+
+from etchdb.db import DB
+from etchdb.query import SqlQuery
+from etchdb.row import Row
+
+__version__ = "0.1.0"
+
+__all__ = ["DB", "Row", "SqlQuery", "__version__"]

etchdb-0.1.0/src/etchdb/adapter.py

@@ -0,0 +1,56 @@
+"""Abstract DB adapter; the boundary DB sits on top of."""
+
+from abc import ABC, abstractmethod
+from contextlib import AbstractAsyncContextManager
+from typing import Any
+
+
+class AdapterBase(ABC):
+    """Abstract DB adapter implemented by each driver.
+
+    The four raw-SQL methods mirror asyncpg's vocabulary:
+    `execute / fetch / fetchrow / fetchval`. All take positional
+    `*params` bound through the driver's parameterised query API.
+
+    `placeholder(i)` converts a 0-indexed parameter position to the
+    driver's placeholder syntax. Postgres returns `$1, $2, ...`; SQLite
+    returns `?`.
+    """
+
+    @staticmethod
+    @abstractmethod
+    def placeholder(i: int) -> str:
+        """Return the placeholder for the i-th parameter (0-indexed)."""
+        ...
+
+    @abstractmethod
+    async def execute(self, sql: str, *params: Any) -> Any: ...
+
+    @abstractmethod
+    async def fetch(self, sql: str, *params: Any) -> list[dict[str, Any]]: ...
+
+    @abstractmethod
+    async def fetchrow(self, sql: str, *params: Any) -> dict[str, Any] | None: ...
+
+    @abstractmethod
+    async def fetchval(self, sql: str, *params: Any) -> Any: ...
+
+    @abstractmethod
+    def transaction(self) -> AbstractAsyncContextManager["AdapterBase"]:
+        """Return an async context manager yielding a transaction-scoped adapter.
+
+        Inside the `async with` block, all calls on the yielded adapter run
+        on the same connection within a single transaction. The transaction
+        commits on a clean exit and rolls back on any exception.
+        """
+        ...
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Release resources owned by this adapter.
+
+        For pool-owning adapters created via `from_url`, this closes the
+        pool. For adapters wrapping an externally-managed pool (`from_pool`),
+        this is a no-op; the caller owns the pool's lifecycle.
+        """
+        ...

etchdb-0.1.0/src/etchdb/aiosqlite/__init__.py

@@ -0,0 +1,17 @@
+"""aiosqlite adapter for etchdb.
+
+Importing this subpackage requires aiosqlite to be installed. The
+top-level `etchdb` namespace does NOT depend on aiosqlite; only this
+subpackage does.
+"""
+
+try:
+    import aiosqlite as _aiosqlite  # noqa: F401
+except ImportError as e:
+    raise ImportError(
+        "etchdb.aiosqlite requires the aiosqlite package. Install with: pip install etchdb[sqlite]"
+    ) from e
+
+from etchdb.aiosqlite.adapter import AiosqliteAdapter
+
+__all__ = ["AiosqliteAdapter"]