pyxle-db 0.2.0__tar.gz

pyxle_db-0.2.0/.gitignore

@@ -0,0 +1,37 @@
+# Python bytecode
+__pycache__/
+*.py[codz]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+venv/
+.venv/
+
+# Test / coverage
+htmlcov/
+.coverage
+.coverage.*
+.pytest_cache/
+coverage.xml
+
+# Node
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Tooling caches
+.ruff_cache/

pyxle_db-0.2.0/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to `pyxle-db` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-06-11
+
+### Changed (BREAKING)
+
+- `Database.transaction()` now yields a transaction whose methods are
+  coroutines: `await tx.execute(...)`, `await tx.fetchone(...)`, etc.
+  In 0.1 these calls were synchronous inside the async context manager.
+- `Database.close()` and `Database.sync_transaction()` are SQLite-only
+  and raise `UnsupportedOperationError` on server backends. Use
+  `await db.aclose()` and `async with db.transaction()` — both work on
+  every backend.
+- Mapping (named) parameters are SQLite-only; portable SQL uses
+  positional `?` parameters.
+
+### Added
+
+- PostgreSQL backend via `asyncpg` (`pip install 'pyxle-db[postgres]'`)
+  and MySQL backend via `asyncmy` (`pip install 'pyxle-db[mysql]'`).
+  The base install remains SQLite-only with zero extra dependencies.
+- Database URLs: `Database(...)`/`connect(...)` accept
+  `sqlite:///...`, `postgresql://...`, and `mysql://...` connection
+  strings alongside the 0.1 bare SQLite path. `DatabaseConfig` and
+  `parse_database_url` are exported for programmatic use.
+- Portable placeholders: qmark (`?`) SQL is translated per backend
+  (`$1` for PostgreSQL, `%s` for MySQL) with a literal-aware rewriter;
+  `??` escapes a literal question mark for PostgreSQL JSON operators.
+- Backend-neutral `Row` result type (index + name access) and `Dialect`
+  metadata, both exported from `pyxle_db`.
+- New error types: `OperationalError` (retryable connection/timeout
+  family), `ConfigurationError`, and `UnsupportedOperationError`.
+  Driver exceptions are translated on every backend — application code
+  never handles `sqlite3`/`asyncpg`/`asyncmy` exceptions.
+- Datetimes come back timezone-aware UTC on every backend; naive values
+  stored in the database are assumed UTC and tagged.
+- Plugin: new `url` setting that takes precedence over `path`, with
+  `env:VAR_NAME` indirection so credentials stay out of the committed
+  `pyxle.config.json` (startup raises `ConfigurationError` when the
+  variable is unset). The plugin now also registers `db.url`, a
+  password-redacted connection string for logging.
+- Migrations: backend-specific override files
+  (`0003-fulltext-index.postgresql.sql` next to
+  `0003-fulltext-index.sql`) for migrations that need per-dialect DDL.
+
+- `DatabaseLike` / `TransactionLike` protocols (`pyxle_db.contract`,
+  exported at top level): the structural contract third-party database
+  layers implement to back plugins like pyxle-auth. `Database` is the
+  reference implementation; both protocols are `runtime_checkable` and
+  the conformance is regression-tested.
+
+### Fixed
+
+- Plugin shutdown awaits `Database.aclose()`, releasing async pools
+  cleanly instead of relying on the SQLite-only synchronous close.
+- **Aware datetimes now bind on every backend** (found by the live-server
+  suites). PostgreSQL and MySQL pass parameters through
+  `utc_naive_params()`: an aware datetime is converted to UTC and bound
+  naive, matching the SQLite adapter and the read-side "naive equals
+  UTC" rule. Previously asyncpg rejected aware datetimes for `TIMESTAMP`
+  columns and asyncmy silently serialised the foreign wall clock.
+- The MySQL pool pins each session to UTC (`SET time_zone = '+00:00'`),
+  so `TIMESTAMP` columns and `NOW()` are no longer shifted through the
+  server's system time zone on read.
+- The `mysql` extra now includes `cryptography`: MySQL 8's default
+  `caching_sha2_password` auth fails at connect without it.
+- Dependency floor corrected to `pyxle-framework>=0.4.0` — the
+  `pyxle.plugins` API first shipped in 0.4.0, so older resolutions
+  could not import.
+
+## [0.1.0] - 2026-04-23
+
+### Added
+
+- Initial release: SQLite `Database` wrapper (thread-local connections,
+  WAL journaling, foreign-key and performance PRAGMAs), filesystem
+  `Migrator` with SHA-256 checksum tracking, `connect()` one-call setup,
+  and the `pyxle-db` plugin registering `db.database`/`db.path`.

pyxle_db-0.2.0/LICENSE

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

pyxle_db-0.2.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: pyxle-db
+Version: 0.2.0
+Summary: Database plugin for Pyxle: SQLite, PostgreSQL, and MySQL with one explicit-SQL API, portable qmark placeholders, and checksum-tracked migrations.
+Project-URL: Homepage, https://pyxle.dev
+Project-URL: Source, https://github.com/pyxle-dev/pyxle-plugins
+Project-URL: Changelog, https://github.com/pyxle-dev/pyxle-plugins/blob/main/packages/pyxle-db/CHANGELOG.md
+Author-email: Pyxle <dev@pyxle.dev>
+License: MIT
+License-File: LICENSE
+Keywords: database,migrations,mysql,postgresql,pyxle,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Requires-Dist: pyxle-framework>=0.4.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: mysql
+Requires-Dist: asyncmy>=0.2.9; extra == 'mysql'
+Requires-Dist: cryptography>=42; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# pyxle-db
+
+The official database plugin for [Pyxle](https://pyxle.dev). One explicit-SQL
+API over **SQLite**, **PostgreSQL**, and **MySQL** — no ORM, no query builder,
+Django-grade ergonomics for people who like writing SQL.
+
+- Write SQL once, in portable qmark style (`?` placeholders); pyxle-db
+  translates per backend with a literal-aware rewriter.
+- Every backend returns the same `Row` type, raises the same
+  `pyxle_db` error types, and hands back timezone-aware UTC datetimes —
+  application code never imports `sqlite3`, `asyncpg`, or `asyncmy`.
+- Filesystem migrations with SHA-256 checksum tracking, applied atomically.
+- First-class Pyxle plugin: one entry in `pyxle.config.json` and your app
+  has an open database at startup.
+
+## Install
+
+```bash
+pip install pyxle-db               # SQLite — zero extra dependencies
+pip install 'pyxle-db[postgres]'   # + asyncpg
+pip install 'pyxle-db[mysql]'      # + asyncmy
+```
+
+## Quickstart
+
+Same code on every backend — only the connection string changes.
+
+```python
+from pyxle_db import connect
+
+# SQLite (a bare path, exactly like 0.1)
+db = await connect("./data/app.db", migrations_dir="migrations")
+
+# PostgreSQL
+db = await connect("postgresql://app:s3cret@localhost/app")
+
+# MySQL
+db = await connect("mysql://app:s3cret@localhost/app")
+
+await db.execute(
+    "INSERT INTO users (id, email) VALUES (?, ?)", (user_id, email)
+)
+
+row = await db.fetchone("SELECT email, created_at FROM users WHERE id = ?", (user_id,))
+row["email"]        # name access
+row[0]              # index access
+row["created_at"]   # timezone-aware UTC datetime, on every backend
+
+user = await db.get("SELECT * FROM users WHERE id = ?", (user_id,))  # raises NotFoundError if absent
+
+await db.aclose()
+```
+
+Constraint violations raise `pyxle_db.IntegrityError`; unreachable/timed-out
+databases raise `pyxle_db.OperationalError` (the retryable family); everything
+else is a `pyxle_db.DatabaseError` subclass. Driver exceptions never leak.
+
+## Database URLs
+
+`Database(...)`, `connect(...)`, and the plugin's `url` setting all accept:
+
+| Form | Opens |
+|------|-------|
+| `./data/app.db` (no scheme) | SQLite at that path — 0.1-compatible |
+| `sqlite:///relative/path.db` | SQLite, path relative to the working directory |
+| `sqlite:////absolute/path.db` | SQLite, absolute path |
+| `sqlite:///:memory:` | SQLite, in-memory |
+| `postgresql://user:pass@host:5432/dbname?sslmode=require` | PostgreSQL (`postgres://` also accepted) |
+| `mysql://user:pass@host:3306/dbname` | MySQL (`mariadb://` also accepted) |
+
+Ports default to 5432/3306. Query-string options (e.g. `sslmode`) pass
+through to the driver. Credentials are percent-decoded, so encode special
+characters (`p@ss` → `p%40ss`).
+
+## Placeholders
+
+Always write `?`. pyxle-db rewrites it to the backend's native style —
+`?` for SQLite, `$1`/`$2` for PostgreSQL, `%s` for MySQL.
+
+When you need a *literal* question mark — PostgreSQL's JSON operators —
+escape it as `??`:
+
+```python
+await db.fetchall(
+    "SELECT id FROM events WHERE payload ?? 'user_id' AND kind = ?",
+    ("signup",),
+)
+# asyncpg receives: SELECT id FROM events WHERE payload ? 'user_id' AND kind = $1
+```
+
+The rewriter is literal-aware: `?` inside string literals, quoted
+identifiers, comments, and dollar-quoted bodies is never touched, so user
+data can't become SQL structure during translation.
+
+## Writing portable schemas
+
+Rules proven against real PostgreSQL and MySQL servers (the live suites
+in `tests/` enforce them):
+
+- **`VARCHAR(n)` for every key or indexed column.** MySQL cannot index
+  bare `TEXT` (error 1170). SQLite and PostgreSQL treat `VARCHAR` as
+  `TEXT`, so nothing is lost. Keep `TEXT` for payloads.
+- **Datetimes: bind anything, read aware UTC.** Columns store UTC wall
+  time. You may bind naive datetimes (assumed UTC) or aware ones (the
+  backend converts to UTC before binding); every read comes back as an
+  aware-UTC `datetime` on all three engines.
+- **`TIMESTAMP` columns are fine on SQLite and PostgreSQL.** On MySQL
+  prefer `DATETIME(6)` via a per-dialect migration override
+  (`0002-x.mysql.sql`): MySQL's `TIMESTAMP` is capped at 2038 and rounds
+  to whole seconds. (The backend pins each session to UTC, so even
+  `TIMESTAMP` columns read back correct instants.)
+- **MySQL has no `CREATE INDEX IF NOT EXISTS`.** Create indexes in
+  migrations (they run exactly once, checksum-tracked) or probe
+  `information_schema.statistics` before creating.
+- **Spell out inserted values instead of relying on column `DEFAULT`s**,
+  which drift subtly between engines.
+
+## Transactions
+
+```python
+async with db.transaction() as tx:
+    await tx.execute("UPDATE accounts SET balance = balance - ? WHERE id = ?", (amount, src))
+    await tx.execute("UPDATE accounts SET balance = balance + ? WHERE id = ?", (amount, dst))
+```
+
+Commits on exit, rolls back on exception. Concurrent transactions never
+interleave statements on the same connection.
+
+**SQLite only:** synchronous scripts and tests can use
+`with db.sync_transaction() as tx: ...` and `db.close()`. Server backends
+hold async pools, so both raise `UnsupportedOperationError` there — use
+`async with db.transaction()` and `await db.aclose()`.
+
+## Migrations
+
+Each migration is a `.sql` file named `<NNNN>-<slug>.sql` in your
+migrations directory:
+
+```
+migrations/
+  0001-initial-schema.sql
+  0002-add-sessions.sql
+  0003-fulltext-index.sql
+  0003-fulltext-index.postgresql.sql   # backend-specific override
+```
+
+- The numeric prefix is the canonical order; two files may not share one.
+- A dialect-suffixed file (`.sqlite.sql`, `.postgresql.sql`, `.mysql.sql`)
+  replaces the base file on that backend — for the rare migration that
+  genuinely needs backend-specific DDL.
+- Each migration runs in its own transaction and is applied exactly once
+  per database, recorded in `schema_migrations` with the file's SHA-256.
+- **Checksum policy:** every startup re-hashes applied migrations. An
+  edited file raises `MigrationChecksumMismatch`; a deleted one raises
+  `MigrationError`. Once applied anywhere, a migration is immutable —
+  write a follow-up migration instead.
+
+Apply on startup via `connect(..., migrations_dir="migrations")`, the
+plugin's `migrationsDir` setting, or explicitly:
+
+```python
+from pathlib import Path
+from pyxle_db import Migrator
+
+await Migrator(db, Path("migrations")).apply_all()
+```
+
+## Using it as a Pyxle plugin
+
+```json
+{
+  "plugins": [
+    {
+      "name": "pyxle-db",
+      "settings": {
+        "url": "env:DATABASE_URL",
+        "migrationsDir": "migrations"
+      }
+    }
+  ]
+}
+```
+
+Settings (all optional):
+
+| Key | Meaning | Default |
+|-----|---------|---------|
+| `url` | Database URL; wins over `path`. The `env:VAR` form resolves the named environment variable at startup — keep secrets out of the committed config. Startup fails with `ConfigurationError` if the variable is unset. | — |
+| `path` | SQLite path, resolved against the project root | `./data/app.db` |
+| `migrationsDir` | Migrations directory, applied at startup if it exists | `migrations` |
+| `waitForFileMs` | Poll this long for a SQLite file being created by another process | `0` |
+
+Registered services: `db.database` (the open `Database`), `db.url`
+(password-redacted connection string for logging), and — SQLite only —
+`db.path` (the resolved file path, kept for 0.1 consumers).
+
+In loaders and actions, skip the service registry boilerplate:
+
+```python
+from pyxle_db import get_database
+
+@server
+async def load(request):
+    db = get_database()
+    return {"posts": await db.fetchall("SELECT * FROM posts ORDER BY id DESC")}
+```
+
+## Upgrading from 0.1
+
+> **Breaking changes in 0.2**
+>
+> - Transaction methods are now coroutines. `async with db.transaction()
+>   as tx:` then `await tx.execute(...)` / `await tx.fetchone(...)` —
+>   0.1's sync calls inside the async block no longer work.
+> - `db.close()` and `db.sync_transaction()` are now SQLite-only and raise
+>   `UnsupportedOperationError` on PostgreSQL/MySQL. Prefer
+>   `await db.aclose()` everywhere — it works on every backend.
+> - Mapping (named) parameters are SQLite-only; portable SQL uses
+>   positional `?` parameters.
+>
+> Everything else is additive: bare SQLite paths, the migration format,
+> and the plugin settings from 0.1 keep working unchanged.
+
+## Roadmap
+
+Short list, subject to change: pool-size tuning options for server
+backends, streaming fetches for large result sets, and `pyxle db` CLI
+commands for migration status/creation. Issues and PRs welcome.
+
+## License
+
+MIT.

pyxle_db-0.2.0/README.md

@@ -0,0 +1,232 @@
+# pyxle-db
+
+The official database plugin for [Pyxle](https://pyxle.dev). One explicit-SQL
+API over **SQLite**, **PostgreSQL**, and **MySQL** — no ORM, no query builder,
+Django-grade ergonomics for people who like writing SQL.
+
+- Write SQL once, in portable qmark style (`?` placeholders); pyxle-db
+  translates per backend with a literal-aware rewriter.
+- Every backend returns the same `Row` type, raises the same
+  `pyxle_db` error types, and hands back timezone-aware UTC datetimes —
+  application code never imports `sqlite3`, `asyncpg`, or `asyncmy`.
+- Filesystem migrations with SHA-256 checksum tracking, applied atomically.
+- First-class Pyxle plugin: one entry in `pyxle.config.json` and your app
+  has an open database at startup.
+
+## Install
+
+```bash
+pip install pyxle-db               # SQLite — zero extra dependencies
+pip install 'pyxle-db[postgres]'   # + asyncpg
+pip install 'pyxle-db[mysql]'      # + asyncmy
+```
+
+## Quickstart
+
+Same code on every backend — only the connection string changes.
+
+```python
+from pyxle_db import connect
+
+# SQLite (a bare path, exactly like 0.1)
+db = await connect("./data/app.db", migrations_dir="migrations")
+
+# PostgreSQL
+db = await connect("postgresql://app:s3cret@localhost/app")
+
+# MySQL
+db = await connect("mysql://app:s3cret@localhost/app")
+
+await db.execute(
+    "INSERT INTO users (id, email) VALUES (?, ?)", (user_id, email)
+)
+
+row = await db.fetchone("SELECT email, created_at FROM users WHERE id = ?", (user_id,))
+row["email"]        # name access
+row[0]              # index access
+row["created_at"]   # timezone-aware UTC datetime, on every backend
+
+user = await db.get("SELECT * FROM users WHERE id = ?", (user_id,))  # raises NotFoundError if absent
+
+await db.aclose()
+```
+
+Constraint violations raise `pyxle_db.IntegrityError`; unreachable/timed-out
+databases raise `pyxle_db.OperationalError` (the retryable family); everything
+else is a `pyxle_db.DatabaseError` subclass. Driver exceptions never leak.
+
+## Database URLs
+
+`Database(...)`, `connect(...)`, and the plugin's `url` setting all accept:
+
+| Form | Opens |
+|------|-------|
+| `./data/app.db` (no scheme) | SQLite at that path — 0.1-compatible |
+| `sqlite:///relative/path.db` | SQLite, path relative to the working directory |
+| `sqlite:////absolute/path.db` | SQLite, absolute path |
+| `sqlite:///:memory:` | SQLite, in-memory |
+| `postgresql://user:pass@host:5432/dbname?sslmode=require` | PostgreSQL (`postgres://` also accepted) |
+| `mysql://user:pass@host:3306/dbname` | MySQL (`mariadb://` also accepted) |
+
+Ports default to 5432/3306. Query-string options (e.g. `sslmode`) pass
+through to the driver. Credentials are percent-decoded, so encode special
+characters (`p@ss` → `p%40ss`).
+
+## Placeholders
+
+Always write `?`. pyxle-db rewrites it to the backend's native style —
+`?` for SQLite, `$1`/`$2` for PostgreSQL, `%s` for MySQL.
+
+When you need a *literal* question mark — PostgreSQL's JSON operators —
+escape it as `??`:
+
+```python
+await db.fetchall(
+    "SELECT id FROM events WHERE payload ?? 'user_id' AND kind = ?",
+    ("signup",),
+)
+# asyncpg receives: SELECT id FROM events WHERE payload ? 'user_id' AND kind = $1
+```
+
+The rewriter is literal-aware: `?` inside string literals, quoted
+identifiers, comments, and dollar-quoted bodies is never touched, so user
+data can't become SQL structure during translation.
+
+## Writing portable schemas
+
+Rules proven against real PostgreSQL and MySQL servers (the live suites
+in `tests/` enforce them):
+
+- **`VARCHAR(n)` for every key or indexed column.** MySQL cannot index
+  bare `TEXT` (error 1170). SQLite and PostgreSQL treat `VARCHAR` as
+  `TEXT`, so nothing is lost. Keep `TEXT` for payloads.
+- **Datetimes: bind anything, read aware UTC.** Columns store UTC wall
+  time. You may bind naive datetimes (assumed UTC) or aware ones (the
+  backend converts to UTC before binding); every read comes back as an
+  aware-UTC `datetime` on all three engines.
+- **`TIMESTAMP` columns are fine on SQLite and PostgreSQL.** On MySQL
+  prefer `DATETIME(6)` via a per-dialect migration override
+  (`0002-x.mysql.sql`): MySQL's `TIMESTAMP` is capped at 2038 and rounds
+  to whole seconds. (The backend pins each session to UTC, so even
+  `TIMESTAMP` columns read back correct instants.)
+- **MySQL has no `CREATE INDEX IF NOT EXISTS`.** Create indexes in
+  migrations (they run exactly once, checksum-tracked) or probe
+  `information_schema.statistics` before creating.
+- **Spell out inserted values instead of relying on column `DEFAULT`s**,
+  which drift subtly between engines.
+
+## Transactions
+
+```python
+async with db.transaction() as tx:
+    await tx.execute("UPDATE accounts SET balance = balance - ? WHERE id = ?", (amount, src))
+    await tx.execute("UPDATE accounts SET balance = balance + ? WHERE id = ?", (amount, dst))
+```
+
+Commits on exit, rolls back on exception. Concurrent transactions never
+interleave statements on the same connection.
+
+**SQLite only:** synchronous scripts and tests can use
+`with db.sync_transaction() as tx: ...` and `db.close()`. Server backends
+hold async pools, so both raise `UnsupportedOperationError` there — use
+`async with db.transaction()` and `await db.aclose()`.
+
+## Migrations
+
+Each migration is a `.sql` file named `<NNNN>-<slug>.sql` in your
+migrations directory:
+
+```
+migrations/
+  0001-initial-schema.sql
+  0002-add-sessions.sql
+  0003-fulltext-index.sql
+  0003-fulltext-index.postgresql.sql   # backend-specific override
+```
+
+- The numeric prefix is the canonical order; two files may not share one.
+- A dialect-suffixed file (`.sqlite.sql`, `.postgresql.sql`, `.mysql.sql`)
+  replaces the base file on that backend — for the rare migration that
+  genuinely needs backend-specific DDL.
+- Each migration runs in its own transaction and is applied exactly once
+  per database, recorded in `schema_migrations` with the file's SHA-256.
+- **Checksum policy:** every startup re-hashes applied migrations. An
+  edited file raises `MigrationChecksumMismatch`; a deleted one raises
+  `MigrationError`. Once applied anywhere, a migration is immutable —
+  write a follow-up migration instead.
+
+Apply on startup via `connect(..., migrations_dir="migrations")`, the
+plugin's `migrationsDir` setting, or explicitly:
+
+```python
+from pathlib import Path
+from pyxle_db import Migrator
+
+await Migrator(db, Path("migrations")).apply_all()
+```
+
+## Using it as a Pyxle plugin
+
+```json
+{
+  "plugins": [
+    {
+      "name": "pyxle-db",
+      "settings": {
+        "url": "env:DATABASE_URL",
+        "migrationsDir": "migrations"
+      }
+    }
+  ]
+}
+```
+
+Settings (all optional):
+
+| Key | Meaning | Default |
+|-----|---------|---------|
+| `url` | Database URL; wins over `path`. The `env:VAR` form resolves the named environment variable at startup — keep secrets out of the committed config. Startup fails with `ConfigurationError` if the variable is unset. | — |
+| `path` | SQLite path, resolved against the project root | `./data/app.db` |
+| `migrationsDir` | Migrations directory, applied at startup if it exists | `migrations` |
+| `waitForFileMs` | Poll this long for a SQLite file being created by another process | `0` |
+
+Registered services: `db.database` (the open `Database`), `db.url`
+(password-redacted connection string for logging), and — SQLite only —
+`db.path` (the resolved file path, kept for 0.1 consumers).
+
+In loaders and actions, skip the service registry boilerplate:
+
+```python
+from pyxle_db import get_database
+
+@server
+async def load(request):
+    db = get_database()
+    return {"posts": await db.fetchall("SELECT * FROM posts ORDER BY id DESC")}
+```
+
+## Upgrading from 0.1
+
+> **Breaking changes in 0.2**
+>
+> - Transaction methods are now coroutines. `async with db.transaction()
+>   as tx:` then `await tx.execute(...)` / `await tx.fetchone(...)` —
+>   0.1's sync calls inside the async block no longer work.
+> - `db.close()` and `db.sync_transaction()` are now SQLite-only and raise
+>   `UnsupportedOperationError` on PostgreSQL/MySQL. Prefer
+>   `await db.aclose()` everywhere — it works on every backend.
+> - Mapping (named) parameters are SQLite-only; portable SQL uses
+>   positional `?` parameters.
+>
+> Everything else is additive: bare SQLite paths, the migration format,
+> and the plugin settings from 0.1 keep working unchanged.
+
+## Roadmap
+
+Short list, subject to change: pool-size tuning options for server
+backends, streaming fetches for large result sets, and `pyxle db` CLI
+commands for migration status/creation. Issues and PRs welcome.
+
+## License
+
+MIT.

pyxle_db-0.2.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling>=1.25,<2.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyxle-db"
+version = "0.2.0"
+description = "Database plugin for Pyxle: SQLite, PostgreSQL, and MySQL with one explicit-SQL API, portable qmark placeholders, and checksum-tracked migrations."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Pyxle", email = "dev@pyxle.dev" },
+]
+keywords = ["pyxle", "sqlite", "postgresql", "mysql", "database", "migrations"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: AsyncIO",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Database",
+]
+dependencies = [
+  "pyxle-framework>=0.4.0",
+]
+
+[project.optional-dependencies]
+postgres = [
+  "asyncpg>=0.29",
+]
+mysql = [
+  "asyncmy>=0.2.9",
+  # MySQL 8's default caching_sha2_password auth needs this at connect time;
+  # without it every modern server greets users with a RuntimeError.
+  "cryptography>=42",
+]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+]
+
+[project.urls]
+Homepage = "https://pyxle.dev"
+Source = "https://github.com/pyxle-dev/pyxle-plugins"
+Changelog = "https://github.com/pyxle-dev/pyxle-plugins/blob/main/packages/pyxle-db/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pyxle_db"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]