install.sh --drivers: bootstrap the open-licence ODBC drivers

.github/workflows/ci.yml

@@ -191,6 +191,37 @@ jobs:
           ADBC_ODBC_DRIVER: ${{ github.workspace }}/build/libadbc_driver_odbc.so
         run: python tests/test_sqlite.py
 
+      # install.sh --drivers: the bridge into ~/.local plus the four open-licence
+      # drivers (apt for three, ClickHouse's checksummed tarball for the fourth).
+      # Its own build tree, so the CI build above is left alone; the manifest it
+      # writes to ~/.config/adbc/drivers is what driver="odbc" resolves through.
+      - name: Driver bootstrap (install.sh --drivers, Linux)
+        if: runner.os == 'Linux'
+        env:
+          BUILD_DIR: ${{ github.workspace }}/build-install
+        run: |
+          set -o pipefail
+          ./install.sh --drivers | tee install.log
+          grep -E '^  (sqlite|postgres|mysql|clickhouse) +ok ' install.log | wc -l | grep -qx 4
+          python - <<'PY'
+          import os, glob, ctypes
+          import adbc_driver_manager.dbapi as dbapi
+          with dbapi.connect(driver="odbc", db_kwargs={"uri": "Driver=SQLite3;Database=:memory:;"}) as conn:
+              with conn.cursor() as cur:
+                  cur.execute("SELECT 1 AS one")
+                  assert cur.fetch_arrow_table().to_pydict() == {"one": [1]}
+          for name in ("PostgreSQL Unicode", "MariaDB Unicode"):
+              # No server in this job: a driver that loads and answers the handshake is enough.
+              try:
+                  dbapi.connect(driver="odbc", db_kwargs={"uri": f"Driver={name};Server=127.0.0.1;Port=1;Uid=x;Pwd=x;"})
+              except Exception as e:
+                  assert "SQLDriverConnect" in str(e), e  # reached the driver; refused by the (absent) server
+          ch = glob.glob(os.path.expanduser("~/.local/odbc-drivers/clickhouse-odbc-*/lib/libclickhouseodbcw.so"))
+          assert ch, "clickhouse-odbc not unpacked"
+          ctypes.CDLL(ch[0])
+          print("driver bootstrap OK")
+          PY
+
       # The Python package (python/) is a thin wrapper around the library built
       # above; ADBC_ODBC_DRIVER points its driver lookup at that build.
       - name: Test the Python package (Linux)

README.md

@@ -81,7 +81,8 @@ you get native speed from the same install.
 ## Quick start
 
 ```sh
-./install.sh                                  # build + install into ~/.local, no root
+./install.sh --drivers                        # build + install into ~/.local; --drivers adds the
+                                              # SQLite, PostgreSQL, MariaDB and ClickHouse ODBC drivers
 pip install adbc-driver-manager pyarrow
 ```
 
@@ -295,12 +296,11 @@ place they looked.
 ## Status and roadmap
 
 Early (0.1.3). Working: everything under *What it does*, on Linux, macOS (arm64) and
-Windows (x64 and Win32 built and tested in CI on every push; the Windows build lacks
-prefetch and parallel ingest); 0.1.3 on PyPI, crates.io, nuget.org and Maven Central. The ADBC Driver
+Windows (x64 and Win32 built and tested in CI on every push); 0.1.3 on PyPI, crates.io,
+nuget.org and Maven Central. The ADBC Driver
 Foundry validation suite passes on PostgreSQL apart from declared server limits
-([`tests/validation/RESULTS.md`](tests/validation/RESULTS.md)). Next: a driver bootstrap for
-the open-licence ODBC drivers, the Win32 thread shim; then a JDBC bridge on the same model —
-[`docs/ROADMAP.md`](docs/ROADMAP.md).
+([`tests/validation/RESULTS.md`](tests/validation/RESULTS.md)). Next: a JDBC bridge on the
+same model — [`docs/ROADMAP.md`](docs/ROADMAP.md).
 
 ## Upstream: giving back
 

docs/ROADMAP.md

@@ -21,7 +21,8 @@ ODBC is the first bridge; the name leaves room for the others.
 | Windows, to verify on the next Windows session (reported by the second Windows campaign, not reproduced on a machine still available): (1) whether `cmake --install` under MSVC can write the manifest key `windows_amd64_mingw` (CMake's `MINGW` is only set for a GNU toolchain; the campaign's own build log recorded `windows_amd64`); (2) the Go binding's SQLite test leaves the database file open after `Close` so `t.TempDir()` cleanup fails — the drivermgr `Close` calls `AdbcConnectionRelease`/`AdbcDatabaseRelease` synchronously, so the open handle is either a driver-side pool or a missing release in the test's reader path | next |
 | Connection-level reader options (`adbc.odbc.batch_size`, `sqllen_32bit`) set before AdbcConnectionInit are discarded — `OdbcConnectionInit` copies the database defaults over them; re-apply the recorded pre-options after the copy | next |
 | Windows: prefetch pipeline and parallel ingest on Win32 threads (SRWLOCK, CONDITION_VARIABLE, `_beginthreadex`), the same options and behaviour as Linux and macOS | done (0.1.4) |
-| **Driver bootstrap**: `install.sh` / the Windows and macOS installers fetch the open-licence ODBC drivers a first run needs (sqliteodbc, psqlodbc, MariaDB Connector/ODBC, clickhouse-odbc) so SQLite/PostgreSQL/MySQL work with nothing else installed; vendor drivers (Oracle, Db2, SQL Server, Snowflake…) stay the user's download — their licences do not allow redistribution, and Windows already ships the SQL Server driver | next |
+| **Driver bootstrap**: `install.sh --drivers` installs the open-licence ODBC drivers a first run needs (sqliteodbc, psqlodbc, MariaDB Connector/ODBC through apt, dnf or Homebrew; clickhouse-odbc from its pinned, checksummed release tarball) and prints what landed where with a connection string each; vendor drivers (Oracle, Db2, SQL Server, Snowflake…) stay the user's download — their licences do not allow redistribution, and Windows already ships the SQL Server driver | done (0.1.4), Linux and macOS |
+| Driver bootstrap on Windows: a PowerShell counterpart that runs the vendors' MSI installers (psqlodbc, sqliteodbc, MariaDB Connector/ODBC, clickhouse-odbc) | next |
 | ADBC Driver Foundry validation suite ([`tests/validation/RESULTS.md`](../tests/validation/RESULTS.md)): PostgreSQL 293/327 pass with the other 34 declared backend limitations (2026-09-15; was 265 on 2026-09-06), SQLite 212/327 with the remainder being precision SQLiteODBC does not report; baseline findings D1–D9, D11, D14 and the PostgreSQL findings P1–P4 (TIME/TIMESTAMP precision and zone fidelity), P7 (`db_schema` option) and P8 (schema catalog fill) fixed; `tests/test_postgres.py` pins them in CI | done — released in 0.1.2 (2026-09-15) |
 | Trust artefacts: security policy with private vulnerability reporting and a stated support window (`SECURITY.md`); Dependabot on every manifest; `SHA256SUMS` and its signature (`SHA256SUMS.asc`) on v0.1.0; every later release signed, attested (GitHub build provenance, `gh attestation verify`) and shipped with an SPDX SBOM by the release workflow | done |
 | Foundry listing (adbc-drivers.org) | next |

docs/community/faq.md

@@ -386,9 +386,8 @@ the [roadmap](../ROADMAP.md).
 
 ### What is on the roadmap?
 
-For the ODBC bridge: a driver-bootstrap installer that fetches the open-licence
-drivers, Maven Central publication, the ADBC Driver Foundry validation
-suite. Beyond ODBC: a
+For the ODBC bridge: the Windows counterpart of `install.sh --drivers`, and the
+items in the roadmap's "now" table. Beyond ODBC: a
 **JDBC bridge** (load a JVM in-process and drive any JDBC driver) and, later, an
 **OLE DB bridge** for Windows. Full detail and status in
 [`docs/ROADMAP.md`](../ROADMAP.md).

docs/getting-started/install-linux.md

@@ -147,14 +147,39 @@ installs into your home directory, and writes the manifest into the ADBC user
 config directory so discovery just works.
 
 ```sh
-./install.sh
+./install.sh             # the bridge only
+./install.sh --drivers   # the bridge plus the four open-licence ODBC drivers below
 ```
 
 It puts the library in `~/.local/lib/libadbc_driver_odbc.so` (`lib64` on
 Fedora/RHEL-style 64-bit systems) and the manifest in
 `~/.config/adbc/drivers/odbc.toml`, then prints both paths. Re-running it is
-safe — it reconfigures the same build tree and overwrites the same two files. It
-honours these environment overrides:
+safe — it reconfigures the same build tree and overwrites the same two files.
+
+**`--drivers`** also installs the drivers a first run usually needs, so SQLite,
+PostgreSQL, MySQL/MariaDB and ClickHouse work with nothing else fetched by hand:
+
+| Database | Driver | How it is installed |
+|---|---|---|
+| SQLite | sqliteodbc | `apt install libsqliteodbc` / `dnf install sqliteodbc`, through `sudo` |
+| PostgreSQL | psqlodbc | `apt install odbc-postgresql` / `dnf install postgresql-odbc` |
+| MySQL / MariaDB | MariaDB Connector/ODBC | `apt install odbc-mariadb` / `dnf install mariadb-connector-odbc` |
+| ClickHouse | clickhouse-odbc | the project's release tarball (pinned version, SHA-256 checked), unpacked under `~/.local/odbc-drivers`, no root |
+
+The first three go through the system package manager on purpose: their
+runtime libraries (`libpq`, `libmariadb`) have to be on the loader path, which
+only the package manager arranges, and the package registers the driver's name
+(`SQLite3`, `PostgreSQL Unicode`, `MariaDB Unicode`) in `odbcinst.ini` so it
+works after `Driver=`. clickhouse-odbc has no distribution package and links its
+C++ runtime in, so it is unpacked for the current user and used by path. The
+script ends with a table of what landed where, whether each library loads, and
+a connection string for each. `--drivers=sqlite,postgres` limits it to some of
+the four; `--drivers-only` skips the build when the bridge is already installed.
+Vendor drivers whose licences do not allow redistribution (Oracle, Db2, SQL
+Server, Snowflake, …) stay a separate download — section 2 above and the
+[compatibility matrix](../COMPATIBILITY.md) name each one.
+
+`install.sh` honours these environment overrides:
 
 | Variable | Meaning | Default |
 |---|---|---|
@@ -163,6 +188,7 @@ honours these environment overrides:
 | `BUILD_DIR` | CMake build tree | `<repo>/build` |
 | `BUILD_TYPE` | CMake build type | `Release` |
 | `JOBS` | parallel build jobs | `nproc` |
+| `SUDO` | command that runs the package manager as root for `--drivers` | `sudo` (empty when already root) |
 
 > **Troubleshooting:** If `install.sh` stops with `cmake not found`, install the
 > build prerequisites first — on Debian/Ubuntu `sudo apt install cmake

docs/getting-started/install-macos.md

@@ -156,7 +156,8 @@ as shown in [the iODBC section](#when-you-need-a-bridge-built-against-iodbc-inst
 ### Via install.sh
 
 ```sh
-./install.sh
+./install.sh             # the bridge only
+./install.sh --drivers   # the bridge plus sqliteodbc, psqlodbc, MariaDB Connector/ODBC and clickhouse-odbc
 ```
 
 On macOS `install.sh` writes the library under `~/.local/lib` and the manifest
@@ -165,6 +166,14 @@ into the ADBC user config directory, which on macOS is
 `MANIFEST_DIR`, `BUILD_DIR`, `BUILD_TYPE` and `JOBS` overrides from the
 [Linux page](install-linux.md#via-installsh) apply unchanged.
 
+`--drivers` installs the three unixODBC drivers through Homebrew (`sqliteodbc`,
+`psqlodbc`, `mariadb-connector-odbc`, no root) and unpacks clickhouse-odbc's
+macOS release tarball (pinned version, SHA-256 checked) under
+`~/.local/odbc-drivers`. Homebrew formulae do not register driver names in
+`odbcinst.ini`, so the script prints each library's path, which is what goes
+after `Driver=`. The iODBC-only drivers in the table above are not part of this;
+they need the second bridge build described there.
+
 ## The ADBC driver manifest
 
 The manifest works exactly as on [Linux](install-linux.md#the-adbc-driver-manifest),