etchdb 0.1.0__py3-none-any.whl

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/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/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"]

etchdb/aiosqlite/adapter.py

@@ -0,0 +1,148 @@
+"""aiosqlite adapter implementation.
+
+aiosqlite has no pool concept; it wraps a single sqlite3 connection
+that runs on its own background thread. The adapter therefore holds
+one connection rather than a pool. Concurrent calls serialise through
+aiosqlite's internal queue, which is the correct sqlite3 model.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+from urllib.parse import urlparse
+
+import aiosqlite
+
+from etchdb.adapter import AdapterBase
+
+
+def _path_from_url(url: str) -> str:
+    """Extract the SQLite database path from a URL.
+
+    Supported forms:
+      sqlite:///:memory:                    -> ":memory:"
+      sqlite+aiosqlite:///:memory:          -> ":memory:"
+      sqlite:///relative.db                 -> "relative.db"
+      sqlite:////absolute/path.db           -> "/absolute/path.db"
+    """
+    parsed = urlparse(url)
+    path = parsed.path
+    if path.startswith("/"):
+        path = path[1:]
+    return path or ":memory:"
+
+
+class AiosqliteAdapter(AdapterBase):
+    """AdapterBase implementation backed by a single aiosqlite connection.
+
+    Construct via `from_connection(conn)` to wrap an externally-managed
+    connection (etchdb will not close it), or `await from_url(url)` to
+    let etchdb create and own the connection.
+    """
+
+    def __init__(self, conn: aiosqlite.Connection, *, owns_conn: bool = False):
+        self._conn = conn
+        self._owns_conn = owns_conn
+
+    @staticmethod
+    def placeholder(i: int) -> str:
+        return "?"
+
+    @classmethod
+    def from_connection(cls, conn: aiosqlite.Connection) -> AiosqliteAdapter:
+        """Wrap an externally-managed aiosqlite connection. The caller closes it."""
+        return cls(conn, owns_conn=False)
+
+    @classmethod
+    async def from_url(cls, url: str) -> AiosqliteAdapter:
+        """Open an aiosqlite connection from `url` and wrap it.
+
+        etchdb owns the connection; `close()` will close it.
+        """
+        path = _path_from_url(url)
+        conn = await aiosqlite.connect(path)
+        conn.row_factory = aiosqlite.Row
+        return cls(conn, owns_conn=True)
+
+    async def execute(self, sql: str, *params: Any) -> Any:
+        await self._conn.execute(sql, params)
+        await self._conn.commit()
+
+    async def fetch(self, sql: str, *params: Any) -> list[dict[str, Any]]:
+        async with self._conn.execute(sql, params) as cursor:
+            rows = await cursor.fetchall()
+        return [dict(r) for r in rows]
+
+    async def fetchrow(self, sql: str, *params: Any) -> dict[str, Any] | None:
+        async with self._conn.execute(sql, params) as cursor:
+            row = await cursor.fetchone()
+        return dict(row) if row is not None else None
+
+    async def fetchval(self, sql: str, *params: Any) -> Any:
+        async with self._conn.execute(sql, params) as cursor:
+            row = await cursor.fetchone()
+        return row[0] if row is not None else None
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncIterator[AdapterBase]:
+        # sqlite3's default isolation_level auto-injects BEGIN before DML,
+        # so we don't emit one explicitly; we just commit on clean exit
+        # and rollback on any exception.
+        try:
+            yield _AiosqliteTxAdapter(self._conn)
+        except BaseException:
+            await self._conn.rollback()
+            raise
+        else:
+            await self._conn.commit()
+
+    async def close(self) -> None:
+        if self._owns_conn:
+            await self._conn.close()
+
+
+class _AiosqliteTxAdapter(AdapterBase):
+    """Tx-scoped aiosqlite adapter; does not commit on each statement."""
+
+    def __init__(self, conn: aiosqlite.Connection):
+        self._conn = conn
+
+    @staticmethod
+    def placeholder(i: int) -> str:
+        return "?"
+
+    async def execute(self, sql: str, *params: Any) -> Any:
+        await self._conn.execute(sql, params)
+
+    async def fetch(self, sql: str, *params: Any) -> list[dict[str, Any]]:
+        async with self._conn.execute(sql, params) as cursor:
+            rows = await cursor.fetchall()
+        return [dict(r) for r in rows]
+
+    async def fetchrow(self, sql: str, *params: Any) -> dict[str, Any] | None:
+        async with self._conn.execute(sql, params) as cursor:
+            row = await cursor.fetchone()
+        return dict(row) if row is not None else None
+
+    async def fetchval(self, sql: str, *params: Any) -> Any:
+        async with self._conn.execute(sql, params) as cursor:
+            row = await cursor.fetchone()
+        return row[0] if row is not None else None
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncIterator[AdapterBase]:
+        sp = "etchdb_sp"
+        await self._conn.execute(f"SAVEPOINT {sp}")
+        try:
+            yield self
+        except BaseException:
+            await self._conn.execute(f"ROLLBACK TO SAVEPOINT {sp}")
+            await self._conn.execute(f"RELEASE SAVEPOINT {sp}")
+            raise
+        else:
+            await self._conn.execute(f"RELEASE SAVEPOINT {sp}")
+
+    async def close(self) -> None:
+        return None

etchdb/asyncpg/__init__.py

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

etchdb/asyncpg/adapter.py

@@ -0,0 +1,106 @@
+"""asyncpg adapter implementation."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+import asyncpg
+
+from etchdb.adapter import AdapterBase
+
+
+class AsyncpgAdapter(AdapterBase):
+    """AdapterBase implementation backed by an asyncpg pool.
+
+    Construct via `from_pool(pool)` to wrap an externally-managed pool
+    (etchdb will not close it), or `await from_url(url)` to let etchdb
+    create and own the pool. The `owns_pool` flag tracks ownership.
+
+    For custom pool settings (init=, min_size=, max_size=, codecs),
+    create the pool yourself with `asyncpg.create_pool(...)` and pass
+    it to `from_pool`. `from_url` is intentionally minimal.
+    """
+
+    def __init__(self, pool: asyncpg.Pool, *, owns_pool: bool = False):
+        self._pool = pool
+        self._owns_pool = owns_pool
+
+    @staticmethod
+    def placeholder(i: int) -> str:
+        return f"${i + 1}"
+
+    @classmethod
+    def from_pool(cls, pool: asyncpg.Pool) -> AsyncpgAdapter:
+        """Wrap an externally-managed asyncpg pool. The caller closes it."""
+        return cls(pool, owns_pool=False)
+
+    @classmethod
+    async def from_url(cls, url: str) -> AsyncpgAdapter:
+        """Create an asyncpg pool from `url` and wrap it.
+
+        etchdb owns the pool; `close()` will close it.
+        """
+        pool = await asyncpg.create_pool(url)
+        return cls(pool, owns_pool=True)
+
+    async def execute(self, sql: str, *params: Any) -> Any:
+        async with self._pool.acquire() as conn:
+            return await conn.execute(sql, *params)
+
+    async def fetch(self, sql: str, *params: Any) -> list[dict[str, Any]]:
+        async with self._pool.acquire() as conn:
+            records = await conn.fetch(sql, *params)
+        return [dict(r) for r in records]
+
+    async def fetchrow(self, sql: str, *params: Any) -> dict[str, Any] | None:
+        async with self._pool.acquire() as conn:
+            record = await conn.fetchrow(sql, *params)
+        return dict(record) if record is not None else None
+
+    async def fetchval(self, sql: str, *params: Any) -> Any:
+        async with self._pool.acquire() as conn:
+            return await conn.fetchval(sql, *params)
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncIterator[AdapterBase]:
+        async with self._pool.acquire() as conn, conn.transaction():
+            yield _AsyncpgConnAdapter(conn)
+
+    async def close(self) -> None:
+        if self._owns_pool:
+            await self._pool.close()
+
+
+class _AsyncpgConnAdapter(AdapterBase):
+    """Single-connection adapter, used inside a transaction."""
+
+    def __init__(self, conn: asyncpg.Connection):
+        self._conn = conn
+
+    @staticmethod
+    def placeholder(i: int) -> str:
+        return f"${i + 1}"
+
+    async def execute(self, sql: str, *params: Any) -> Any:
+        return await self._conn.execute(sql, *params)
+
+    async def fetch(self, sql: str, *params: Any) -> list[dict[str, Any]]:
+        records = await self._conn.fetch(sql, *params)
+        return [dict(r) for r in records]
+
+    async def fetchrow(self, sql: str, *params: Any) -> dict[str, Any] | None:
+        record = await self._conn.fetchrow(sql, *params)
+        return dict(record) if record is not None else None
+
+    async def fetchval(self, sql: str, *params: Any) -> Any:
+        return await self._conn.fetchval(sql, *params)
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncIterator[AdapterBase]:
+        async with self._conn.transaction():
+            yield self
+
+    async def close(self) -> None:
+        return None

etchdb/db.py

@@ -0,0 +1,179 @@
+"""DB facade: the user-facing entry point.
+
+DB sits on top of an AdapterBase and exposes the user-facing API:
+typed CRUD over Row, raw SQL passthrough mirroring asyncpg's
+vocabulary, typed-result helpers `fetch_models / fetch_model`, a
+transaction context manager, and a `compose` inspector for previewing
+the SQL of a typed op without executing it. Construct directly with
+an adapter, or via the URL-scheme dispatcher `DB.from_url`.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any, Literal
+from urllib.parse import urlparse
+
+from etchdb import sql
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from etchdb.adapter import AdapterBase
+    from etchdb.query import SqlQuery
+    from etchdb.row import Row
+
+
+def _hydrate(model_or_row: type[Row] | Row, row: dict[str, Any] | None) -> Row | None:
+    """Build a Row from a fetchrow result, or return None when there is no row.
+
+    Centralises the dict-to-Row construction and the None-handling that
+    fetchrow-based methods (`fetch_model`, `insert`, `update`) all share.
+    `model_or_row` may be either a Row class (for `fetch_model`) or a Row
+    instance whose class should be used (for `insert` and `update`).
+    """
+    if row is None:
+        return None
+    cls = model_or_row if isinstance(model_or_row, type) else type(model_or_row)
+    return cls(**row)
+
+
+_COMPOSE_OPS = {
+    "get": sql.select_one,
+    "query": sql.select_many,
+    "insert": sql.insert,
+    "update": sql.update,
+    "delete": sql.delete,
+}
+
+
+class DB:
+    """User-facing DB facade."""
+
+    def __init__(self, adapter: AdapterBase):
+        self._adapter = adapter
+
+    @classmethod
+    async def from_url(cls, url: str) -> DB:
+        """Open a DB from a URL, dispatching on the URL scheme.
+
+        Supported schemes:
+          postgresql://, postgres://, postgresql+asyncpg://  -> asyncpg
+          sqlite:///, sqlite+aiosqlite:///                   -> aiosqlite
+          postgresql+psycopg://                              -> NotImplementedError
+
+        Driver subpackages are imported lazily so users only need the
+        driver they actually use installed.
+        """
+        scheme = urlparse(url).scheme.lower()
+
+        if scheme in {"postgresql", "postgres", "postgresql+asyncpg"}:
+            from etchdb.asyncpg import AsyncpgAdapter
+
+            # asyncpg only accepts the bare postgresql:// scheme.
+            if scheme == "postgresql+asyncpg":
+                url = "postgresql://" + url.split("://", 1)[1]
+            adapter: AdapterBase = await AsyncpgAdapter.from_url(url)
+        elif scheme in {"sqlite", "sqlite+aiosqlite"}:
+            from etchdb.aiosqlite import AiosqliteAdapter
+
+            adapter = await AiosqliteAdapter.from_url(url)
+        elif scheme == "postgresql+psycopg":
+            raise NotImplementedError("psycopg adapter not yet shipped")
+        else:
+            raise ValueError(f"Unsupported URL scheme: {scheme!r}")
+
+        return cls(adapter)
+
+    async def execute(self, sql: str, *params: Any) -> Any:
+        return await self._adapter.execute(sql, *params)
+
+    async def fetch(self, sql: str, *params: Any) -> list[dict[str, Any]]:
+        return await self._adapter.fetch(sql, *params)
+
+    async def fetchrow(self, sql: str, *params: Any) -> dict[str, Any] | None:
+        return await self._adapter.fetchrow(sql, *params)
+
+    async def fetchval(self, sql: str, *params: Any) -> Any:
+        return await self._adapter.fetchval(sql, *params)
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncIterator[DB]:
+        """Open a transaction. Commits on clean exit, rolls back on exception.
+
+        Yields a DB bound to the transaction's connection so that calls
+        on `tx` use the same connection as the surrounding block.
+        """
+        async with self._adapter.transaction() as tx_adapter:
+            yield DB(tx_adapter)
+
+    async def close(self) -> None:
+        await self._adapter.close()
+
+    async def fetch_models(self, model: type[Row], sql: str, *params: Any) -> list[Row]:
+        rows = await self._adapter.fetch(sql, *params)
+        return [model(**r) for r in rows]
+
+    async def fetch_model(self, model: type[Row], sql: str, *params: Any) -> Row | None:
+        row = await self._adapter.fetchrow(sql, *params)
+        return _hydrate(model, row)
+
+    async def get(self, model: type[Row], **filters: Any) -> Row | None:
+        q = sql.select_one(model, placeholder=self._adapter.placeholder, **filters)
+        return await self.fetch_model(model, q.sql, *q.params)
+
+    async def query(
+        self,
+        model: type[Row],
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        order_by: str | list[str] | None = None,
+        **filters: Any,
+    ) -> list[Row]:
+        q = sql.select_many(
+            model,
+            placeholder=self._adapter.placeholder,
+            limit=limit,
+            offset=offset,
+            order_by=order_by,
+            **filters,
+        )
+        return await self.fetch_models(model, q.sql, *q.params)
+
+    async def insert(self, row: Row) -> Row:
+        q = sql.insert(row, placeholder=self._adapter.placeholder)
+        result = await self._adapter.fetchrow(q.sql, *q.params)
+        return _hydrate(row, result) or row
+
+    async def update(self, row: Row) -> Row | None:
+        """Update `row` keyed by its primary key. Returns the updated row,
+        or None if no row matched."""
+        q = sql.update(row, placeholder=self._adapter.placeholder, returning="*")
+        result = await self._adapter.fetchrow(q.sql, *q.params)
+        return _hydrate(row, result)
+
+    async def delete(self, row: Row) -> None:
+        q = sql.delete(row, placeholder=self._adapter.placeholder)
+        await self._adapter.execute(q.sql, *q.params)
+
+    def compose(
+        self,
+        op: Literal["get", "query", "insert", "update", "delete"],
+        *args: Any,
+        **kwargs: Any,
+    ) -> SqlQuery:
+        """Return the SqlQuery a typed op would produce, without executing it.
+
+        Lets callers inspect or test SQL before it touches the DB. The
+        placeholder style follows the underlying adapter ($N for asyncpg,
+        ? for aiosqlite).
+
+            q = db.compose("get", User, id=1)
+            print(q.sql, q.params)
+        """
+        try:
+            fn = _COMPOSE_OPS[op]
+        except KeyError as e:
+            raise ValueError(f"Unknown op {op!r}. Expected one of: {sorted(_COMPOSE_OPS)}") from e
+        return fn(*args, placeholder=self._adapter.placeholder, **kwargs)

etchdb/query.py

@@ -0,0 +1,18 @@
+"""Inspectable SQL value type."""
+
+from typing import Any, NamedTuple
+
+
+class SqlQuery(NamedTuple):
+    """A SQL string and its bound parameters.
+
+    Returned by every typed operation in etchdb. Useful for testing,
+    debugging, and copy-pasting into psql.
+
+        q = pg.insert(user)
+        print(q.sql)     # INSERT INTO users (id, name) VALUES ($1, $2) RETURNING *
+        print(q.params)  # [1, "Alice"]
+    """
+
+    sql: str
+    params: list[Any]

etchdb/row.py

@@ -0,0 +1,29 @@
+"""Base class for typed table rows."""
+
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+
+class Row(BaseModel):
+    """Base class for typed table rows.
+
+    Subclass to declare a table:
+
+        class User(Row):
+            __table__ = "users"
+            id: int
+            name: str
+
+    `__table__` is required. `__pk__` defaults to `("id",)`; override
+    if your primary key is composite or named differently.
+
+        class UserRole(Row):
+            __table__ = "user_roles"
+            __pk__ = ("user_id", "role_id")
+            user_id: int
+            role_id: int
+    """
+
+    __table__: ClassVar[str]
+    __pk__: ClassVar[tuple[str, ...]] = ("id",)

etchdb/sql/__init__.py

@@ -0,0 +1,209 @@
+"""Dialect-neutral SQL emitter.
+
+Generates SqlQuery values for typed Row operations. Driver-free: knows
+nothing about asyncpg, psycopg, or aiosqlite. Each adapter passes its
+own `placeholder` callable so the same emitter works for both Postgres
+($1, $2, ...) and SQLite (?, ?, ...).
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from etchdb.query import SqlQuery
+from etchdb.row import Row
+
+
+def insert(
+    row: Row,
+    *,
+    placeholder: Callable[[int], str],
+    returning: str | list[str] | None = "*",
+) -> SqlQuery:
+    """Build an INSERT for `row`, emitting only fields in `model_fields_set`.
+
+    Defaulted fields are omitted so the database applies its own DEFAULT
+    (or sequence). An explicit `None` is treated as set. With nothing
+    set, emits `INSERT INTO ... DEFAULT VALUES`. `returning="*"` by
+    default; pass `None` or a column list to override.
+    """
+    table = _table_name(row)
+    fields = [f for f in type(row).model_fields if f in row.model_fields_set]
+
+    if not fields:
+        sql = f"INSERT INTO {table} DEFAULT VALUES"
+        if returning is not None:
+            sql += f" RETURNING {_format_columns(returning)}"
+        return SqlQuery(sql=sql, params=[])
+
+    values = [getattr(row, f) for f in fields]
+    columns = ", ".join(fields)
+    placeholders = ", ".join(placeholder(i) for i in range(len(fields)))
+
+    sql = f"INSERT INTO {table} ({columns}) VALUES ({placeholders})"
+    if returning is not None:
+        sql += f" RETURNING {_format_columns(returning)}"
+
+    return SqlQuery(sql=sql, params=values)
+
+
+def select_one(
+    row_class: type[Row],
+    *,
+    placeholder: Callable[[int], str],
+    **filters: Any,
+) -> SqlQuery:
+    """Build a SELECT for at most one row matching `filters`.
+
+    Filters are joined with AND. Pass no filters to fetch the first row
+    in the table (mostly useful for tests / single-row tables).
+    """
+    table = _table_name(row_class)
+    columns = ", ".join(row_class.model_fields)
+
+    where_sql = _eq_clauses(list(filters), placeholder=placeholder)
+    sql = f"SELECT {columns} FROM {table}"
+    if where_sql:
+        sql += f" WHERE {where_sql}"
+    sql += " LIMIT 1"
+
+    return SqlQuery(sql=sql, params=list(filters.values()))
+
+
+def select_many(
+    row_class: type[Row],
+    *,
+    placeholder: Callable[[int], str],
+    limit: int | None = None,
+    offset: int | None = None,
+    order_by: str | list[str] | None = None,
+    **filters: Any,
+) -> SqlQuery:
+    """Build a SELECT for multiple rows.
+
+    Filters (keyword arguments) are joined with AND. `limit`, `offset`,
+    and `order_by` are keyword-only. `limit` and `offset` are bound as
+    parameters; `order_by` is interpolated as a raw SQL fragment, so do
+    not pass user-controlled values to it.
+    """
+    table = _table_name(row_class)
+    columns = ", ".join(row_class.model_fields)
+
+    where_sql = _eq_clauses(list(filters), placeholder=placeholder)
+    params: list[Any] = list(filters.values())
+
+    sql = f"SELECT {columns} FROM {table}"
+    if where_sql:
+        sql += f" WHERE {where_sql}"
+    if order_by:
+        sql += f" ORDER BY {_format_columns(order_by)}"
+    if limit is not None:
+        params.append(int(limit))
+        sql += f" LIMIT {placeholder(len(params) - 1)}"
+    if offset is not None:
+        params.append(int(offset))
+        sql += f" OFFSET {placeholder(len(params) - 1)}"
+
+    return SqlQuery(sql=sql, params=params)
+
+
+def update(
+    row: Row,
+    *,
+    placeholder: Callable[[int], str],
+    returning: str | list[str] | None = None,
+) -> SqlQuery:
+    """Build an UPDATE for `row` keyed by its primary key.
+
+    Only fields in `model_fields_set` go into the SET clause, giving
+    partial-update semantics: columns the caller didn't touch are
+    preserved. WHERE uses every field in `__pk__`. Raises ValueError if
+    any PK field is unset (no row to identify) or if no non-PK field is
+    set (nothing to update). Pass `returning="*"` to add RETURNING.
+    """
+    table = _table_name(row)
+    _ensure_pk_set(row, "update")
+    pk_set = set(row.__pk__)
+    set_fields = [
+        f for f in type(row).model_fields if f in row.model_fields_set and f not in pk_set
+    ]
+
+    if not set_fields:
+        raise ValueError(f"{type(row).__name__} has no non-PK fields to update")
+
+    set_sql = _eq_clauses(set_fields, placeholder=placeholder, sep=", ")
+    pk_sql = _eq_clauses(list(row.__pk__), placeholder=placeholder, start=len(set_fields))
+
+    set_values = [getattr(row, f) for f in set_fields]
+    pk_values = [getattr(row, f) for f in row.__pk__]
+
+    sql = f"UPDATE {table} SET {set_sql} WHERE {pk_sql}"
+    if returning is not None:
+        sql += f" RETURNING {_format_columns(returning)}"
+
+    return SqlQuery(sql=sql, params=set_values + pk_values)
+
+
+def delete(row: Row, *, placeholder: Callable[[int], str]) -> SqlQuery:
+    """Build a DELETE for `row` keyed by its primary key.
+
+    Raises ValueError if any PK field is unset (no row to identify).
+    """
+    table = _table_name(row)
+    _ensure_pk_set(row, "delete")
+    pk_sql = _eq_clauses(list(row.__pk__), placeholder=placeholder)
+    pk_values = [getattr(row, f) for f in row.__pk__]
+
+    sql = f"DELETE FROM {table} WHERE {pk_sql}"
+    return SqlQuery(sql=sql, params=pk_values)
+
+
+# --- helpers ----------------------------------------------------------
+
+
+def _ensure_pk_set(row: Row, op: str) -> None:
+    """Raise ValueError if any field in __pk__ is not in model_fields_set.
+
+    Without this check, an unset PK field would yield `WHERE id = NULL`,
+    which matches no rows: the caller's update or delete becomes a
+    silent no-op. Failing loudly catches "I forgot to set the PK".
+    """
+    unset = [f for f in row.__pk__ if f not in row.model_fields_set]
+    if unset:
+        raise ValueError(
+            f"Cannot {op}: primary key field(s) {unset} not set on this "
+            f"{type(row).__name__}. Set them so the row can be identified."
+        )
+
+
+def _table_name(row_or_class: Row | type[Row]) -> str:
+    cls = row_or_class if isinstance(row_or_class, type) else type(row_or_class)
+    table = getattr(cls, "__table__", None)
+    if not table:
+        raise ValueError(
+            f"{cls.__name__} has no __table__ attribute. "
+            "Set `__table__ = 'your_table_name'` on the Row subclass."
+        )
+    return table
+
+
+def _eq_clauses(
+    fields: list[str],
+    *,
+    placeholder: Callable[[int], str],
+    start: int = 0,
+    sep: str = " AND ",
+) -> str:
+    """Build `field1 = ? AND field2 = ? ...` clauses with the given placeholder style.
+
+    `start` is the 0-indexed position in the surrounding parameter list at
+    which this clause's parameters begin (matters for Postgres `$N` numbering).
+    """
+    if not fields:
+        return ""
+    return sep.join(f"{f} = {placeholder(start + i)}" for i, f in enumerate(fields))
+
+
+def _format_columns(cols: str | list[str]) -> str:
+    if isinstance(cols, str):
+        return cols
+    return ", ".join(cols)

etchdb-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+etchdb/__init__.py,sha256=BVNM4Hn-QZ5NBc90fjvFDbyCjDpqYIpquMEyTqDY1Q4,211
+etchdb/adapter.py,sha256=C-T1c8lYsdFeDLDyBtE_Dh_tr_Hi5jbIcn6cPOpeVqE,1907
+etchdb/db.py,sha256=RVGlX4aGZF9ruqnQ6m1QSSNQM8qD3WnsaZIzy-gii7g,6607
+etchdb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+etchdb/query.py,sha256=OWtbNKnYjBW0eBVuYLvW9ytUSoIKWyjM9kNRUZeZiBc,456
+etchdb/row.py,sha256=A87TOBdLbNpe_EwH3_3364x00VkYJvL2q4aHodNOGyE,675
+etchdb/aiosqlite/__init__.py,sha256=NJ3vJ8WZxRbZymhKUiAMY08DWgl70__2gwuKEwapPZ0,493
+etchdb/aiosqlite/adapter.py,sha256=at9vu2Zpj7ythdb6MiLFZshDbdJx34tcYgqYoA9eGTM,5140
+etchdb/asyncpg/__init__.py,sha256=fEB__qclkBuluXGiVVMxuy33GT3RexSB5WDeNoZhKro,474
+etchdb/asyncpg/adapter.py,sha256=mqyq0ayAD2CT-QV8oV54azAxUzy1t30RsKghAh5Q-h8,3632
+etchdb/sql/__init__.py,sha256=CA9ALtQeRgot3FSoFrj--Mk6ezbet98sMewukm55hVM,6976
+etchdb-0.1.0.dist-info/METADATA,sha256=l9gU_wq0VT-CN0oLXv5-12qFFuLo04-HFJh4Ykmjjs4,7167
+etchdb-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+etchdb-0.1.0.dist-info/licenses/LICENSE,sha256=RnIp7FS8GthGT8lKJ1TorahoQuzqoVVkMIdfNtLh788,1073
+etchdb-0.1.0.dist-info/RECORD,,

etchdb-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

etchdb-0.1.0.dist-info/licenses/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.