sqlalchemy-adbc 0.2.0__tar.gz → 0.3.0__tar.gz

sqlalchemy_adbc-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Ruff check
+        run: ruff check src/ tests/
+      - name: Ruff format
+        run: ruff format --check src/ tests/
+      - name: Mypy
+        run: mypy src tests
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Matrix tracks active Python versions only — 3.9 hit EOL in
+        # October 2025, so it's dropped. Bump when a new minor ships;
+        # drop when Python marks one end-of-life.
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    # Postgres service for integration tests (test_postgresql_types.py,
+    # issue #3). Gated by DRLS_PG_URL — tests skip when the env var is
+    # absent, so local `pytest` runs without a local PG also pass.
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U test"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      DRLS_PG_URL: "adbc+postgresql://test:test@localhost:5432/test"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev,postgresql]"
+      - name: Pytest
+        run: pytest tests/ --cov=sqlalchemy_adbc --cov-report=term-missing

{sqlalchemy_adbc-0.2.0 → sqlalchemy_adbc-0.3.0}/.github/workflows/publish.yml

@@ -87,3 +87,57 @@ jobs:
           name: dist
           path: dist/
       - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    # Creates a GitHub Release for every tag push, using the matching
+    # CHANGELOG.md section as the release body. Runs AFTER the PyPI
+    # publish succeeds so we don't advertise a version that failed
+    # to upload. No binary assets attached — PyPI is the distribution
+    # channel; duplicating wheels here invites drift.
+    name: Create GitHub Release
+    needs: publish-pypi
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Extract release notes from CHANGELOG
+        id: notes
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          # Grab the section under `## [X.Y.Z]` up to the next `## `
+          # heading (or EOF). `awk` keeps this portable across bash
+          # versions without depending on gh's CHANGELOG conventions.
+          NOTES=$(awk -v ver="$TAG" '
+            /^## \[/ {
+              if (found) exit
+              if ($0 ~ "\\[" ver "\\]") { found = 1; next }
+            }
+            found { print }
+          ' CHANGELOG.md)
+          if [ -z "$NOTES" ]; then
+            echo "::warning::No CHANGELOG entry found for version $TAG"
+            NOTES="Release v$TAG. See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details."
+          fi
+          # Append PyPI link so the Release page directs installers
+          # back to the canonical distribution.
+          NOTES="$NOTES
+
+          ---
+
+          📦 **Install:** \`pip install sqlalchemy-adbc==$TAG\` —
+          [view on PyPI](https://pypi.org/project/sqlalchemy-adbc/$TAG/)"
+          {
+            echo "notes<<EOF"
+            echo "$NOTES"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+      - name: Create Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          gh release create "v$TAG" \
+            --title "v$TAG" \
+            --notes "${{ steps.notes.outputs.notes }}"

sqlalchemy_adbc-0.3.0/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+All notable changes to `sqlalchemy-adbc` are documented here. Format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.3.0] — 2026-04-21
+
+Largest release so far: table reflection, Alembic autogenerate,
+PostgreSQL type decorators, and breaking fixes to dialect naming
+and Python version support. Not backwards-compatible for callers
+that read `engine.dialect.name` or run on Python 3.9.
+
+### Added
+
+- **Table reflection via `adbc_get_objects`** — the full SQLAlchemy
+  Inspector contract now works for any ADBC driver that implements
+  the GetObjects metadata call. Covers `get_columns`,
+  `get_pk_constraint`, `get_foreign_keys`, `get_unique_constraints`,
+  `get_table_names`, `get_view_names`, `get_schema_names`, and
+  `has_table`. `MetaData.reflect(bind=engine)` works end-to-end.
+  ([#5](https://github.com/drls-io/sqlalchemy-adbc/pull/5),
+  closes [#1](https://github.com/drls-io/sqlalchemy-adbc/issues/1))
+- **Native `get_indexes` for SQLite and PostgreSQL** — ADBC's
+  GetObjects spec doesn't carry per-index column lists, so we
+  query the backend's native catalog (PRAGMA `index_list` /
+  `index_info` for SQLite; `pg_index` / `pg_class` / `pg_attribute`
+  with `LATERAL unnest WITH ORDINALITY` for PG). Identifiers are
+  properly escaped — PRAGMA can't be parameterized.
+  ([#6](https://github.com/drls-io/sqlalchemy-adbc/pull/6))
+- **Alembic autogenerate support** — fallout from the dialect-name
+  fix below. Alembic's DDL impl registry now finds the correct
+  per-backend impl (`SQLiteImpl`, `PostgresqlImpl`) for free.
+  Covers create/drop table, add/drop column, and roundtrip
+  idempotency (apply autogenerate output → re-run → no-op).
+  ([#7](https://github.com/drls-io/sqlalchemy-adbc/pull/7),
+  closes [#2](https://github.com/drls-io/sqlalchemy-adbc/issues/2))
+- **PostgreSQL type decorators** — `JSONB`, `JSON`, `UUID`, `INET`,
+  `CIDR`, `MACADDR`, `MACADDR8`. Round-trip PG-specific types
+  through ADBC as the Python objects SQLAlchemy users expect:
+  JSONB → dict/list, UUID → `uuid.UUID` (or `str` with
+  `as_uuid=False`), INET/CIDR/MAC as strings. PG column reflection
+  now queries `information_schema.columns.udt_name` directly
+  (ADBC's `xdbc_type_name` is unreliable for PG-extension types),
+  so `MetaData.reflect()` surfaces these as TypeDecorators, not
+  `NullType`. ([#8](https://github.com/drls-io/sqlalchemy-adbc/pull/8),
+  closes [#3](https://github.com/drls-io/sqlalchemy-adbc/issues/3))
+- **CI Postgres service** — integration tests (`test_postgresql_types.py`)
+  now run against a real `postgres:16` container, gated by
+  `DRLS_PG_URL`. Local `pytest` runs without Postgres continue to
+  skip these cleanly.
+
+### Changed
+
+- **BREAKING — dialect `name` and `driver` attributes flipped** to
+  match SQLAlchemy's convention: `name` is the backend identity
+  (`sqlite`, `postgresql`, `flightsql`, `snowflake`, `bigquery`),
+  `driver` is the wire path (`adbc`). Previously every dialect
+  reported `name="adbc"`, which caused Alembic's DDL-impl lookup
+  to `KeyError`. URL forms (`adbc+sqlite://`, etc.) are unchanged.
+  Callers inspecting `engine.dialect.name` must update expectations.
+- **BREAKING — dropped Python 3.9.** Python 3.9 reached end-of-life
+  in October 2025. `requires-python` is now `>=3.10`; the CI matrix
+  covers 3.10–3.13.
+- **Development Status classifier: Alpha → Beta.** Matches the
+  README's scope statement — core functionality is stable enough
+  for real use, but a few months of external feedback still needed
+  before 1.0.
+
+### Fixed
+
+- **PG `paramstyle` — `numeric_dollar`.** Forces SQLAlchemy to emit
+  `$1, $2, ...` (libpq's native wire form) instead of `:name` binds
+  via ADBC's `adbc.statement.bind_by_name` (which libpq rejects
+  with `NOT_IMPLEMENTED`) or `:1, :2, ...` (which PG's parser
+  rejects with `syntax error at or near ":"`). Set via
+  `__init__(kwargs.setdefault(...))` because `DefaultDialect.__init__`
+  clobbers the class-level attribute from `dbapi.paramstyle`.
+- `get_columns` now honors SQLAlchemy's `ReflectedColumn` shape
+  ([#5](https://github.com/drls-io/sqlalchemy-adbc/pull/5))
+- Mypy is gated in CI with proper `sqlalchemy.engine.interfaces`
+  return types
+- `cache_ok = True` declared explicitly on `JSON` and `CIDR`
+  subclasses — the attribute does not inherit across `TypeDecorator`
+  subclasses, so the absence silenced statement caching and
+  emitted SAWarning on every engine.
+
+## [0.2.0] — 2026-04-19
+
+Security + correctness release. Not backwards-compatible for
+Flight SQL users relying on the plaintext-by-default behavior.
+
+### Changed
+
+- **BREAKING — Flight SQL TLS is now default-on** (`tls=true`).
+  Send a bearer token over plaintext gRPC was an unmissable
+  credential-leak shape. Local/dev users on plaintext listeners
+  must now opt out with `?tls=false`. Default port auto-picks
+  443 for TLS, 50051 for plaintext (Arrow Flight convention).
+
+### Fixed
+
+- **URL → DSN special-character escaping** for PostgreSQL and
+  Snowflake. A password containing `@`, `:`, `/`, `#`, `%` was
+  previously concatenated into the DSN unquoted and would silently
+  re-route libpq to the wrong host. Username/password now routed
+  through `urllib.parse.quote`; database path stays as-is since
+  SQLAlchemy's URL parser leaves it percent-encoded.
+- mypy errors in the Flight SQL dialect around `URL.query`
+  tuple vs str handling. A `_scalar()` helper normalizes repeated
+  keys to their last value (HTTP/shell convention).
+- Formatting drift on three files.
+
+### Added
+
+- CI gates `mypy src tests` alongside the existing ruff check.
+- Extensive URL-parse test coverage: 13 PG, 9 Snowflake, 5 BigQuery
+  tests covering special-char escaping, no-credentials paths, and
+  edge cases. Total suite: 51 (up from 16).
+- Documentation of known gaps in the README (table reflection,
+  Alembic autogenerate, PG-specific types) with links to tracking
+  issues.
+
+## [0.1.0] — 2026-04-18
+
+Initial public release.
+
+### Added
+
+- Generic `ADBCDialect` base class with per-driver subclasses for
+  Flight SQL, SQLite, PostgreSQL, Snowflake, and BigQuery
+- URL → `db_kwargs` translation per driver
+- Entry-point registration under `sqlalchemy.dialects` so any
+  `adbc+<driver>://` URL resolves automatically
+- PyPI trusted publishing via OIDC
+
+[Unreleased]: https://github.com/drls-io/sqlalchemy-adbc/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/drls-io/sqlalchemy-adbc/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/drls-io/sqlalchemy-adbc/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/drls-io/sqlalchemy-adbc/releases/tag/v0.1.0

{sqlalchemy_adbc-0.2.0 → sqlalchemy_adbc-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlalchemy-adbc
-Version: 0.2.0
+Version: 0.3.0
 Summary: Generic SQLAlchemy dialect for any ADBC driver (Flight SQL, PostgreSQL, SQLite, Snowflake, BigQuery).
 Project-URL: Homepage, https://github.com/drls-io/sqlalchemy-adbc
 Project-URL: Repository, https://github.com/drls-io/sqlalchemy-adbc
@@ -9,13 +9,17 @@ Author: DRLS Contributors
 License: Apache-2.0
 License-File: LICENSE
 Keywords: adbc,arrow,dialect,flight-sql,sqlalchemy
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
 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: Topic :: Database
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Requires-Dist: adbc-driver-manager>=1.0
 Requires-Dist: pyarrow>=14.0
 Requires-Dist: sqlalchemy>=2.0
@@ -23,6 +27,7 @@ Provides-Extra: bigquery
 Requires-Dist: adbc-driver-bigquery>=1.0; extra == 'bigquery'
 Provides-Extra: dev
 Requires-Dist: adbc-driver-sqlite>=1.0; extra == 'dev'
+Requires-Dist: alembic>=1.13; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
@@ -117,30 +122,47 @@ df = pd.read_sql("SELECT 1 AS n", engine)
 
 ## Status
 
-Alpha — the core dialect machinery works for simple `SELECT` / `INSERT` /
-`CREATE TABLE` use. More advanced SQLAlchemy features are still to come;
-the known gaps are called out below so you don't waste time debugging a
-missing feature:
-
-- **Table reflection** (`MetaData.reflect()`): not implemented. The ADBC
-  driver exposes table/column metadata via the Arrow-based `GetObjects`
-  call, but this library doesn't yet wire that into SQLAlchemy's
-  `Inspector` contract. PRs welcome.
-- **Alembic autogenerate**: follows from reflection — won't work until
-  reflection lands. `alembic upgrade` against already-written migrations
-  is fine (it's pure SQL).
-- **PostgreSQL-specific types** (JSONB, ARRAY, UUID, TSTZMULTIRANGE,
-  …): ADBC's Arrow-over-the-wire codec returns these as strings / lists
-  of primitives, not as SQLAlchemy's typed objects. If you need ORM-level
-  round-tripping of PG-specific types, use `psycopg2` until we add a
-  type compiler.
-- **Query parameterization**: uses ADBC's native `$1`-style placeholders
-  for PostgreSQL and `?` for SQLite. Flight SQL and Snowflake delegate
-  to the driver's default.
-
-PRs welcome.
-
-Tests: 52+ passing against ADBC SQLite + URL/DSN translators on Python 3.9–3.13.
+**Beta.** Core dialect + reflection + Alembic autogenerate work on
+the ADBC drivers we exercise in CI (SQLite end-to-end, PostgreSQL
+via service container). Not 1.0 yet — we want a few months of
+real-world use and at least one release without breaking changes
+before committing to a stable API.
+
+Full history in [CHANGELOG.md](CHANGELOG.md). Download tags on
+[GitHub Releases](https://github.com/drls-io/sqlalchemy-adbc/releases);
+published wheels on [PyPI](https://pypi.org/project/sqlalchemy-adbc/).
+
+### What works
+
+- `SELECT` / `INSERT` / `CREATE TABLE` / `DROP TABLE` / `ALTER TABLE`
+  for every advertised driver
+- `MetaData.reflect(bind=engine)` — full Inspector contract backed
+  by ADBC `GetObjects`, including columns, PK, FK, unique
+  constraints, indexes (native PRAGMA / `pg_catalog` queries on
+  SQLite and PG)
+- Alembic `autogenerate` — end-to-end, reusing SQLAlchemy's native
+  backend DDL impls via standard dialect-name lookup
+- URL forms for Flight SQL, PostgreSQL, SQLite, Snowflake, BigQuery
+  with correct special-character escaping in passwords
+
+### Known limitations
+
+- **PostgreSQL range types** (tstzrange, tstzmultirange, int4range,
+  …) and **hstore** — not yet mapped to typed decorators; returned
+  as raw strings. JSONB / JSON / UUID / INET / CIDR / MACADDR /
+  MACADDR8 all round-trip through typed decorators as of 0.3.0
+  ([#3](https://github.com/drls-io/sqlalchemy-adbc/issues/3) —
+  JSONB/UUID/INET portion closed)
+- **Drivers exercised in CI** — SQLite fully, PostgreSQL
+  integration-tested via service container. Snowflake / BigQuery /
+  Flight SQL inherit the shared reflection path but have no
+  per-driver CI
+- **ADBC SQLite NOT NULL reporting** — upstream driver always
+  reports nullable=True; reflection faithfully reflects that
+  (tracked, auto-reactivating xfail)
+
+Tests: 106 passing on Python 3.10–3.13, including 17 PostgreSQL
+integration tests against a service-container Postgres.
 
 ## Development
 

{sqlalchemy_adbc-0.2.0 → sqlalchemy_adbc-0.3.0}/README.md

@@ -78,30 +78,47 @@ df = pd.read_sql("SELECT 1 AS n", engine)
 
 ## Status
 
-Alpha — the core dialect machinery works for simple `SELECT` / `INSERT` /
-`CREATE TABLE` use. More advanced SQLAlchemy features are still to come;
-the known gaps are called out below so you don't waste time debugging a
-missing feature:
-
-- **Table reflection** (`MetaData.reflect()`): not implemented. The ADBC
-  driver exposes table/column metadata via the Arrow-based `GetObjects`
-  call, but this library doesn't yet wire that into SQLAlchemy's
-  `Inspector` contract. PRs welcome.
-- **Alembic autogenerate**: follows from reflection — won't work until
-  reflection lands. `alembic upgrade` against already-written migrations
-  is fine (it's pure SQL).
-- **PostgreSQL-specific types** (JSONB, ARRAY, UUID, TSTZMULTIRANGE,
-  …): ADBC's Arrow-over-the-wire codec returns these as strings / lists
-  of primitives, not as SQLAlchemy's typed objects. If you need ORM-level
-  round-tripping of PG-specific types, use `psycopg2` until we add a
-  type compiler.
-- **Query parameterization**: uses ADBC's native `$1`-style placeholders
-  for PostgreSQL and `?` for SQLite. Flight SQL and Snowflake delegate
-  to the driver's default.
-
-PRs welcome.
-
-Tests: 52+ passing against ADBC SQLite + URL/DSN translators on Python 3.9–3.13.
+**Beta.** Core dialect + reflection + Alembic autogenerate work on
+the ADBC drivers we exercise in CI (SQLite end-to-end, PostgreSQL
+via service container). Not 1.0 yet — we want a few months of
+real-world use and at least one release without breaking changes
+before committing to a stable API.
+
+Full history in [CHANGELOG.md](CHANGELOG.md). Download tags on
+[GitHub Releases](https://github.com/drls-io/sqlalchemy-adbc/releases);
+published wheels on [PyPI](https://pypi.org/project/sqlalchemy-adbc/).
+
+### What works
+
+- `SELECT` / `INSERT` / `CREATE TABLE` / `DROP TABLE` / `ALTER TABLE`
+  for every advertised driver
+- `MetaData.reflect(bind=engine)` — full Inspector contract backed
+  by ADBC `GetObjects`, including columns, PK, FK, unique
+  constraints, indexes (native PRAGMA / `pg_catalog` queries on
+  SQLite and PG)
+- Alembic `autogenerate` — end-to-end, reusing SQLAlchemy's native
+  backend DDL impls via standard dialect-name lookup
+- URL forms for Flight SQL, PostgreSQL, SQLite, Snowflake, BigQuery
+  with correct special-character escaping in passwords
+
+### Known limitations
+
+- **PostgreSQL range types** (tstzrange, tstzmultirange, int4range,
+  …) and **hstore** — not yet mapped to typed decorators; returned
+  as raw strings. JSONB / JSON / UUID / INET / CIDR / MACADDR /
+  MACADDR8 all round-trip through typed decorators as of 0.3.0
+  ([#3](https://github.com/drls-io/sqlalchemy-adbc/issues/3) —
+  JSONB/UUID/INET portion closed)
+- **Drivers exercised in CI** — SQLite fully, PostgreSQL
+  integration-tested via service container. Snowflake / BigQuery /
+  Flight SQL inherit the shared reflection path but have no
+  per-driver CI
+- **ADBC SQLite NOT NULL reporting** — upstream driver always
+  reports nullable=True; reflection faithfully reflects that
+  (tracked, auto-reactivating xfail)
+
+Tests: 106 passing on Python 3.10–3.13, including 17 PostgreSQL
+integration tests against a service-container Postgres.
 
 ## Development
 

{sqlalchemy_adbc-0.2.0 → sqlalchemy_adbc-0.3.0}/pyproject.toml

@@ -4,19 +4,23 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlalchemy-adbc"
-version = "0.2.0"
+version = "0.3.0"
 description = "Generic SQLAlchemy dialect for any ADBC driver (Flight SQL, PostgreSQL, SQLite, Snowflake, BigQuery)."
 readme = "README.md"
 license = { text = "Apache-2.0" }
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 authors = [{ name = "DRLS Contributors" }]
 keywords = ["sqlalchemy", "adbc", "arrow", "flight-sql", "dialect"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
     "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",
     "Topic :: Database",
 ]
 dependencies = [
@@ -41,6 +45,10 @@ dev = [
     "ruff>=0.6",
     "mypy>=1.10",
     "adbc-driver-sqlite>=1.0",
+    # Alembic autogenerate tests (test_alembic_autogenerate.py) rely on
+    # the Inspector contract we implemented in #1 — pinning the dev
+    # pin ensures CI exercises that integration path.
+    "alembic>=1.13",
 ]
 
 [project.urls]
@@ -64,7 +72,7 @@ packages = ["src/sqlalchemy_adbc"]
 
 [tool.ruff]
 line-length = 100
-target-version = "py39"
+target-version = "py310"
 
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "B", "UP"]