sqlalchemy-monetdb-adbc 0.1.0__tar.gz

sqlalchemy_monetdb_adbc-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+*.bat text eol=crlf

sqlalchemy_monetdb_adbc-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        patterns: ["*"]

sqlalchemy_monetdb_adbc-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,167 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked --all-groups
+      - run: uv run --no-sync ruff check .
+      - run: uv run --no-sync ruff format --check .
+      - run: uv run --no-sync pyright
+      - run: uv run --no-sync pytest
+
+  platform:
+    name: Platform (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-14, windows-latest]
+        python-version: ["3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked --all-groups
+      - run: uv run --no-sync pytest
+
+  integration:
+    name: Integration (MonetDB ${{ matrix.monetdb-version }})
+    runs-on: ubuntu-24.04-arm
+    strategy:
+      fail-fast: false
+      matrix:
+        monetdb-version: ["11.55.7-2"]
+    services:
+      monetdb:
+        image: wlaur/monetdb-container:${{ matrix.monetdb-version }}@sha256:22dd41bd10fd7136ca1ef6afaec5cf0c1670f16a84b80785a5fee12aac480eb4
+        ports:
+          - 50000:50000
+        env:
+          MDB_DB_ADMIN_PASS: monetdb
+          MDB_CREATE_DBS: test
+    env:
+      MONETDB_TEST_URI: monetdb://monetdb:monetdb@localhost:50000/test
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: "3.13"
+      - run: uv sync --locked --all-groups
+      - name: Wait for MonetDB
+        run: |
+          for _ in $(seq 1 60); do
+            if uv run --no-sync python -c "
+          from adbc_driver_monetdb import dbapi
+          dbapi.connect('$MONETDB_TEST_URI').close()
+          "; then exit 0; fi
+            sleep 2
+          done
+          echo "MonetDB did not become ready" >&2
+          exit 1
+      - name: Integration tests
+        run: uv run --no-sync pytest tests -m integration
+      - name: SQLAlchemy dialect compliance suite
+        run: |
+          uv run --no-sync pytest suite -o addopts="" \
+            --dburi "$MONETDB_TEST_URI"
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: "3.13"
+      - name: Build and validate the release artifact set
+        shell: bash
+        run: |
+          uv build --out-dir dist
+          python packaging/release_checks.py artifacts dist --version "$(uv version --short)"
+      - name: Smoke-test wheel
+        shell: bash
+        run: |
+          wheel=$(find dist -maxdepth 1 -name '*.whl' -print -quit)
+          wheel=$(realpath "$wheel")
+          cd "$RUNNER_TEMP"
+          uv run --isolated --no-project --python 3.13 --with "$wheel" \
+            python -c "from sqlalchemy.dialects import registry; from sqlalchemy_monetdb_adbc.constants import DIALECT_NAMES; assert all(registry.load(name).name == 'monetdb' for name in DIALECT_NAMES)"
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: [test, platform, integration, build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/sqlalchemy-monetdb-adbc/
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist
+      - name: Verify protected-main provenance and release artifacts
+        run: |
+          git fetch origin main --no-tags
+          python packaging/release_checks.py provenance \
+            --tag "$GITHUB_REF_NAME" --commit "$GITHUB_SHA" --main-ref origin/main
+          python packaging/release_checks.py artifacts dist --version "${GITHUB_REF_NAME#v}"
+      - uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+
+  github-release:
+    name: Create GitHub release
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist
+      - name: Create release with checksums and generated notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          cd dist
+          sha256sum sqlalchemy_monetdb_adbc-* > SHA256SUMS
+          gh release create "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" \
+            --verify-tag --generate-notes \
+            sqlalchemy_monetdb_adbc-* SHA256SUMS

sqlalchemy_monetdb_adbc-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.coverage
+htmlcov/
+
+.DS_Store
+.idea/
+.vscode/

sqlalchemy_monetdb_adbc-0.1.0/AGENTS.md

@@ -0,0 +1,47 @@
+# Working on sqlalchemy-monetdb-adbc
+
+This repository provides the SQLAlchemy dialect for `adbc-driver-monetdb`. It is a
+pure-Python integration package: native protocol and Arrow behavior belong in the
+driver, while SQLAlchemy compilation, connection adaptation, and reflection belong
+here.
+
+## Python
+
+- Support Python 3.13 and newer.
+- Use `uv` only, never `pip`, and commit `uv.lock`.
+- Use full typing. Strict pyright, Ruff check/format, and pytest must pass.
+- Do not add `pymonetdb` or `sqlalchemy-monetdb` as runtime dependencies.
+- Do not add unnecessary comments, docstrings, or compatibility fallbacks.
+
+## Connection and transaction boundaries
+
+- `monetdb://`, `monetdb+adbc://`, `monetdbs://`, and `monetdbs+adbc://` must
+  create one ADBC DBAPI connection per SQLAlchemy connection. The secure schemes must
+  remain secure when translated to driver URIs.
+- DDL, SQL execution, Arrow reads, and `adbc_ingest` participating in one unit of work
+  must use that same physical connection. Do not introduce a second MonetDB session.
+- Preserve SQLAlchemy's transaction contract while exposing a documented way to reach
+  the raw ADBC connection for Arrow-native operations.
+- The driver owns ADBC behavior and MonetDB wire semantics. Do not duplicate or patch
+  those layers in this package.
+
+## Testing
+
+- Unit gates: `uv run ruff check .`, `uv run ruff format --check .`,
+  `uv run pyright`, and `uv run pytest`.
+- Integration tests use the pinned native ARM64 MonetDB image documented by
+  `adbc-driver-monetdb` and skip when no test URI is configured.
+- Add regression tests for transaction ownership before changing connection or pool
+  behavior.
+
+## Packaging
+
+- The distribution is `sqlalchemy-monetdb-adbc`, the import package is
+  `sqlalchemy_monetdb_adbc`, and the SQLAlchemy entry points are `monetdb`,
+  `monetdb.adbc`, `monetdbs`, and `monetdbs.adbc`.
+- Do not install this package alongside `sqlalchemy-monetdb`; both distributions
+  register the bare `monetdb` entry point.
+- Build both wheel and sdist with `uv build` and smoke-test the built wheel outside the
+  repository before release.
+- Keep the public repository self-contained. Do not commit private planning notes,
+  benchmark results, credentials, or local infrastructure details.

sqlalchemy_monetdb_adbc-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Create a branch from `main`, keep changes focused, and include tests for behavior
+changes.
+
+Set up the environment and run every local gate:
+
+```console
+uv sync --all-groups
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv run pytest
+uv build
+```
+
+Integration work must use the MonetDB image and connection rules documented in
+`AGENTS.md`. Do not run live tests against an unrelated development container.
+
+## Review matrix
+
+A passing happy-path test is not evidence for adjacent states. Reflection work
+must cover `schema=None`, explicit and missing schemas; absent, empty and
+non-empty filters; default, temporary and combined scopes; permanent/temporary
+name collisions; and same-schema, cross-schema and self-referential foreign
+keys.
+
+Connection work must cover the default transaction mode and autocommit,
+commit, rollback and pool reset, complete and partial result consumption, and
+raw ADBC operations sharing the SQLAlchemy session. Packaging changes must
+exercise every declared dialect entry point from the built wheel outside the
+checkout.
+
+Treat test names, documentation claims, support metadata and repository
+settings as assertions that need executable gates. A dependency release must
+be available from its public registry before this lockfile adopts it, and the
+driver must run this dialect against its candidate wheel before publishing.

sqlalchemy_monetdb_adbc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Laurén
+
+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_monetdb_adbc-0.1.0/PKG-INFO

@@ -0,0 +1,349 @@
+Metadata-Version: 2.4
+Name: sqlalchemy-monetdb-adbc
+Version: 0.1.0
+Summary: SQLAlchemy dialect for MonetDB over ADBC
+Project-URL: Homepage, https://github.com/wlaur/sqlalchemy-monetdb-adbc
+Project-URL: Repository, https://github.com/wlaur/sqlalchemy-monetdb-adbc
+Project-URL: Issues, https://github.com/wlaur/sqlalchemy-monetdb-adbc/issues
+Author-email: William Laurén <lauren.william.a@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adbc,arrow,database,dialect,monetdb,sqlalchemy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: adbc-driver-manager>=1.11
+Requires-Dist: adbc-driver-monetdb>=0.8.5
+Requires-Dist: numpy>=2.1
+Requires-Dist: pyarrow>=25
+Requires-Dist: pydantic>=2
+Requires-Dist: sqlalchemy>=2.0.34
+Requires-Dist: tzdata>=2025.2; sys_platform == 'win32'
+Description-Content-Type: text/markdown
+
+# sqlalchemy-monetdb-adbc
+
+A SQLAlchemy dialect for MonetDB backed by
+[`adbc-driver-monetdb`](https://github.com/wlaur/adbc-driver-monetdb).
+
+The package is pure Python. It gives SQLAlchemy and Arrow-native ADBC operations a
+single MonetDB connection and transaction boundary, without depending on `pymonetdb`
+or `sqlalchemy-monetdb`.
+
+## Status
+
+The dialect covers SQL compilation, types, reflection, transactions, and the ORM,
+and is validated against a live MonetDB server.
+
+### Dialect compliance suite
+
+SQLAlchemy's own dialect suite runs from `suite/` (see Development) and reports
+no failures: 1237 passed, 16 xfailed, 388 skipped. Each xfail is a MonetDB or
+driver limitation, listed with its reason in `suite/known_failures.py`. They are
+marked xfail rather than skipped so that the tests still run, and report XPASS
+if a future release gains the behaviour:
+
+- MonetDB infers no type for a bare parameter, so `WHERE ? = ?` is rejected
+  outright. A cast resolves it, but SQLAlchemy emits the parameter alone. This
+  is most of the remainder.
+- Untyped parameters also change arithmetic: `SELECT ? / ?` with `(15, 10)`
+  returns `1`, not `1.5`, and dividing an untyped parameter by a decimal is
+  read as interval arithmetic.
+- No lastrowid, which is why generated values come back through `RETURNING`.
+- `RETURNING *` needs an explicit column list.
+- JSON is normalized on input, so a document does not round-trip byte for byte.
+- Some identifiers legal elsewhere are rejected, such as one containing `%`.
+
+Common table expressions are fully supported, including recursive CTEs, CTEs
+over `VALUES`, and CTEs driving `UPDATE`/`DELETE`. MonetDB's `WITH` accepts only
+`SELECT` or `VALUES`, so a CTE cannot itself be an `INSERT`/`UPDATE`/`DELETE`.
+
+Regular expression matching is not available: MonetDB's `~` is `mbr_contains`,
+a geometry operator, so `regexp_match()` raises rather than producing SQL that
+means something else. `regexp_replace()` works.
+
+The dialect requires `adbc-driver-monetdb` 0.8.5 or newer, which reports
+truthful row counts, exports the PEP 249 `Binary` constructor, caches
+prepared statements per connection, executes one-row bound DML without a
+savepoint, and returns small results from MonetDB's initial reply. One
+`DRIVER-WORKAROUND` remains in the source for upstream Apache arrow-adbc
+behavior: ADBC always returns an Arrow stream, so the DB-API layer reports an
+empty `description` rather than `None` for statements that produce no result
+set, and SQLAlchemy needs `None` to decide that a statement returned no rows.
+
+### MonetDB behaviors worth knowing
+
+- A stock login lands in the `sys` schema, where system views already occupy
+  ordinary table names such as `users` and `columns`. Create and use a schema of
+  your own.
+- Self-referential foreign keys are added by `ALTER TABLE` after the table
+  exists, because MonetDB cannot declare them inline. MonetDB then enforces
+  them one statement at a time rather than at statement end, so on such a table
+  `DELETE FROM t` and `TRUNCATE t` are both rejected, and a multi-row `INSERT`
+  cannot reference a row added by the same statement. Declare the foreign key
+  with `ondelete="CASCADE"` if you need bulk deletes, or clear the referencing
+  column first:
+
+  ```python
+  connection.execute(update(tree).values(parent_id=None))
+  connection.execute(delete(tree))
+  ```
+- Indexes carry no ordering, so `ASC`/`DESC` on an index expression is dropped.
+- MonetDB rejects the all-zero (nil) UUID, `00000000-0000-0000-0000-000000000000`,
+  even as a plain literal, because it uses that value as its internal `NULL` for
+  the `uuid` type. A `Uuid` column therefore cannot store `uuid.UUID(int=0)`.
+- A `DECIMAL` declared without precision means `DECIMAL(18, 3)`. The dialect
+  always renders that explicitly: MonetDB drops the connection when a
+  *parameter* is cast to an unsized `DECIMAL`, which is what SQLAlchemy emits
+  for true division.
+- A `Numeric` column accepts `float`, `int` and `Decimal` in the same
+  `executemany`. ADBC would otherwise take the column's Arrow type from the
+  first value and reject the rest, so the dialect normalises the column first.
+- A `UNIQUE` constraint is backed by an index of the same name, so it is
+  reflected both by `get_unique_constraints()` and by `get_indexes()`.
+
+## Installation
+
+```console
+uv add sqlalchemy-monetdb-adbc
+```
+
+Or with Python's standard package installer:
+
+```console
+python -m pip install sqlalchemy-monetdb-adbc
+```
+
+## Usage
+
+Existing SQLAlchemy MonetDB URLs work unchanged:
+
+```python
+from sqlalchemy import create_engine
+
+engine = create_engine(
+    "monetdb://monetdb:monetdb@localhost:50000/demo",
+)
+
+with engine.connect() as connection:
+    rows = connection.exec_driver_sql("SELECT 1").all()
+```
+
+The explicit `monetdb+adbc://` form resolves to the same dialect. Do not install
+`sqlalchemy-monetdb-adbc` and `sqlalchemy-monetdb` in the same environment: both
+packages register the bare `monetdb://` SQLAlchemy entry point.
+
+TLS URLs work with either the unchanged `monetdbs://` form or the explicit
+`monetdbs+adbc://` form. Both preserve the secure driver URI.
+
+The driver accepts the same URI query options after the database name:
+
+```python
+engine = create_engine(
+    "monetdb://monetdb:monetdb@localhost:50000/demo?client_application=my_app",
+)
+```
+
+## Arrow and polars
+
+Rows are converted to Python objects only if you ask for them, and that
+conversion is done a column at a time through numpy rather than element by
+element. Ordinary row-returning queries with meaningful result sizes avoid
+per-cell Arrow scalar boxing.
+
+Driver 0.8.5 removes the avoidable fixed costs found in the release review:
+one-row parameterized DML no longer adds a savepoint pair, and results of up to
+100 rows no longer force a second fetch. The driver also batches `executemany`
+parameters into one multi-row statement when MonetDB can preserve the DB-API
+semantics. Tiny row-oriented SELECTs still carry the fixed cost of receiving a
+canonical Arrow stream across the native boundary; use the Arrow helpers below
+when keeping the result columnar matters.
+
+To skip the conversion entirely and keep data columnar, run the query on the
+same connection and take Arrow back:
+
+```python
+from sqlalchemy_monetdb_adbc import fetch_arrow_table, fetch_record_batches, ingest_arrow
+
+statement = select(trades.c.id, trades.c.symbol).where(trades.c.symbol == "AAPL")
+
+with Session(engine) as session:
+    table = fetch_arrow_table(session.connection(), statement)  # pyarrow.Table
+    frame = polars.from_arrow(table)
+
+    # streaming, for results that should not be materialized at once
+    with fetch_record_batches(session.connection(), statement) as reader:
+        for batch in reader:
+            ...
+
+    ingest_arrow(session.connection(), "trades", table, mode="append")
+```
+
+These run on the ADBC session backing the SQLAlchemy connection, so they see
+that connection's uncommitted work, take part in its transaction, and roll back
+with it. Use them rather than opening a second connection with
+`polars.read_database`, which would be a separate session and transaction.
+
+A SQLAlchemy statement is compiled for you, bind parameters included; a plain
+SQL string works too. `raw_adbc_connection()` returns the underlying ADBC
+connection if you need the driver API directly.
+
+The driver prefetches large results by default. Closing a partially consumed
+result—such as calling `.first()`—waits briefly and then lets an in-flight fetch
+finish without killing the pooled session. The next statement on that
+connection can wait for that fetch or its configured timeout. Set
+`read_prefetch=false` in the connection URI when prompt pool reuse matters more
+than fetch/decode overlap:
+
+```python
+engine = create_engine("monetdb://localhost/demo?read_prefetch=false")
+```
+
+## JSON
+
+A `JSON` column round-trips Python objects, as SQLAlchemy specifies: the driver
+returns the document as a string and SQLAlchemy deserializes it, honouring
+`json_serializer` and `json_deserializer` on `create_engine`.
+
+```python
+engine = create_engine("monetdb://...", json_deserializer=orjson.loads)
+```
+
+MonetDB validates and normalizes JSON on input, so a round-tripped document
+keeps its values but not its original whitespace or key order.
+
+Path indexing works as on other backends, including nested keys, array indexes
+and the `as_string()`/`as_integer()` accessors. A path that matches nothing
+returns `None`:
+
+```python
+select(t.c.doc["title"])  # 'hello'
+select(t.c.doc[("sub", "k")])  # 'v'
+select(t.c.doc[("arr", 1)])  # 20
+select(t.c.doc["missing"])  # None
+```
+
+Whatever Python object you store is serialized, and you get that same object
+back. Note that a `str` is itself a valid JSON value, so passing pre-serialized
+text to a `JSON` column stores a JSON *string*, not an object:
+
+```python
+connection.execute(insert(t), [{"payload": {"a": 1}}])  # stored as {"a":1}
+connection.execute(insert(t), [{"payload": '{"a": 1}'}])  # stored as "{\"a\": 1}"
+```
+
+This is SQLAlchemy's behavior on every backend, not a MonetDB quirk. To store
+JSON text you already hold, use a `Text` column, or a type that controls the
+codec as below.
+
+### Storing a Pydantic model
+
+`PydanticJSON` stores a Pydantic model in a MonetDB `JSON` column. The model is
+serialized straight to JSON text and parsed straight back with
+`model_validate_json`, so no intermediate `dict` is built in either direction:
+
+```python
+from pydantic import BaseModel, ConfigDict
+from sqlalchemy import Integer, select
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from sqlalchemy_monetdb_adbc import PydanticJSON
+
+
+class Content(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    title: str
+    views: int
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Article(Base):
+    __tablename__ = "article"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    content: Mapped[Content] = mapped_column(PydanticJSON(Content))
+```
+
+The attribute is the model itself, with no conversion at the call site:
+
+```python
+article: Article = session.scalars(select(Article)).one()
+article.content.title  # Content instance, never a dict
+```
+
+This avoids deserializing to an intermediate `dict` before validation. A plain
+`JSON` column cannot avoid the dict: by the time the attribute is read,
+SQLAlchemy has already deserialized and the original text is gone.
+
+#### Declare the model frozen
+
+As with any `JSON` column, SQLAlchemy does not track mutation *inside* the
+value, so an in-place edit is silently not persisted. Declaring the model
+`frozen=True`, as above, turns that silent loss into a `ValidationError`, and
+makes the model hashable. Persist a change by assigning a new value:
+
+```python
+article.content = article.content.model_copy(update={"views": 2})
+```
+
+Freezing is a property of your model, so the type cannot impose it; if you need
+mutation to be tracked instead, use `sqlalchemy.ext.mutable`.
+
+## Alembic
+
+Importing the dialect registers a MonetDB migration implementation, so Alembic
+works without further configuration. Schema operations, autogenerate, and
+`PydanticJSON` columns are covered by the test suite.
+
+No configuration is needed: importing the dialect, which `create_engine` does
+for you, registers the implementation. This works in offline mode too.
+
+Changing a column's type is supported. MonetDB spells it
+`ALTER TABLE t ALTER COLUMN c <type>`, without the `TYPE` keyword most backends
+use. It refuses to alter a column that other objects depend on, such as one
+carrying a primary key, and says so.
+
+A `PydanticJSON` column autogenerates as `sa.JSON()`, since a migration
+describes the database schema. Rendering the model instead would make
+migrations import application code and break as soon as that model moved.
+
+## Development
+
+Python 3.13 or newer and `uv` are required.
+
+```console
+uv sync --all-groups
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv run pytest
+uv build
+```
+
+Integration tests and the dialect compliance suite need a server. `compose.yaml`
+pins the same native ARM64 MonetDB image the driver is developed against:
+
+```console
+docker compose up --wait
+MONETDB_TEST_URI=monetdb://monetdb:monetdb@localhost:50001/test uv run pytest tests
+uv run pytest suite -o addopts=""
+docker compose down -v
+```
+
+`uv run pytest` alone skips every test that needs a server, so the unit gate
+runs without one.
+
+## License
+
+MIT