You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by li...@apache.org on 2026/07/20 00:43:45 UTC
(arrow-adbc) branch main updated: docs: reorganize docs to highlight tools and drivers (#4525)
This is an automated email from the ASF dual-hosted git repository.
lidavidm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-adbc.git
The following commit(s) were added to refs/heads/main by this push:
new fddc14887 docs: reorganize docs to highlight tools and drivers (#4525)
fddc14887 is described below
commit fddc1488733eef25856a4c9e382b21a9d23ef06d
Author: Bryce Mecum <pe...@gmail.com>
AuthorDate: Sun Jul 19 17:43:40 2026 -0700
docs: reorganize docs to highlight tools and drivers (#4525)
This is a major reorganization and rethinking of the ADBC docs to catch
them up with what's happening across the ADBC ecosystem.
The key changes are:
- New, simpler landing page focusing on the core questions users will
have (what drivers are available, how do I connect with one, how do I
write a new driver)
- New sidebar structure that starts by grouping pages into one of two
major categories: Connecting or Writing Drivers
- New Drivers page that covers the third-party driver ecosystem which
has grown quite a lot. Includes talking about dbc, the ADBC Driver
Foundry, third-party drivers offered by Columnar
- New Tools & Integrations page covering the cool ecosystem stuff like
pandas/polars/R/etc
- Now uses the term "Client Library" over Driver Manager in many places
as this is conceptually more simple. No packages were renamed so the
term Driver Manager is still valid and used in the docs.
- Language-specific docs now more consistently load drivers by manifest
rather than driver-specific packages.
- New page on Writing Drivers
- New page on Connection Profiles
- A small but updated C# page
- Updated Glossary
Closes https://github.com/apache/arrow-adbc/issues/4233
Closes #4454
---------
Co-authored-by: David Li <li...@gmail.com>
Co-authored-by: Ian Cook <ia...@gmail.com>
Co-authored-by: Emil Sadek <es...@hotmail.com>
---
.github/workflows/native-unix.yml | 15 ++
README.md | 2 +-
ci/conda_env_docs.txt | 1 +
.../scripts/make_manifests.sh | 33 +--
compose.yaml | 2 +-
dev/release/post-11-announce.sh | 2 +-
dev/release/rat_exclude_files.txt | 1 +
docs/source/_static/css/custom.css | 110 ++++++++
docs/source/_static/logo-dark.png | Bin 22461 -> 7628 bytes
docs/source/_static/logo-light.png | Bin 11027 -> 7628 bytes
docs/source/_static/logo.svg | 17 ++
docs/source/client_libraries.rst | 109 ++++++++
docs/source/conf.py | 19 +-
docs/source/connection_profiles.rst | 191 ++++++++++++++
docs/source/cpp/recipe/quickstart.cc | 31 ++-
docs/source/csharp/index.rst | 72 +++++-
docs/source/driver/authoring.rst | 124 +++++++--
docs/source/driver/bigquery.rst | 10 +-
docs/source/driver/duckdb.rst | 2 +
docs/source/driver/flight_sql.rst | 2 +
docs/source/driver/index.rst | 285 +++++++++++++++++++++
docs/source/driver/jdbc.rst | 2 +
docs/source/driver/postgresql.rst | 12 +-
docs/source/driver/sqlite.rst | 2 +
docs/source/driver/status.rst | 226 ----------------
docs/source/ext/adbc_misc.py | 143 +++++------
docs/source/faq.rst | 4 +-
docs/source/format/connection_profiles.rst | 18 +-
docs/source/format/driver_manifests.rst | 35 ++-
docs/source/format/related_work.rst | 7 +-
docs/source/glossary.rst | 88 ++++---
docs/source/index.rst | 278 ++++++++++----------
docs/source/{driver => }/installation.rst | 31 ++-
docs/source/integrations.rst | 200 +++++++++++++++
docs/source/java/jni.rst | 2 +-
docs/source/java/quickstart.rst | 61 +++--
docs/source/javascript/quickstart.rst | 40 +--
docs/source/python/quickstart.rst | 53 +++-
.../python/recipe/driver_manager_lowlevel.py | 5 +-
.../source/python/recipe/driver_manager_prepare.py | 4 +-
.../python/recipe/flightsql_dremio_connect.py | 5 +-
.../recipe/flightsql_oauth_client_credentials.py | 4 +-
.../recipe/flightsql_oauth_token_exchange.py | 4 +-
.../python/recipe/flightsql_sqlite_connect.py | 4 +-
.../python/recipe/flightsql_sqlite_max_msg_size.py | 9 +-
.../python/recipe/flightsql_sqlite_options.py | 5 +-
docs/source/python/recipe/postgresql.rst | 2 +
.../python/recipe/postgresql_authenticate.py | 4 +-
docs/source/python/recipe/postgresql_autocommit.py | 4 +-
.../recipe/postgresql_create_append_table.py | 4 +-
.../recipe/postgresql_create_dataset_table.py | 4 +-
.../python/recipe/postgresql_create_temp_table.py | 6 +-
.../python/recipe/postgresql_execute_bind.py | 4 +-
.../python/recipe/postgresql_execute_nocopy.py | 8 +-
.../python/recipe/postgresql_get_query_schema.py | 4 +-
.../python/recipe/postgresql_get_table_schema.py | 4 +-
.../python/recipe/postgresql_list_catalogs.py | 4 +-
docs/source/python/recipe/postgresql_pandas.py | 4 +-
docs/source/python/recipe/postgresql_pool.py | 4 +-
docs/source/python/recipe/sqlite_batch_rows.py | 6 +-
docs/source/r/index.rst | 103 +++++++-
docs/source/ruby/index.rst | 159 ++++++++++++
docs/source/rust/driver_manager.rst | 12 +-
docs/source/rust/quickstart.rst | 61 +++--
go/adbc/README.md | 12 +-
ruby/README.md | 2 +-
66 files changed, 1960 insertions(+), 721 deletions(-)
diff --git a/.github/workflows/native-unix.yml b/.github/workflows/native-unix.yml
index 59236003f..3af8831c0 100644
--- a/.github/workflows/native-unix.yml
+++ b/.github/workflows/native-unix.yml
@@ -695,6 +695,21 @@ jobs:
ADBC_USE_UBSAN: "0"
run: |
./ci/scripts/python_build.sh "$(pwd)" "$(pwd)/build" "$HOME/local"
+ - name: Create manifests
+ run: |
+ # Create manifests so the C++ examples/doctests can find SQLite via
+ # just "sqlite" (and so on)
+ mkdir -p ~/.config/adbc/drivers
+ for d in flightsql postgresql sqlite; do
+ lib_path=$(readlink -f "$HOME/local/lib/libadbc_driver_$d.so")
+ cat <<EOF > "$HOME/.config/adbc/drivers/$d.toml"
+ manifest_version = 1
+ [Driver]
+ shared = "$lib_path"
+ EOF
+ done
+ ls ~/.config/adbc/drivers
+ cat ~/.config/adbc/drivers/*.toml
# Docs requires Python packages since it runs doctests
- name: Build Docs
run: |
diff --git a/README.md b/README.md
index cb2b9c069..db33f1c8a 100644
--- a/README.md
+++ b/README.md
@@ -48,7 +48,7 @@ For more details, see the [documentation](https://arrow.apache.org/adbc/main/dri
## Installation
-Please see the [documentation](https://arrow.apache.org/adbc/main/driver/installation.html).
+Please see the [documentation](https://arrow.apache.org/adbc/main/installation.html).
## Documentation
diff --git a/ci/conda_env_docs.txt b/ci/conda_env_docs.txt
index c1837f47d..ffe700296 100644
--- a/ci/conda_env_docs.txt
+++ b/ci/conda_env_docs.txt
@@ -29,6 +29,7 @@ sphinx-autobuild
sphinx-copybutton
sphinx-design
sphinxext-opengraph
+sphinx-reredirects
# Used in recipes
sqlalchemy>2
r-pkgdown
diff --git a/docs/source/python/recipe/flightsql_sqlite_connect.py b/ci/scripts/make_manifests.sh
old mode 100644
new mode 100755
similarity index 59%
copy from docs/source/python/recipe/flightsql_sqlite_connect.py
copy to ci/scripts/make_manifests.sh
index 97148e6d6..a02f795ef
--- a/docs/source/python/recipe/flightsql_sqlite_connect.py
+++ b/ci/scripts/make_manifests.sh
@@ -1,3 +1,4 @@
+#!/usr/bin/env bash
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
@@ -15,22 +16,24 @@
# specific language governing permissions and limitations
# under the License.
-# RECIPE STARTS HERE
+# Only used in CI to make manifests before building docs
-#: To connect to an unsecured Flight SQL service, just provide the URI.
+set -euxo pipefail
-import os
+main() {
+ local -r install_dir="${1}"
-import adbc_driver_flightsql.dbapi
+ mkdir -p "$HOME/.config/adbc/drivers"
+ for d in flightsql postgresql sqlite; do
+ driver_path=$(readlink -f "$install_dir/lib/libadbc_driver_$d.so")
+ cat <<EOF > "$HOME/.config/adbc/drivers/$d.toml"
+ manifest_version = 1
+ [Driver]
+ shared = "$driver_path"
+EOF
+ done
+ ls ~/.config/adbc/drivers
+ cat ~/.config/adbc/drivers/*.toml
+}
-uri = os.environ["ADBC_SQLITE_FLIGHTSQL_URI"]
-conn = adbc_driver_flightsql.dbapi.connect(uri)
-
-#: We can then execute a simple query.
-
-with conn.cursor() as cur:
- cur.execute("SELECT 1")
-
- assert cur.fetchone() == (1,)
-
-conn.close()
+main "$@"
diff --git a/compose.yaml b/compose.yaml
index 7bf912852..4b67f755a 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -101,7 +101,7 @@ services:
ADBC_USE_UBSAN: "0"
CGO_ENABLED: "1"
command: |
- /bin/bash -c 'git config --global --add safe.directory /adbc && source /opt/conda/etc/profile.d/conda.sh && mamba create -y -n adbc -c conda-forge go --file /adbc/ci/conda_env_cpp.txt --file /adbc/ci/conda_env_docs.txt --file /adbc/ci/conda_env_java.txt --file /adbc/ci/conda_env_python.txt && conda activate adbc && /adbc/ci/scripts/cpp_build.sh /adbc /adbc/build && /adbc/ci/scripts/go_build.sh /adbc /adbc/build && /adbc/ci/scripts/python_build.sh /adbc /adbc/build && /adbc/ci/scrip [...]
+ /bin/bash -c 'git config --global --add safe.directory /adbc && source /opt/conda/etc/profile.d/conda.sh && mamba create -y -n adbc -c conda-forge go --file /adbc/ci/conda_env_cpp.txt --file /adbc/ci/conda_env_docs.txt --file /adbc/ci/conda_env_java.txt --file /adbc/ci/conda_env_python.txt && conda activate adbc && /adbc/ci/scripts/cpp_build.sh /adbc /adbc/build && /adbc/ci/scripts/go_build.sh /adbc /adbc/build && /adbc/ci/scripts/python_build.sh /adbc /adbc/build && /adbc/ci/scrip [...]
################################### Java ###################################
diff --git a/dev/release/post-11-announce.sh b/dev/release/post-11-announce.sh
index b697c8606..4ff09f9c8 100755
--- a/dev/release/post-11-announce.sh
+++ b/dev/release/post-11-announce.sh
@@ -41,7 +41,7 @@ separately: some packages are on version ${VERSION_NATIVE} and others
are on version ${VERSION_JAVA}.
Release artifacts can be downloaded from:
-https://arrow.apache.org/adbc/current/driver/installation.html
+https://arrow.apache.org/adbc/current/installation.html
This release contains ${RESOLVED_ISSUES} bug fixes and improvements.
Release notes are available at:
diff --git a/dev/release/rat_exclude_files.txt b/dev/release/rat_exclude_files.txt
index 268fd51be..6eaff4062 100644
--- a/dev/release/rat_exclude_files.txt
+++ b/dev/release/rat_exclude_files.txt
@@ -25,6 +25,7 @@ csharp/*.props
dev/release/rat_exclude_files.txt
docs/source/format/*.drawio
docs/source/format/*.svg
+docs/source/_static/*.svg
docs/source/*/*.stdout.txt
filtered_rat.txt
go/adbc/drivermgr/arrow-adbc/adbc.h
diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css
index acfd176c6..c3fc8aa95 100644
--- a/docs/source/_static/css/custom.css
+++ b/docs/source/_static/css/custom.css
@@ -35,3 +35,113 @@ figcaption {
h1, h2, h3, h4 {
text-wrap: balance;
}
+
+/* Two-part package badges (shields.io style) */
+.package-badge-link {
+ text-decoration: none;
+ display: inline-block;
+ vertical-align: middle;
+ margin-right: 0.25rem;
+ margin-bottom: 0.25rem;
+ max-width: 100%;
+}
+
+.package-badge-container {
+ display: inline-flex;
+ border-radius: 0.25rem;
+ overflow: hidden;
+ font-size: 0.75rem;
+ line-height: 1;
+ white-space: nowrap;
+ max-width: 100%;
+}
+
+.package-badge-left {
+ background-color: #555;
+ color: white;
+ padding: 0.25em 0.4em;
+ font-weight: 600;
+ flex-shrink: 0;
+}
+
+.package-badge-right {
+ background-color: #007ec6;
+ color: white;
+ padding: 0.25em 0.4em;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ min-width: 0;
+}
+
+/* Compact driver cards only */
+.driver-cards .sd-card-body {
+ padding: 0.75rem 0.5rem !important;
+}
+
+.driver-cards .sd-card-body p {
+ margin-bottom: 0.15rem;
+}
+
+.driver-cards .sd-card-body p:last-child {
+ margin-bottom: 0;
+}
+
+/* Add spacing between the icon and the text in card titles */
+.sd-card-title .sd-octicon {
+ margin-right: 0.5rem;
+}
+
+/* Icon-only links (e.g. GitHub source links in the driver table) */
+a.icon-link {
+ color: var(--color-foreground-muted);
+ font-size: 1.15rem;
+ text-decoration: none;
+}
+
+a.icon-link:hover {
+ color: var(--color-brand-content);
+}
+
+/* Unified driver table: keep it compact and scannable */
+table.driver-table {
+ width: 100%;
+}
+
+table.driver-table td,
+table.driver-table th {
+ vertical-align: middle;
+}
+
+/* Install column reads as a command, not prose */
+table.driver-table td code,
+table.driver-table td .docutils.literal {
+ white-space: nowrap;
+}
+
+/* Center the icon in the Repo column (last column) of the main driver table */
+table.driver-table-main td:last-child,
+table.driver-table-main th:last-child {
+ text-align: center;
+}
+
+/* Secondary hint text in a table header (e.g. "(click for docs)") */
+table.driver-table th .th-hint {
+ font-weight: normal;
+ font-size: 0.8em;
+ opacity: 0.75;
+}
+
+/* Shrink the sidebar logo slightly */
+.sidebar-logo {
+ max-width: 95%;
+ margin-left: 0;
+ margin-right: auto;
+}
+
+/* Emphasize and align the documentation title in the sidebar */
+.sidebar-brand-text {
+ font-weight: 700;
+ margin-left: 12px;
+ font-size: 1.6rem;
+}
diff --git a/docs/source/_static/logo-dark.png b/docs/source/_static/logo-dark.png
index 1cf65f079..40f4a20e1 100644
Binary files a/docs/source/_static/logo-dark.png and b/docs/source/_static/logo-dark.png differ
diff --git a/docs/source/_static/logo-light.png b/docs/source/_static/logo-light.png
index ccf6c61aa..2f35a8fdf 100644
Binary files a/docs/source/_static/logo-light.png and b/docs/source/_static/logo-light.png differ
diff --git a/docs/source/_static/logo.svg b/docs/source/_static/logo.svg
new file mode 100644
index 000000000..58de1b601
--- /dev/null
+++ b/docs/source/_static/logo.svg
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 330" fill="currentColor">
+ <path d="M505.93 24.13A.42.42 0 0 1 506.646985 23.833015L647.516985 164.703015A.42.42 0 0 1 647.516985 165.296985L506.646985 306.166985A.42.42 0 0 1 505.93 305.87L505.93 249.52A.42.42 0 0 1 506.053015 249.223015L590.27603 165 506.053015 80.776985A.42.42 0 0 1 505.93 80.48Z"/>
+ <path d="M604.54 24.13A.42.42 0 0 1 605.256985 23.833015L746.126985 164.703015A.42.42 0 0 1 746.126985 165.296985L605.256985 306.166985A.42.42 0 0 1 604.54 305.87L604.54 249.52A.42.42 0 0 1 604.663015 249.223015L688.88603 165 604.663015 80.776985A.42.42 0 0 1 604.54 80.48Z"/>
+ <path d="M703.15 24.13A.42.42 0 0 1 703.866995 23.833026L844.726995 164.703026A.42.42 0 0 1 844.726995 165.296974L703.866995 306.166974A.42.42 0 0 1 703.15 305.87L703.15 249.52A.42.42 0 0 1 703.273015 249.223015L787.49603 165 703.273015 80.776985A.42.42 0 0 1 703.15 80.48Z"/>
+ <path d="M70.33,66.8l-11.01,30.3h-4.49l12.67-33.25h2.9l-.06,2.94ZM79.54,97.1l-11.03-30.3-.07-2.94h2.9l12.72,33.25h-4.52ZM78.97,84.79v3.61h-18.67v-3.61h18.67Z"/>
+ <path d="M100.78,84.06h-8.88v-3.58h9.38s.49-.03.49-.03l.47-.04.45-.06.43-.07.41-.09.39-.1.37-.13.34-.14.33-.16h0l.31-.17.3-.18.27-.2.26-.21.24-.22.23-.23.2-.25.19-.26.17-.27.16-.29h0l.14-.3.13-.31.11-.31.1-.32.08-.33.07-.34.05-.34.03-.35.02-.36v-.38h0v-.34s-.03-.34-.03-.34l-.03-.34-.05-.33-.07-.32-.08-.32-.1-.31-.11-.31-.13-.31-.14-.31h0l-.16-.3-.17-.28-.19-.27-.2-.26-.23-.25-.24-.23-.26-.23-.27-.21-.3-.2-.31-.19h0l-.33-.18-.34-.16-.37-.14-.39-.13-.41-.1-.43-.09-.45-.06-.47-.05-.49-.03 [...]
+ <path d="M130.33,66.8l-11,30.3h-4.5l12.67-33.25h2.9l-.07,2.94ZM139.55,97.1l-11.03-30.3-.06-2.94h2.9l12.72,33.25h-4.52ZM138.98,84.79v3.61h-18.68v-3.61h18.68Z"/>
+ <path d="M168.6,86.53h4.38l-.08.63-.1.61-.13.59-.15.59-.17.57-.19.56-.22.54-.23.53-.26.52-.28.51h0l-.31.49-.33.47-.35.45-.38.42-.4.41-.42.38-.45.37-.47.34-.5.32-.52.31h0l-.55.27-.57.25-.6.21-.63.19-.65.16-.68.13-.71.1-.73.07-.76.04-.79.02h-.58s-.56-.04-.56-.04l-.56-.05-.55-.08-.53-.1-.53-.12-.52-.14-.5-.16-.5-.19-.48-.21h0l-.47-.23-.45-.24-.45-.27-.43-.28-.41-.31-.4-.32-.39-.34-.38-.35-.36-.38-.35-.4h0l-.33-.41-.32-.43-.31-.45-.29-.46-.27-.48-.26-.49-.23-.51-.23-.52-.21-.55-.2-.56h0l-. [...]
+ <path d="M200.68,78.15v3.58h-17.99v-3.58h17.99ZM183.37,63.86v33.25h-4.41v-33.25h4.41ZM204.51,63.86v33.25h-4.38v-33.25h4.38Z"/>
+ <path d="M233.44,93.52v3.58h-17.6v-3.58h17.6ZM216.73,63.86v33.25h-4.41v-33.25h4.41ZM231.11,78.15v3.58h-15.28v-3.58h15.28ZM233.21,63.86v3.61h-17.37v-3.61h17.37Z"/>
+ <path d="M116.88,213.56h0l-.27-.02-.23-.04-.23-.07-.2-.09-.18-.12-.17-.15-.14-.17-.13-.2-.11-.23-.09-.25-4.05-13.2h0l-.05-.1-.05-.09-.06-.08-.06-.07-.06-.06-.07-.05-.07-.04-.08-.02-.08-.02h-.08s-33.14,0-33.14,0h-.08s-.08.02-.08.02l-.08.02-.07.04-.07.05-.06.06-.06.07-.06.08-.05.09-.05.1-3.91,13.2h0l-.09.25-.11.23-.13.2-.15.17-.16.15-.19.12-.2.09-.22.07-.24.04-.26.02h-17.27s-.15-.02-.15-.02l-.14-.02-.13-.02-.13-.04-.12-.05-.11-.05-.1-.06-.09-.07-.08-.08h0l-.08-.11-.06-.12-.05-.13-.03-.13 [...]
+ <path d="M199.06,213.56h0l-.26-.02-.25-.03-.23-.06-.21-.09-.2-.11-.18-.13-.16-.16-.15-.18-.13-.21-.12-.23-16.84-37.31h0l-.05-.1-.06-.09-.06-.08-.08-.07-.08-.06-.08-.05-.09-.04-.09-.02-.1-.02h-.1s-12.53,0-12.53,0h-.13s-.12.02-.12.02l-.1.04-.09.05-.07.05-.06.08-.05.09-.03.1-.02.12v.13s0,36.77,0,36.77h0v.13s-.02.13-.02.13l-.02.13-.04.13-.05.13-.06.12-.07.12-.08.12-.09.11-.1.11h0l-.08.08-.09.07-.09.06-.1.05-.1.05-.11.04-.12.02-.12.02h-.13s-.13.02-.13.02h-15.9s-.13-.02-.13-.02l-.13-.02-.13- [...]
+ <path d="M281.77,213.56h0l-.26-.02-.24-.03-.23-.06-.21-.09-.2-.11-.18-.13-.16-.16-.15-.18-.13-.21-.12-.23-16.83-37.31h0l-.06-.1-.05-.09-.07-.08-.07-.07-.08-.06-.09-.05-.09-.04-.09-.02-.1-.02h-.11s-12.53,0-12.53,0h-.13s-.11.02-.11.02l-.1.04-.09.05-.07.05-.06.08-.05.09-.03.1-.02.12v.13s0,36.77,0,36.77h0v.13l-.02.13-.03.13-.04.13-.05.13-.05.12-.07.12-.09.12-.09.11-.1.11h0l-.09.08-.09.07-.1.06-.09.05-.11.05-.11.04-.12.02-.12.02h-.13s-.13.02-.13.02h-15.89s-.13-.02-.13-.02l-.13-.02-.13-.02-. [...]
+ <path d="M346.3,215.04h0l-2.08-.04-2.03-.13-1.98-.21-1.93-.31-1.88-.38-1.84-.48-1.78-.56-1.74-.64-1.69-.74-1.64-.82h0l-1.55-.89-1.49-.96-1.42-1.03-1.35-1.1-1.27-1.17-1.21-1.24-1.13-1.3-1.06-1.36-.99-1.44-.92-1.5h0l-.85-1.58-.76-1.64-.67-1.67-.58-1.72-.49-1.77-.41-1.82-.31-1.86-.23-1.9-.13-1.96-.04-2v-28.83h0l.04-1.97.13-1.93.23-1.88.31-1.83.41-1.79.49-1.74.58-1.7.67-1.65.76-1.6.85-1.56h0l.92-1.5.99-1.42,1.06-1.36,1.13-1.29,1.21-1.22,1.27-1.15,1.35-1.08,1.42-1.01,1.49-.95,1.55-.87h0l1.6 [...]
+ <path d="M417.3,213.56h0l-.29-.02-.27-.04-.24-.07-.22-.09-.2-.12-.18-.15-.16-.17-.13-.2-.12-.23-.09-.25-23.85-91.21-.13-.54h0v-.23s.05-.21.05-.21l.08-.18.1-.16.13-.13.16-.11.19-.09.23-.06.25-.03.28-.02h16.7l.27.02.23.04.23.07.2.09.18.12.17.15.14.17.13.2.11.23.09.25,12.8,54.83h0l.02.1.03.09.03.08.04.07.04.06.04.05.05.04.05.02.05.02h.05s.05,0,.05,0l.05-.02.05-.02.05-.04.04-.05.04-.06.04-.07.03-.08.03-.09.03-.1,12.39-54.7h0l.09-.27.11-.26.13-.22.15-.2.16-.16.19-.13.2-.1.22-.07.24-.05.26-. [...]
+</svg>
diff --git a/docs/source/client_libraries.rst b/docs/source/client_libraries.rst
new file mode 100644
index 000000000..eebf76bd2
--- /dev/null
+++ b/docs/source/client_libraries.rst
@@ -0,0 +1,109 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied. See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+================
+Client Libraries
+================
+
+ADBC client libraries let you connect to databases and execute queries from your language of choice.
+Because most ADBC :doc:`drivers <driver/index>` expose the same :doc:`standard C ABI <format/specification>`, a single client library can generally use drivers written in any language through the same client API.
+
+.. note::
+
+ On this page we use the terms **client library** and **driver manager**
+ interchangeably. More precisely, the driver manager is the part of a client
+ library that dynamically loads ADBC driver shared libraries and forwards your
+ calls to them; the client library wraps that machinery in an API that feels
+ idiomatic in your language.
+
+ The package names are, unfortunately, not consistent about this. Some are
+ named for the driver manager (Python's ``adbc-driver-manager``, R's
+ ``adbcdrivermanager``), while others are named for ADBC itself (C#'s
+ ``Apache.Arrow.Adbc.Client``, Ruby's ``red-adbc``). They all give you the
+ same thing: a way to load drivers and talk to databases from your language.
+
+Packages
+========
+
+The client library package for each language:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 15 15 30 40
+
+ * - Language
+ - Package Manager
+ - Package
+ - Documentation
+ * - Python
+ - pip / conda
+ - ``adbc-driver-manager``
+ - :doc:`Python Quickstart <python/quickstart>`
+ * - C/C++
+ - various
+ - See quickstart
+ - :doc:`C/C++ Quickstart <cpp/quickstart>`
+ * - C#
+ - dotnet
+ - ``Apache.Arrow.Adbc.Client``
+ - :doc:`C#/.NET <csharp/index>`
+ * - Go
+ - go
+ - ``github.com/apache/arrow-adbc/go/adbc``
+ - `Go Documentation ↗ <https://pkg.go.dev/github.com/apache/arrow-adbc/go/adbc>`__
+ * - Java
+ - Maven
+ - ``org.apache.arrow.adbc``: ``adbc-core``, ``adbc-driver-manager``, ``adbc-driver-jni``
+ - :doc:`Java Quickstart <java/quickstart>`
+ * - JavaScript / TypeScript
+ - npm
+ - ``@apache-arrow/adbc-driver-manager``
+ - :doc:`JavaScript Quickstart <javascript/quickstart>`
+ * - R
+ - CRAN / conda
+ - ``adbcdrivermanager``
+ - :doc:`R <r/index>`
+ * - Ruby
+ - bundler
+ - ``red-adbc``
+ - :doc:`Ruby <ruby/index>`
+ * - Rust
+ - cargo
+ - ``adbc_core``, ``adbc_driver_manager``
+ - :doc:`Rust Quickstart <rust/quickstart>`
+
+Using a Client Library
+======================
+
+Client libraries provide a language-native interface on top of the ADBC API.
+They handle loading drivers, managing connections, and converting results into idiomatic types for each language.
+For example, Python exposes a `DBAPI 2.0 (PEP 249) <https://peps.python.org/pep-0249/>`__-style interface, Go uses ``database/sql``, and R uses DBI.
+
+A client library on its own can't talk to a database—it also needs a
+:doc:`driver <driver/index>` for the database you want to connect to.
+The client library loads the driver at runtime, so you install the client
+library once and then add a driver for each database you use.
+See :doc:`Drivers <driver/index>` for the full list of available drivers and how to install them.
+
+You may not need to use a client library directly at all: many higher-level
+tools, such as pandas and Polars, integrate with ADBC and use it under the hood.
+See :doc:`Tools & Integrations <integrations>` for more.
+
+More Information
+================
+
+- `ADBC Quickstarts <https://github.com/columnar-tech/adbc-quickstarts>`__ — simple, runnable examples for getting started in each of these languages, across a range of databases
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 5c5653d6c..91deff2c1 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -35,6 +35,8 @@ author = "the Apache Arrow Developers"
release = "24 (dev)"
# Needed to generate version switcher
version = release
+# Override Sphinx's default title to capitalize "Documentation"
+html_title = f"{project} {release} Documentation"
# For linking to latest downloads
latest_release = "23"
@@ -58,6 +60,7 @@ extensions = [
"sphinx_copybutton",
"sphinx_design",
"sphinxext.opengraph",
+ "sphinx_reredirects",
]
templates_path = ["_templates"]
@@ -128,10 +131,10 @@ nitpick_ignore = [
doctest_global_setup = """
try:
- import adbc_driver_sqlite
- import adbc_driver_sqlite.dbapi # noqa: F401
+ import adbc_driver_manager
+ import adbc_driver_manager.dbapi # noqa: F401
except ImportError:
- adbc_driver_sqlite = None
+ adbc_driver_manager = None
"""
# -- Options for HTML output -------------------------------------------------
@@ -196,3 +199,13 @@ if "dev" in release:
else:
ogp_site_url = f"https://arrow.apache.org/adbc/{release}/"
ogp_image = "_static/banner.png"
+
+# -- Options for sphinx_reredirects ------------------------------------------
+
+redirects = {
+ "driver/status": "./index.html",
+ "driver/snowflake": "./index.html",
+ "driver/installation": "../installation.html",
+ "python/api/adbc_driver_snowflake": "../../driver/index.html",
+ "python/api/adbc_driver_bigquery": "../../driver/index.html",
+}
diff --git a/docs/source/connection_profiles.rst b/docs/source/connection_profiles.rst
new file mode 100644
index 000000000..7dee9263a
--- /dev/null
+++ b/docs/source/connection_profiles.rst
@@ -0,0 +1,191 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied. See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+===================
+Connection Profiles
+===================
+
+An ADBC connection profile combines a driver name and database options into a reusable, named configuration stored in a TOML file.
+This keeps credentials and settings out of your application code.
+
+Here are example profiles for a few databases. Each sets ``driver`` to a driver
+name (see :doc:`Drivers <driver/index>`) and puts that driver's options under ``[Options]``.
+Secrets are injected from environment variables with ``{{ env_var(NAME) }}``
+rather than being written into the file:
+
+.. tab-set::
+
+ .. tab-item:: PostgreSQL
+
+ .. code-block:: toml
+
+ profile_version = 1
+ driver = "postgresql"
+
+ [Options]
+ uri = "postgresql://postgres:{{ env_var(PGPASSWORD) }}@localhost:5432/demo"
+
+ .. tab-item:: BigQuery
+
+ .. code-block:: toml
+
+ profile_version = 1
+ driver = "bigquery"
+
+ [Options]
+ "adbc.bigquery.sql.project_id" = "my-gcp-project"
+ "adbc.bigquery.sql.dataset_id" = "bigquery-public-data"
+
+ .. tab-item:: Redshift
+
+ .. code-block:: toml
+
+ profile_version = 1
+ driver = "redshift"
+
+ [Options]
+ uri = "postgresql://localhost:5439"
+ "redshift.cluster_type" = "redshift-serverless"
+ "redshift.workgroup_name" = "my-workgroup"
+ "redshift.db_name" = "sample_data_dev"
+
+ .. tab-item:: Snowflake
+
+ .. code-block:: toml
+
+ profile_version = 1
+ driver = "snowflake"
+
+ [Options]
+ username = "MYUSER"
+ "adbc.snowflake.sql.auth_type" = "auth_jwt"
+ "adbc.snowflake.sql.client_option.jwt_private_key" = "/path/to/rsa_key.p8"
+ "adbc.snowflake.sql.account" = "ACCOUNT-IDENT"
+ "adbc.snowflake.sql.db" = "SNOWFLAKE_SAMPLE_DATA"
+ "adbc.snowflake.sql.schema" = "TPCH_SF1"
+ "adbc.snowflake.sql.warehouse" = "MY_WAREHOUSE"
+ "adbc.snowflake.sql.role" = "MY_ROLE"
+
+ .. tab-item:: StarRocks
+
+ .. code-block:: toml
+
+ profile_version = 1
+ driver = "flightsql"
+
+ [Options]
+ uri = "grpc://localhost:9408"
+ username = "root"
+ password = "{{ env_var(STARROCKS_PASSWORD) }}"
+
+Save the profile as a ``.toml`` file (for example ``myprofile.toml``) in the
+user configuration directory, where the client library or driver manager
+looks for it by name:
+
+- **Linux**: ``~/.config/adbc/profiles/``
+- **macOS**: ``~/Library/Application Support/ADBC/Profiles/``
+- **Windows**: ``%LOCALAPPDATA%\ADBC\Profiles\``
+
+Other locations are also searched; see
+:ref:`Profile Search Locations <profile-search-locations>` for the full list
+and precedence.
+
+Your application then references the profile at connection time, and the client
+library or driver manager loads it automatically. Point the ``uri`` option at
+the profile name—the TOML file's name without the ``.toml`` extension—using
+the ``profile://`` scheme:
+
+.. tab-set::
+
+ .. tab-item:: C/C++
+
+ .. code-block:: cpp
+
+ AdbcDatabase database = {};
+ AdbcDatabaseNew(&database, &error);
+ AdbcDatabaseSetOption(&database, "uri", "profile://myprofile", &error);
+ AdbcDriverManagerDatabaseSetLoadFlags(&database, ADBC_LOAD_FLAG_DEFAULT, &error);
+ AdbcDatabaseInit(&database, &error);
+
+ .. tab-item:: Go
+
+ .. code-block:: go
+
+ var drv drivermgr.Driver
+
+ db, err := drv.NewDatabase(map[string]string{
+ "uri": "profile://myprofile",
+ })
+
+ .. tab-item:: Java
+
+ .. code-block:: java
+
+ Map<String, Object> params = new HashMap<>();
+ JniDriver.PARAM_URI.set(params, "profile://myprofile");
+
+ AdbcDatabase db =
+ AdbcDriverManager.getInstance().connect(DRIVER_FACTORY, allocator, params);
+
+ .. tab-item:: JavaScript
+
+ .. code-block:: javascript
+
+ import { AdbcDatabase } from '@apache-arrow/adbc-driver-manager';
+
+ const db = new AdbcDatabase({
+ driver: 'profile://myprofile',
+ });
+
+ .. tab-item:: Python
+
+ .. code-block:: python
+
+ from adbc_driver_manager import dbapi
+
+ with dbapi.connect(uri="profile://myprofile") as con:
+ ...
+
+ .. tab-item:: R
+
+ .. code-block:: r
+
+ library(adbcdrivermanager)
+
+ db <- adbc_database_init(uri = "profile://myprofile")
+ con <- adbc_connection_init(db)
+
+ .. tab-item:: Ruby
+
+ .. code-block:: ruby
+
+ database = ADBC::Database.new
+ database.set_option("uri", "profile://myprofile")
+ database.set_load_flags(ADBC::LoadFlags::DEFAULT)
+ database.init
+
+ .. tab-item:: Rust
+
+ .. code-block:: rust
+
+ let uri = "profile://myprofile";
+ let db = ManagedDatabase::from_uri(
+ uri, None, AdbcVersion::default(), LOAD_FLAG_DEFAULT, None,
+ )?;
+
+You can also pass an absolute path to a profile file instead of a name.
+For full details on the profile file format, search paths, option precedence, and how to implement a custom profile provider, see :doc:`format/connection_profiles`.
diff --git a/docs/source/cpp/recipe/quickstart.cc b/docs/source/cpp/recipe/quickstart.cc
index 1f726ee69..36a5e19d6 100644
--- a/docs/source/cpp/recipe/quickstart.cc
+++ b/docs/source/cpp/recipe/quickstart.cc
@@ -32,9 +32,28 @@
///
/// .. code-block:: shell
///
-/// mamba install cmake compilers libadbc-driver-manager libadbc-driver-sqlite
+/// mamba install cmake compilers libadbc-driver-manager
+///
+/// Installing Drivers
+/// ------------------
+///
+/// See :ref:`driver-table-install` for instructions on installing
+/// ADBC drivers for the database you want to connect to. For the
+/// example below, you could install `dbc <dbc_>`_ and then use dbc
+/// to install the SQLite driver and its manifest in the user
+/// configuration directory where the driver manager library will
+/// search for it:
+///
+/// .. code-block:: shell
+///
+/// dbc install --level user sqlite
+///
+/// You can also build drivers from source or use other installation
+/// methods. See the :doc:`driver documentation </driver/index>` for
+/// more details.
///
/// .. _conda-forge: https://conda-forge.org/
+/// .. _dbc: https://docs.columnar.tech/dbc/
/// Building
/// ========
@@ -51,8 +70,8 @@
///
/// .. _CMake: https://cmake.org/
-/// Using ADBC
-/// ==========
+/// Basic Example
+/// =============
///
/// Let's start with some includes:
@@ -63,6 +82,7 @@
#include <iostream>
#include <arrow-adbc/adbc.h>
+#include <arrow-adbc/adbc_driver_manager.h>
#include <nanoarrow.h>
/// Then we'll add some (very basic) error checking helpers.
@@ -110,7 +130,10 @@ int main() {
CHECK_ADBC(AdbcDatabaseNew(&database, &error));
/// The way the driver manager knows what driver we want is via the
/// ``driver`` option.
- CHECK_ADBC(AdbcDatabaseSetOption(&database, "driver", "adbc_driver_sqlite", &error));
+ CHECK_ADBC(AdbcDatabaseSetOption(&database, "driver", "sqlite", &error));
+ /// We also need to enable searching for driver manifests.
+ CHECK_ADBC(
+ AdbcDriverManagerDatabaseSetLoadFlags(&database, ADBC_LOAD_FLAG_DEFAULT, &error));
CHECK_ADBC(AdbcDatabaseInit(&database, &error));
/// Creating a Connection
diff --git a/docs/source/csharp/index.rst b/docs/source/csharp/index.rst
index dd636fdbf..d5712770e 100644
--- a/docs/source/csharp/index.rst
+++ b/docs/source/csharp/index.rst
@@ -19,7 +19,73 @@
C#/.NET
=======
-The ADBC C# libraries are under development, supporting:
+The ADBC C#/.NET libraries support three different ways of using ADBC:
-- A native driver to Google BigQuery
-- A way to import/export native (C/C++) drivers
+- Native C# drivers for databases like Google BigQuery
+- Bindings packages that wrap individual drivers such as the Snowflake Go driver
+- A driver manager for loading ADBC drivers written in other languages at runtime
+
+Here we'll briefly tour basic features using the driver manager and the PostgreSQL driver.
+
+Installation
+============
+
+.. code-block:: shell
+
+ dotnet add package Apache.Arrow.Adbc
+
+Installing Drivers
+------------------
+
+See :ref:`driver-table-install` for instructions on installing ADBC drivers for
+the database you want to connect to. For the example below, you could install
+`dbc <https://docs.columnar.tech/dbc>`__ and then install the PostgreSQL driver with:
+
+.. code-block:: shell
+
+ dbc install postgresql
+
+Usings
+------
+
+.. code-block:: csharp
+
+ using System.Collections.Generic;
+ using Apache.Arrow;
+ using Apache.Arrow.Adbc;
+ using Apache.Arrow.Adbc.DriverManager;
+ using Apache.Arrow.Ipc;
+
+Basic Usage
+===========
+
+.. code-block:: csharp
+
+ using AdbcDriver driver = AdbcDriverManager.FindLoadDriver(
+ "postgresql",
+ loadOptions: AdbcLoadFlags.Default);
+
+ using AdbcDatabase db = driver.Open(new Dictionary<string, string>
+ {
+ ["uri"] = "postgresql://localhost:5432/postgres",
+ });
+
+ using AdbcConnection conn = db.Connect(null);
+ using AdbcStatement stmt = conn.CreateStatement();
+
+ stmt.SqlQuery = "SELECT * FROM foo";
+
+ QueryResult result = stmt.ExecuteQuery();
+ using IArrowArrayStream stream = result.Stream!;
+
+ while (true)
+ {
+ using Apache.Arrow.RecordBatch batch = await stream.ReadNextRecordBatchAsync();
+ if (batch == null) break;
+ // process batch
+ }
+
+Next Steps
+==========
+
+- Explore more C# examples in the `adbc-quickstarts repository <https://github.com/columnar-tech/adbc-quickstarts/tree/main/csharp>`_
diff --git a/docs/source/driver/authoring.rst b/docs/source/driver/authoring.rst
index bd11493ef..526a4e930 100644
--- a/docs/source/driver/authoring.rst
+++ b/docs/source/driver/authoring.rst
@@ -19,26 +19,104 @@
Writing New Drivers
===================
-Currently, new drivers can be written in C#, C/C++, Go, and Java. A driver
-written in C/C++ or Go can be used from either of those languages, as well as
-C#, Python, R, and Ruby. (C# can experimentally export drivers to the same
-set of languages as well.) The Rust API definitions for ADBC are still under
-development, but we plan for them to be on par with C#, C/C++, and Go in this
-respect.
-
-It is so far preferable to write new drivers in Go. C/C++ have had issues
-with dependencies and in particular some not uncommon dependencies in that
-ecosystem tend to cause conflicts when loaded into Python processes and
-elsewhere. (For example, the ADBC Flight SQL driver was originally written in
-C++ but would have conflicted with the grpcio and pyarrow Python packages.)
-It also tends to be easier for us to package and distribute additional Go
-libraries than it is for C/C++.
-
-In Go, some frameworks are available for driver
-authors. `go/adbc/driver/internal/driverbase`_ manages much of the boilerplate
-and basic state management for drivers. `go/adbc/pkg`_ can template out a C
-ABI wrapper around the Go driver. Especially if the driver is planned to go
-upstream, we recommend driver authors consider using these frameworks.
-
-.. _go/adbc/driver/internal/driverbase: https://github.com/apache/arrow-adbc/tree/main/go/adbc/driver/internal/driverbase
-.. _go/adbc/pkg: https://github.com/apache/arrow-adbc/tree/main/go/adbc/pkg
+Interested in building an ADBC driver? You can develop and host a driver
+wherever you like—it just needs to implement the :doc:`ADBC standard
+<../format/specification>`. That said, the best place to start is the **ADBC
+Driver Foundry**, a community project that hosts most ADBC drivers and provides
+the frameworks, templates, testing tools, and distribution infrastructure for
+building and shipping them. You can develop your driver entirely within the
+Foundry, or keep it in your own repository and use the Foundry only for
+distribution and other shared infrastructure.
+
+.. button-link:: https://docs.adbc-drivers.org/building-drivers/
+ :color: primary
+
+ Building Drivers guide (ADBC Driver Foundry) :octicon:`link-external`
+
+The rest of this page gives a brief orientation. For anything beyond
+that—project templates, frameworks, validation tests, packaging, and
+distribution—follow the guide above.
+
+.. note::
+
+ The ADBC project itself focuses on the :doc:`ADBC standard
+ <../format/specification>` and :doc:`client libraries <../client_libraries>`,
+ not on building and distributing drivers. In most cases, new drivers should
+ be developed in the ADBC Driver Foundry, not in the ``apache/arrow-adbc``
+ repository.
+
+ The ADBC Driver Foundry is an independent community project, separate from
+ the Apache Arrow project.
+
+What Language Should I Use?
+===========================
+
+Most ADBC drivers are built as shared libraries (``.so`` / ``.dll`` /
+``.dylib``) in a portable systems language (like C/C++, Go, or Rust). A
+single shared library can be loaded by any :doc:`ADBC client library
+<../client_libraries>` and used from any language, so the implementation
+language does not affect which languages can use the driver.
+
+- **Go** and **Rust** are the most common choices, and have the most examples,
+ templates, and framework tooling available (see below). If you're starting
+ fresh, one of these is usually the easiest path.
+- **C/C++** also works, but the build is more involved, and C/C++ drivers have
+ historically hit dependency conflicts inside host processes.
+
+In principle a shared-library driver can be written in other languages, such as
+C# or Java, but in practice this has not been done.
+
+Separately, a driver can be built as a language-specific package that runs
+directly on a managed runtime (for example, a NuGet package for .NET or a Maven
+package for the JVM) rather than as a loadable shared library. Such a driver can
+only be used from that runtime. This is less common, but the Driver Foundry can
+accommodate it too.
+
+Driver Frameworks
+=================
+
+The ADBC Driver Foundry maintains frameworks for Go and Rust that provide base
+implementations of the ADBC interfaces, so you implement only what's specific to
+your database:
+
+- **Go**: `driverbase-go <https://github.com/adbc-drivers/driverbase-go>`__
+- **Rust**: `driverbase-rs <https://github.com/adbc-drivers/driverbase-rs>`__
+
+For Rust, `template-rs <https://github.com/adbc-drivers/template-rs>`__
+generates a ready-to-build driver crate to start from.
+
+.. note::
+
+ A Go ``driverbase`` also exists in this repository, under
+ `go/adbc/driver/internal/driverbase
+ <https://github.com/apache/arrow-adbc/tree/main/go/adbc/driver/internal/driverbase>`__.
+ It remains only for historical reasons (the Flight SQL driver depends on it)
+ and is not intended for new work. New Go drivers should use `driverbase-go
+ <https://github.com/adbc-drivers/driverbase-go>`__ instead.
+
+Why the Driver Foundry, Not This Repository?
+============================================
+
+.. _authoring-why-foundry:
+
+Building and distributing driver binaries is a non-goal of the core ADBC
+project, and routing every driver through ``apache/arrow-adbc`` bottlenecks
+on its maintainers. The Driver Foundry instead gives each driver its own
+repository and maintainers, while its shared frameworks and validation suite
+keep drivers consistent and standards-conformant. It also handles testing,
+security vulnerability scanning and patching, packaging, and distribution—including
+prebuilt, signed, notarized binaries on Columnar's
+`ADBC driver registry <https://dbc-cdn.columnar.tech/>`__.
+Vendors such as dbt Labs and Microsoft build on Foundry-maintained drivers.
+
+The ADBC maintainers generally decline pull requests adding new drivers to
+``apache/arrow-adbc`` and direct you instead to the Foundry.
+
+Columnar's ADBC driver registry, like the Foundry, is maintained independently
+of the Apache Arrow project.
+
+.. note::
+
+ A small number of drivers (PostgreSQL, SQLite, and Flight SQL) are still
+ maintained in this repository for historical reasons. See :doc:`Drivers
+ <index>` for the full list of available drivers and who maintains each one.
diff --git a/docs/source/driver/bigquery.rst b/docs/source/driver/bigquery.rst
index 71be05542..938c3ce63 100644
--- a/docs/source/driver/bigquery.rst
+++ b/docs/source/driver/bigquery.rst
@@ -15,13 +15,15 @@
.. specific language governing permissions and limitations
.. under the License.
-================
-BigQuery Support
-================
+:orphan:
+
+=============
+BigQuery (C#)
+=============
.. adbc_driver_status:: ../../../csharp/src/Drivers/BigQuery/readme.md
-The C# BigQuery Driver (Beta) is available as a `NuGet package <https://www.nuget.org/packages/Apache.Arrow.Adbc.Drivers.BigQuery>`__
+The C# BigQuery Driver (Beta) is available as a `NuGet package <https://www.nuget.org/packages/Apache.Arrow.Adbc.Drivers.BigQuery>`__.
C# BigQuery Driver
==================
diff --git a/docs/source/driver/duckdb.rst b/docs/source/driver/duckdb.rst
index 8658b4759..e1e3fcb1a 100644
--- a/docs/source/driver/duckdb.rst
+++ b/docs/source/driver/duckdb.rst
@@ -15,6 +15,8 @@
.. specific language governing permissions and limitations
.. under the License.
+:orphan:
+
==============
DuckDB Support
==============
diff --git a/docs/source/driver/flight_sql.rst b/docs/source/driver/flight_sql.rst
index 29f871ec7..a53c833da 100644
--- a/docs/source/driver/flight_sql.rst
+++ b/docs/source/driver/flight_sql.rst
@@ -15,6 +15,8 @@
.. specific language governing permissions and limitations
.. under the License.
+:orphan:
+
=================
Flight SQL Driver
=================
diff --git a/docs/source/driver/index.rst b/docs/source/driver/index.rst
new file mode 100644
index 000000000..5b5564782
--- /dev/null
+++ b/docs/source/driver/index.rst
@@ -0,0 +1,285 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied. See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+=======
+Drivers
+=======
+
+.. |click-for-docs| raw:: html
+
+ <span class="th-hint">(click for docs)</span>
+
+.. |click-for-readme| raw:: html
+
+ <span class="th-hint">(click for README)</span>
+
+An ADBC driver lets you connect to a database, run queries, and exchange data in
+Arrow format.
+
+.. _driver-table:
+
+Available Drivers
+=================
+
+ADBC drivers are typically built, distributed, and used as **shared libraries**
+(``.so``, ``.dll``, or ``.dylib`` files). One shared library works from any
+language. An application uses an
+:doc:`ADBC client library <../client_libraries>` to dynamically load the driver
+at runtime, no matter which language the driver was written in. Every
+driver in the table below is packaged this way.
+
+.. list-table::
+ :header-rows: 1
+ :widths: 38 22 22 18
+ :class: driver-table driver-table-main
+
+ * - Driver for |click-for-docs|
+ - Slug [#slug]_
+ - Maintainer [#maintainer]_
+ - Repo
+ * - `BigQuery <https://docs.adbc-drivers.org/drivers/bigquery/>`__
+ - ``bigquery``
+ - Foundry
+ - :iconlink:`fa-brands fa-github|https://github.com/adbc-drivers/bigquery|GitHub repository`
+ * - `ClickHouse <https://docs.adbc-drivers.org/drivers/clickhouse/>`__
+ - ``clickhouse``
+ - Vendor
+ - :iconlink:`fa-brands fa-github|https://github.com/adbc-drivers/clickhouse|GitHub repository`
+ * - `Databricks <https://docs.adbc-drivers.org/drivers/databricks/>`__
+ - ``databricks``
+ - Foundry
+ - :iconlink:`fa-brands fa-github|https://github.com/adbc-drivers/databricks|GitHub repository`
+ * - `Apache DataFusion <https://docs.adbc-drivers.org/drivers/datafusion/>`__
+ - ``datafusion``
+ - Foundry
+ - :iconlink:`fa-brands fa-github|https://github.com/adbc-drivers/datafusion|GitHub repository`
+ * - :doc:`DuckDB <duckdb>` [#duckdb]_
+ - ``duckdb``
+ - Vendor
+ - :iconlink:`fa-brands fa-github|https://github.com/duckdb/duckdb|GitHub repository`
+ * - `Exasol <https://docs.adbc-drivers.org/drivers/exasol/>`__
+ - ``exasol``
+ - Vendor
+ - :iconlink:`fa-brands fa-github|https://github.com/exasol/adbc-driver-exasol|GitHub repository`
+ * - :doc:`Apache Arrow Flight SQL <flight_sql>` [#compat-flightsql]_
+ - ``flightsql``
+ - ASF
+ - :iconlink:`fa-brands fa-github|https://github.com/apache/arrow-adbc/tree/main/go/adbc/driver/flightsql|GitHub repository`
+ * - `Microsoft SQL Server <https://docs.adbc-drivers.org/drivers/mssql/>`__
+ - ``mssql``
+ - Foundry
+ - :iconlink:`fa-brands fa-github|https://github.com/adbc-drivers/mssql|GitHub repository`
+ * - `MySQL/MariaDB <https://docs.adbc-drivers.org/drivers/mysql/>`__ [#compat-mysql]_
+ - ``mysql``
+ - Foundry
+ - :iconlink:`fa-brands fa-github|https://github.com/adbc-drivers/mysql|GitHub repository`
+ * - :doc:`PostgreSQL <postgresql>` [#compat-postgresql]_
+ - ``postgresql``
+ - ASF
+ - :iconlink:`fa-brands fa-github|https://github.com/apache/arrow-adbc/tree/main/c/driver/postgresql|GitHub repository`
+ * - `DuckDB Quack <https://docs.adbc-drivers.org/drivers/quack/>`__
+ - ``quack``
+ - Foundry
+ - :iconlink:`fa-brands fa-github|https://github.com/adbc-drivers/quack|GitHub repository`
+ * - `Amazon Redshift <https://docs.adbc-drivers.org/drivers/redshift/>`__
+ - ``redshift``
+ - Foundry
+ - :iconlink:`fa-brands fa-github|https://github.com/adbc-drivers/redshift|GitHub repository`
+ * - `SingleStore <https://docs.adbc-drivers.org/drivers/singlestore/>`__
+ - ``singlestore``
+ - Vendor
+ - :iconlink:`fa-brands fa-github|https://github.com/singlestore-labs/singlestore-adbc-connector|GitHub repository`
+ * - `Snowflake <https://docs.adbc-drivers.org/drivers/snowflake/>`__
+ - ``snowflake``
+ - Foundry
+ - :iconlink:`fa-brands fa-github|https://github.com/adbc-drivers/snowflake|GitHub repository`
+ * - `Apache Spark <https://docs.adbc-drivers.org/drivers/spark/>`__
+ - ``spark``
+ - Foundry
+ - :iconlink:`fa-brands fa-github|https://github.com/adbc-drivers/spark|GitHub repository`
+ * - :doc:`SQLite <sqlite>`
+ - ``sqlite``
+ - ASF
+ - :iconlink:`fa-brands fa-github|https://github.com/apache/arrow-adbc/tree/main/c/driver/sqlite|GitHub repository`
+ * - `Trino <https://docs.adbc-drivers.org/drivers/trino/>`__
+ - ``trino``
+ - Foundry
+ - :iconlink:`fa-brands fa-github|https://github.com/adbc-drivers/trino|GitHub repository`
+
+.. [#slug] The **slug** is the short name a driver is known by. It is the name
+ you hand to a :doc:`client library <../client_libraries>` to load the
+ driver—either as the driver name (``postgresql``) or as the URI scheme
+ (``postgresql://``). Given this name, the client library
+ :ref:`searches for a matching driver manifest <driver-manifest-discovery>`
+ (``postgresql.toml``) that tells it which shared library to load. The same
+ slug is what you pass when :ref:`installing a driver <driver-table-install>`.
+.. [#maintainer] See :ref:`Who Maintains These Drivers? <driver-table-maintainers>`
+ for what **ASF**, **Foundry**, and **Vendor** mean.
+.. [#duckdb] ADBC support is built directly into DuckDB; installing the
+ ``duckdb`` driver fetches a prebuilt binary. This driver is also compatible
+ with MotherDuck.
+.. [#compat-flightsql] This driver works with Flight SQL-compatible systems,
+ including Apache Doris, Dremio, GizmoSQL, InfluxDB, Sail, and StarRocks.
+.. [#compat-mysql] This driver also works with MySQL-compatible systems including
+ TiDB and Vitess.
+.. [#compat-postgresql] This driver also works with PostgreSQL wire
+ protocol-compatible systems, including CedarDB, Citus, CockroachDB, CrateDB,
+ Neon, ParadeDB, TimescaleDB, Yellowbrick, and YugabyteDB.
+
+.. _driver-table-install:
+
+Installing Drivers
+==================
+
+Pre-built binaries for the drivers in the table above are available from the
+`ADBC driver registry <https://dbc-cdn.columnar.tech>`__ hosted by
+`Columnar <https://columnar.tech>`__, a company active in ADBC driver
+development. Binaries are available for Windows (amd64), macOS (arm64), and
+Linux (amd64 and arm64), and are code-signed and notarized by Columnar.
+
+Users and applications can download a driver from the registry manually, or with
+the `dbc <https://docs.columnar.tech/dbc/>`__ command-line tool. With dbc
+installed, install any driver by its slug:
+
+.. code-block:: shell
+
+ dbc install <slug> # e.g. dbc install postgresql
+
+dbc installs both the driver's shared library and its
+:term:`driver manifest` to a location where an ADBC client library can find the
+driver by its slug.
+
+If you download a driver from the registry manually instead, you'll need to
+install the driver shared library file to the correct location yourself and
+create a driver manifest for it, or else pass the full path to the shared
+library in your application code, plus the entrypoint if the driver does not
+use the default entrypoint name.
+See :doc:`ADBC Driver Manager and Manifests <../format/driver_manifests>` for
+details.
+
+Some drivers are also published to language-specific package registries.
+Apache-maintained drivers are on
+:doc:`PyPI, conda-forge, CRAN, and more </installation>`; some vendor
+drivers list their own packages in each driver's documentation, linked from its
+name in the table above.
+
+.. note::
+ The `ADBC driver registry <https://dbc-cdn.columnar.tech/>`__ and the
+ `dbc <https://docs.columnar.tech/dbc/>`__ command-line tool for installing
+ drivers from it are provided by Columnar, and are maintained independently of
+ the Apache Arrow project.
+
+.. _driver-table-language-specific:
+
+Language-Specific Drivers
+=========================
+
+Some drivers are built and packaged for a specific language or runtime rather
+than as dynamically loadable shared libraries. They run directly on that runtime,
+without crossing an FFI / ABI boundary, and are distributed through its package
+registry. They can be used from any language that targets that runtime. For
+example, the .NET drivers work from C#, F#, and other .NET languages, and the
+Java driver works from Java, Kotlin, Scala, and other JVM languages.
+
+.. _driver-table-csharp:
+
+C#/.NET
+-------
+
+Distributed as .NET packages on NuGet, for use from C#/.NET applications:
+
+.. list-table::
+ :header-rows: 1
+ :class: driver-table
+
+ * - Driver for |click-for-readme|
+ - NuGet package
+ - Maintainer
+ * - `Apache Arrow Flight SQL <https://github.com/apache/arrow-adbc/tree/main/csharp/src/Drivers/FlightSql/README.md>`__
+ - :package-badge:`NuGet|Apache.Arrow.Adbc.FlightSql|https://www.nuget.org/packages/Apache.Arrow.Adbc.FlightSql/`
+ - ASF
+ * - :doc:`Google BigQuery <./bigquery>`
+ - :package-badge:`NuGet|Apache.Arrow.Adbc.Drivers.BigQuery|https://www.nuget.org/packages/Apache.Arrow.Adbc.Drivers.BigQuery/`
+ - ASF
+ * - `Apache Hive / Impala / Spark <https://github.com/apache/arrow-adbc/blob/main/csharp/src/Drivers/Apache/readme.md>`__
+ - :package-badge:`NuGet|Apache.Arrow.Adbc.Drivers.Apache|https://www.nuget.org/packages/Apache.Arrow.Adbc.Drivers.Apache/`
+ - ASF
+ * - `Databricks <https://github.com/apache/arrow-adbc/blob/main/csharp/src/Drivers/Databricks/readme.md>`__
+ - :package-badge:`NuGet|Apache.Arrow.Adbc.Drivers.Databricks|https://www.nuget.org/packages/Apache.Arrow.Adbc.Drivers.Databricks/`
+ - ASF
+
+.. _driver-table-java:
+
+Java/JVM
+--------
+
+Distributed as Maven packages, for use from Java applications:
+
+.. list-table::
+ :header-rows: 1
+ :class: driver-table
+
+ * - Driver for |click-for-docs|
+ - Maven package
+ - Maintainer
+ * - `Apache Arrow Flight SQL <https://arrow.apache.org/adbc/current/java/api/org/apache/arrow/adbc/driver/flightsql/package-summary.html>`__
+ - :package-badge:`Maven|org.apache.arrow.adbc:adbc-driver-flight-sql|https://central.sonatype.com/artifact/org.apache.arrow.adbc/adbc-driver-flight-sql`
+ - ASF
+ * - :doc:`./jdbc`
+ - :package-badge:`Maven|org.apache.arrow.adbc:adbc-driver-jdbc|https://central.sonatype.com/artifact/org.apache.arrow.adbc/adbc-driver-jdbc`
+ - ASF
+
+.. _driver-table-maintainers:
+
+Who Maintains These Drivers?
+============================
+
+The ADBC project focuses primarily on the :doc:`ADBC standard <../format/specification>`
+and :doc:`client libraries <../client_libraries>`, not on developing drivers
+and shipping driver binaries. The **Maintainer** column in the tables above
+identifies who maintains each driver:
+
+**ASF**
+ A few drivers are maintained within the Apache Arrow project under
+ Apache Software Foundation (ASF) governance, mostly for historical reasons.
+
+**Foundry**
+ Most drivers are maintained within the `ADBC Driver Foundry <https://adbc-drivers.org/>`__,
+ a community-governed project focused on growing the ADBC ecosystem.
+
+**Vendor**
+ Some drivers are maintained in independent repositories controlled
+ by database vendors.
+
+Have a Driver to Add?
+=====================
+
+If you've developed a high-quality ADBC driver, made it freely available for
+public use under a permissive license, and would like it listed here,
+`open an issue <https://github.com/apache/arrow-adbc/issues/new>`__ on the
+Apache Arrow ADBC repository with the details (name, database, repository URL,
+package names) and we'll help get it added.
+
+Interested in developing a new driver? See :doc:`Writing New Drivers <authoring>`.
+
+More Information
+================
+
+- :doc:`Client Libraries <../client_libraries>` — the libraries that load and use drivers from your language of choice
+- :doc:`Tools & Integrations <../integrations>` — tools and libraries that work with ADBC
+- :doc:`Connection Profiles <../connection_profiles>` — reusable, shareable connection configuration
+- `ADBC Quickstarts <https://github.com/columnar-tech/adbc-quickstarts>`__ — simple, runnable examples for getting started with many of these drivers
diff --git a/docs/source/driver/jdbc.rst b/docs/source/driver/jdbc.rst
index 63261db93..6311ae1bc 100644
--- a/docs/source/driver/jdbc.rst
+++ b/docs/source/driver/jdbc.rst
@@ -15,6 +15,8 @@
.. specific language governing permissions and limitations
.. under the License.
+:orphan:
+
============
JDBC Adapter
============
diff --git a/docs/source/driver/postgresql.rst b/docs/source/driver/postgresql.rst
index ba1e6b617..ab9191fbb 100644
--- a/docs/source/driver/postgresql.rst
+++ b/docs/source/driver/postgresql.rst
@@ -15,6 +15,8 @@
.. specific language governing permissions and limitations
.. under the License.
+:orphan:
+
=================
PostgreSQL Driver
=================
@@ -31,11 +33,11 @@ overall approach.
.. _libpq: https://www.postgresql.org/docs/current/libpq.html
.. _pgeon: https://github.com/0x0L/pgeon
-.. note:: Older versions (<=1.11.0) of this driver had experimental support for
- Amazon Redshift. As Redshift does not support reading or writing COPY
- in PostgreSQL binary format, however, the optimizations that
- accelerate queries are not enabled when connecting to Redshift. There
- may also be other differences in functionality.
+.. note:: Some older versions (<=1.11.0) of this driver had experimental
+ support for Amazon Redshift, but this was removed in 1.11.0. We
+ recommend using the `Redshift-specific driver
+ <https://docs.adbc-drivers.org/drivers/redshift/>`__ from the ADBC
+ Driver Foundry (a third party).
Installation
============
diff --git a/docs/source/driver/sqlite.rst b/docs/source/driver/sqlite.rst
index bb5f524bb..2ed10b13f 100644
--- a/docs/source/driver/sqlite.rst
+++ b/docs/source/driver/sqlite.rst
@@ -15,6 +15,8 @@
.. specific language governing permissions and limitations
.. under the License.
+:orphan:
+
=============
SQLite Driver
=============
diff --git a/docs/source/driver/status.rst b/docs/source/driver/status.rst
deleted file mode 100644
index c4d1b41a9..000000000
--- a/docs/source/driver/status.rst
+++ /dev/null
@@ -1,226 +0,0 @@
-.. Licensed to the Apache Software Foundation (ASF) under one
-.. or more contributor license agreements. See the NOTICE file
-.. distributed with this work for additional information
-.. regarding copyright ownership. The ASF licenses this file
-.. to you under the Apache License, Version 2.0 (the
-.. "License"); you may not use this file except in compliance
-.. with the License. You may obtain a copy of the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing,
-.. software distributed under the License is distributed on an
-.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-.. KIND, either express or implied. See the License for the
-.. specific language governing permissions and limitations
-.. under the License.
-
-============================
-Driver Implementation Status
-============================
-
-.. warning:: There is a known problem on macOS x86_64 when using two drivers
- written in Go in the same process (unless working in a pure-Go
- application), where using the second driver may crash. For more
- details, see `GH-1841
- <https://github.com/apache/arrow-adbc/issues/1841>`_.
-
-.. note::
-
- Drivers that support C/C++ can also be used from C#, GLib, Go, Python, R,
- Ruby, and Rust, regardless of their implementation language.
-
-.. _driver-status:
-
-Driver Status
-=============
-
-**Experimental** drivers are not feature-complete and the implementation is still progressing.
-**Beta** drivers are (mostly) feature-complete but have only been available for a short time.
-**Stable** drivers are (mostly) feature-complete (as much as possible for the underlying database) and have been available/tested for a while.
-
-Feature Support
-===============
-
-.. adbc_driver_status_table::
-
- ../../../csharp/src/Drivers/Apache/Hive2/README.md
- ../../../csharp/src/Drivers/Apache/Impala/README.md
- ../../../csharp/src/Drivers/Apache/Spark/README.md
- ../../../csharp/src/Drivers/BigQuery/readme.md
- ../../../csharp/src/Drivers/Databricks/readme.md
- ../../../csharp/src/Drivers/FlightSql/README.md
- ../../../java/driver/flight-sql/README.md
- ./duckdb => ../../../c/integration/duckdb/README.md [#duckdb]
- ./flight_sql => ../../../c/driver/flightsql/README.md
- ./jdbc => ../../../java/driver/jdbc/README.md
- ./postgresql => ../../../c/driver/postgresql/README.md
- ./sqlite => ../../../c/driver/sqlite/README.md
-
-.. [#duckdb] DuckDB is developed and provided by a third party. See the
- `DuckDB documentation
- <https://duckdb.org/docs/stable/clients/adbc.html>`_ for details.
-
-Feature Support
-===============
-
-N/A indicates that it is not possible to support this feature in the underlying database.
-
-See individual driver documentation pages for full details.
-
-Bulk Ingestion
- Does the driver support :ref:`bulk ingestion of data <specification-bulk-ingestion>` (creating or appending to a database table from an Arrow table)?
-
-Database Metadata
- Does the driver support functions like :c:func:`AdbcConnectionGetObjects` that get metadata about the database catalog, etc.?
-
-Parameterized Queries
- Does the driver support binding query parameters?
-
-Partitioned Data
- Being able to read individual chunks of a (generally distributed)
- result set (:c:func:`AdbcStatementExecutePartitions`).
-
-Prepared Statements
- Does the driver support binding query parameters?
-
-Full Type Support
- Does the driver map all database types to/from equivalent Arrow types, as much as is possible?
-
-Select Queries
- Does the driver support queries returning result sets?
-
-SQL
- Does the driver support submitting SQL queries?
-
-Transactions
- Does the driver support explicit transactions (the default is to assume auto-commit)?
-
-Substrait
- Does the driver support submitting Substrait plans?
-
-Update Queries
- Does the driver support queries not returning result sets?
-
-.. list-table:: General features
- :header-rows: 1
-
- * - Driver
- - Full Type Support
- - SQL
- - Substrait
-
- * - Flight SQL (Go)
- - Y
- - Y
- - N
-
- * - Flight SQL (Java)
- - Y
- - Y
- - N
-
- * - JDBC
- - N
- - Y
- - N/A
-
- * - PostgreSQL
- - N
- - Y
- - N/A
-
- * - SQLite
- - Y
- - Y
- - N/A
-
-.. list-table:: Statement/query-level features
- :header-rows: 1
-
- * - Driver
- - Incremental Queries
- - Partitioned Data
- - Parameterized Queries
- - Prepared Statements
- - Select Queries
- - Update Queries
-
- * - Flight SQL (Go)
- - Y
- - Y
- - Y
- - Y
- - Y
- - Y
-
- * - Flight SQL (Java)
- - N
- - Y
- - Y
- - Y
- - Y
- - Y
-
- * - JDBC
- - N/A
- - N/A
- - Y
- - Y
- - Y
- - Y
-
- * - PostgreSQL
- - N/A
- - N/A
- - Y [#postgresql-prepared]_
- - Y
- - Y
- - Y
-
- * - SQLite
- - N/A
- - N/A
- - Y
- - Y
- - Y
- - Y
-
-.. [#postgresql-prepared] The PostgreSQL driver only supports executing
- prepared statements with parameters that do not return result sets
- (basically, an INSERT with parameters). Queries that return result sets
- are difficult with prepared statements because the driver is built around
- using COPY for best performance, which is not supported in this context.
-
-.. list-table:: Connection/database-level features
- :header-rows: 1
-
- * - Driver
- - Bulk Ingestion
- - Database Metadata (catalogs, etc.)
- - Transactions
-
- * - Flight SQL (Go)
- - N
- - Y
- - Y
-
- * - Flight SQL (Java)
- - Y
- - Y
- - N
-
- * - JDBC
- - Y
- - Y
- - N
-
- * - PostgreSQL
- - Y
- - Y
- - Y
-
- * - SQLite
- - Y
- - Y
- - Y
diff --git a/docs/source/ext/adbc_misc.py b/docs/source/ext/adbc_misc.py
index 827ac4aec..fc2dc53b0 100644
--- a/docs/source/ext/adbc_misc.py
+++ b/docs/source/ext/adbc_misc.py
@@ -20,11 +20,11 @@
import collections
import dataclasses
import functools
-import itertools
import typing
from pathlib import Path
import docutils
+import docutils.nodes
import sphinx
from docutils.statemachine import StringList
from sphinx.util.docutils import SphinxDirective
@@ -257,7 +257,7 @@ class DriverStatusDirective(SphinxDirective):
generated_lines = [
f":bdg-primary:`Language: {status.implementation}`",
- f":bdg-ref-{status.badge_type}:`Status: {status.status} <driver-status>`",
+ f":bdg-{status.badge_type}:`Status: {status.status}`",
]
parsed = docutils.nodes.Element()
@@ -269,99 +269,74 @@ class DriverStatusDirective(SphinxDirective):
return parsed.children
-class DriverStatusTableDirective(SphinxDirective):
- has_content = True
- required_arguments = 0
- optional_arguments = 0
- option_spec: OptionSpec = {}
+def package_badge_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+ """Create a two-part badge for package managers.
- def run(self):
- table = []
- for line in self.content:
- if "=>" in line:
- xref, _, path = line.partition("=>")
- xref = xref.strip()
- path = path.strip()
- else:
- xref = None
- path = line.strip()
-
- if "[#" in path:
- footnote = path[path.index("[#") + 2 : -1].strip()
- path = path[: path.index("[#")].strip()
- else:
- footnote = None
-
- rel_filename, filename = self.env.relfn2path(path)
- self.env.note_dependency(rel_filename)
-
- path = Path(filename).resolve()
- status = driver_status(path)
- table.append((status, xref, footnote))
-
- table.sort(key=lambda x: (x[0].vendor, x[0].implementation))
+ Usage: :package-badge:`PackageManager|package-name|URL`
+ Example: :package-badge:`PyPI|adbc-driver-postgresql|https://pypi.org/project/adbc-driver-postgresql/`
+ """
+ parts = text.split("|")
+ if len(parts) != 3:
+ msg = inliner.reporter.error(
+ f"package-badge must have exactly 3 parts separated by |, got: {text}",
+ line=lineno,
+ )
+ return [inliner.problematic(rawtext, rawtext, msg)], [msg]
- generated_lines = [
- ".. list-table::",
- " :header-rows: 1",
- "",
- " * - Vendor",
- " - Implementation",
- " - :ref:`driver-status`",
- " - Packages [#packages]_",
- "",
- ]
- for row in table:
- if row[1]:
- generated_lines.append(f" * - :doc:`{row[0].vendor} <{row[1]}>`")
- else:
- generated_lines.append(f" * - {row[0].vendor}")
-
- if row[2]:
- generated_lines[-1] += f" [#{row[2]}]_"
-
- generated_lines.append(f" - {row[0].implementation}")
- generated_lines.append(f" - {row[0].status}")
-
- generated_lines.append(" -")
- packages = itertools.groupby(
- sorted(row[0].packages, key=lambda x: x[0].lower()),
- key=lambda x: x[0],
- )
- for repo, group in packages:
- group = list(group)
- if generated_lines[-1][-1] == "-":
- generated_lines[-1] += " "
- else:
- generated_lines[-1] += ", "
+ left_text, right_text, url = [p.strip() for p in parts]
- if len(group) == 1:
- generated_lines[-1] += f"`{repo} <{group[0][2]}>`__"
- else:
- links = ", ".join(f"`{pkg[1]} <{pkg[2]}>`__" for pkg in group)
- generated_lines[-1] += f"{repo} ({links})"
- generated_lines.append("")
+ # Create the two-part badge structure
+ # Left part (label): darker background
+ left_node = docutils.nodes.inline("", left_text, classes=["package-badge-left"])
- generated_lines.extend(
- [
- "",
- ".. [#packages] This lists only packages available in package repositories. However, as noted above, many of these drivers can be used from languages not listed via the driver manager, even if a package is not yet available.", # noqa:E501
- ]
- )
+ # Right part (value): lighter background
+ right_node = docutils.nodes.inline("", right_text, classes=["package-badge-right"])
- parsed = docutils.nodes.Element()
- nested_parse_with_titles(
- self.state,
- StringList(generated_lines, source=""),
- parsed,
+ # Container to hold both parts together
+ container = docutils.nodes.inline(
+ "", "", left_node, right_node, classes=["package-badge-container"]
+ )
+
+ # Wrap in a reference/link
+ ref_node = docutils.nodes.reference(
+ "", "", container, refuri=url, classes=["package-badge-link"]
+ )
+
+ return [ref_node], []
+
+
+def iconlink_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+ """Create an icon-only link (e.g. a GitHub logo linking to a repo).
+
+ Usage: :iconlink:`fa-classes|URL|tooltip`
+ Example: :iconlink:`fa-brands fa-github|https://github.com/apache/arrow-adbc|Source`
+
+ The ``tooltip`` is used as the link's accessible label (``title`` and
+ ``aria-label``) so the icon-only link remains usable without visible text.
+ """
+ parts = text.split("|")
+ if len(parts) != 3:
+ msg = inliner.reporter.error(
+ f"iconlink must have exactly 3 parts separated by |, got: {text}",
+ line=lineno,
)
- return parsed.children
+ return [inliner.problematic(rawtext, rawtext, msg)], [msg]
+
+ fa_classes, url, tooltip = [p.strip() for p in parts]
+
+ icon_html = (
+ f'<a class="icon-link" href="{url}" title="{tooltip}" '
+ f'aria-label="{tooltip}"><i class="{fa_classes}" aria-hidden="true">'
+ f"</i></a>"
+ )
+ return [docutils.nodes.raw("", icon_html, format="html")], []
def setup(app) -> None:
app.add_directive("adbc_driver_installation", DriverInstallationDirective)
app.add_directive("adbc_driver_status", DriverStatusDirective)
- app.add_directive("adbc_driver_status_table", DriverStatusTableDirective)
+ app.add_role("package-badge", package_badge_role)
+ app.add_role("iconlink", iconlink_role)
return {
"version": "0.1",
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
index 4489c4b9c..fd688abda 100644
--- a/docs/source/faq.rst
+++ b/docs/source/faq.rst
@@ -28,7 +28,7 @@ lower level, ADBC is two separate but related things:
1. An abstract API for working with databases and Arrow data.
2. A set of concrete implementations of that abstract API in different languages
- and drivers for different databases (see :doc:`driver/status`).
+ and drivers for different databases (see :doc:`driver/index`).
Why not just use JDBC/ODBC?
===========================
@@ -250,7 +250,7 @@ When/where is 1.0? Is this project ready?
Different parts of the project have different version numbers. We consider
certain implementations (like Go) to be "1.0"-ready, while others (like Java)
-are still pre-1.0. :doc:`driver/status` has a rough overview of the status of
+are still pre-1.0. :doc:`driver/index` has a rough overview of the status of
individual driver implementations.
Where can I learn more about the rationale for ADBC?
diff --git a/docs/source/format/connection_profiles.rst b/docs/source/format/connection_profiles.rst
index aaabc49e9..6e17531ac 100644
--- a/docs/source/format/connection_profiles.rst
+++ b/docs/source/format/connection_profiles.rst
@@ -19,12 +19,16 @@
ADBC Driver Manager and Connection Profiles
===========================================
-.. note:: This document describes using the :term:`driver manager` to load
- drivers. The driver manager is not required to use ADBC in general
- but it allows loading drivers written in a different language from the
- application and improves the experience when using multiple drivers in
- a single application. For more information on how the driver manager
- works see :doc:`how_manager`.
+.. note:: This page is a detailed reference on the connection profile format and
+ behavior, aimed at developers of ADBC drivers and libraries and
+ advanced users. For basic usage of connection profiles, see
+ :doc:`Connection Profiles <../connection_profiles>` instead.
+
+ Profiles are loaded by the :term:`driver manager`, which is not
+ required to use ADBC in general but which allows loading drivers
+ written in a different language from the application and improves the
+ experience when using multiple drivers in a single application. For
+ more on how the driver manager works, see :doc:`how_manager`.
There are two ways to pass database options through the driver manager:
@@ -200,6 +204,8 @@ Profile values can reference environment variables using the ``{{ env_var() }}``
When the driver manager encounters ``{{ env_var(VAR_NAME) }}``, it replaces the placeholder with the contents of environment variable ``VAR_NAME``. If the environment variable is not set, the placeholder is replaced with an empty string and processing of the rest of the value continues (e.g. ``"foo{{ env_var(MISSING) }}bar"`` becomes ``"foobar"``).
+.. _profile-search-locations:
+
Profile Search Locations
=========================
diff --git a/docs/source/format/driver_manifests.rst b/docs/source/format/driver_manifests.rst
index 77753f81a..dbf78977e 100644
--- a/docs/source/format/driver_manifests.rst
+++ b/docs/source/format/driver_manifests.rst
@@ -35,7 +35,10 @@ There are two ways to load a driver with the driver manager:
With either method, you specify the dynamic library or driver manifest as the
``driver`` option to the driver manager or you can use an explicit function for
loading drivers if your driver manager library exposes one (e.g., C++, see
-example below).
+example below). With either method, you can also specify the driver in a
+:doc:`connection profile <connection_profiles>`. You can additionally let the
+driver manager select the driver from the scheme of the ADBC connection URI
+(see :ref:`driver-uri-scheme`).
.. note:: In addition to the ``driver`` option, there is also an
:term:`entrypoint` option that should be used if the driver uses a
@@ -324,6 +327,8 @@ The construction of the platform tuple is: ``<OS>_<Architecture>``, for example:
(glibc) or MinGW, the tuple should have the appropriate suffix for that
environment. i.e. ``linux_amd64_musl`` or ``windows_amd64_mingw``.
+.. _driver-manifest-discovery:
+
Manifest Location and Discovery
-------------------------------
@@ -505,3 +510,31 @@ would happen for ODBC drivers. The search for a manifest on Windows would be the
* The registry is searched for the key ``HKEY_LOCAL_MACHINE\SOFTWARE\ADBC\Drivers\${name}``. If it exists, then the same sub-keys
as above are used.
+
+.. _driver-uri-scheme:
+
+Resolving a Driver from a Connection URI
+----------------------------------------
+
+Most ADBC drivers accept connection parameters as a URI, which is passed using
+the ``uri`` option. By convention, a driver's connection URIs use a scheme that
+matches the driver's name. For example, the PostgreSQL driver uses
+``postgresql://`` URIs and the SQLite driver uses ``sqlite://`` URIs.
+
+When a driver has not otherwise been specified (that is, no ``driver`` option
+was given), the driver manager will use the **scheme** of the ``uri`` option as
+the driver name and resolve it using the discovery process described above. For
+example, given only::
+
+ uri = "postgresql://localhost:5432/postgres"
+
+the driver manager takes ``postgresql`` as the driver name, searches for a
+matching driver (e.g. a ``postgresql.toml`` manifest), loads it, and then passes
+the full URI to the driver as the ``uri`` option. This lets an application
+connect using just a connection URI, without separately naming the driver.
+
+The scheme is matched against the driver name using the same rules as any other
+driver name, so the corresponding driver must be discoverable as a manifest or
+shared library (see :ref:`driver-manifest-discovery`). A driver may accept
+multiple URI schemes; consult the documentation for the specific driver for the
+schemes and connection URI formats it supports.
diff --git a/docs/source/format/related_work.rst b/docs/source/format/related_work.rst
index c09b0b680..0ce9a93fe 100644
--- a/docs/source/format/related_work.rst
+++ b/docs/source/format/related_work.rst
@@ -19,9 +19,10 @@
Related Work
============
-In the initial proposal, a survey of existing solutions and systems was
-included, which is partially reproduced below for context, though note the
-descriptions are only kept up-to-date on a best-effort basis.
+In the initial proposal for ADBC, a survey of existing solutions and
+systems was included, which is partially reproduced below for context,
+though note the descriptions are only kept up-to-date on a best-effort
+basis.
Preexisting database client APIs
================================
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
index ab87f4c6f..e7b2b7744 100644
--- a/docs/source/glossary.rst
+++ b/docs/source/glossary.rst
@@ -23,25 +23,44 @@ Glossary
Arrow Flight SQL
A :term:`wire protocol` for data systems that uses Apache Arrow.
- See the :external:doc:`specification <format/FlightSql>`.
+ See the :external:doc:`Flight SQL specification <format/FlightSql>`.
client API
The API that an application uses to interact with a database. May
- abstract over the underlying :term:`wire protocol` and other details.
- For example, ADBC, JDBC, ODBC.
+ abstract over the underlying :term:`wire protocol` and other details. A
+ client API is generally standardized so that many applications and
+ databases can interoperate through it: examples include ADBC (defined by
+ the :doc:`ADBC specification <format/specification>`), JDBC, and ODBC.
+
+ client library
+ A library an application uses to access databases from a particular
+ language. In ADBC, a client library exposes the ADBC :term:`client API`
+ and includes a :term:`driver manager` for loading and using
+ :term:`drivers <driver>`. Its API is designed to feel idiomatic in the host
+ language (for example, DBAPI in Python, ``database/sql`` in Go, or DBI in
+ R). The terms *client library* and *driver manager* are often used
+ interchangeably, though strictly the driver manager is the driver-loading
+ component within the client library.
connection
- In ADBC, the connection object/struct represents a single connection to a
- database. Multiple connections may be created from one :term:`database`.
+ In the ADBC API, the connection object/struct represents a single
+ connection to a database. Multiple connections may be created from one
+ :term:`database`.
connection profile
- A preconfigured driver and options that can be loaded by the
- :term:`driver manager` for convenience. Specified via a TOML file. See
- :doc:`format/connection_profiles`.
+ In ADBC, a named, reusable configuration that pairs a :term:`driver` with
+ a set of options, stored in a TOML file. A :term:`client library` can load
+ a profile by name at connection time, so credentials and settings do not
+ have to be specified in application code.
database
- In ADBC, the database object/struct holds state that is shared across
- connections.
+ In the ADBC API, the database object/struct holds state that is shared
+ across :term:`connections <connection>`.
+
+ In general usage, a database is the system that an ADBC :term:`driver`
+ connects to. This documentation uses the term broadly to refer not only to
+ databases proper but also to query engines, data warehouses, data
+ lakehouses, cloud data platforms, and the like.
driver
Loosely speaking, a library that implements a :term:`client API` using a
@@ -58,33 +77,28 @@ Glossary
application in any supported language using a :term:`driver manager`.
driver manager
- A library for loading and using :term:`drivers <driver>`. A driver manager
- implements the ADBC API and delegates to dynamically-loaded drivers. It
- simplifies using multiple drivers in a single application and makes it
- possible to use drivers written in any language, regardless of the language
- the application is written in.
-
- The driver manager in each language is similar. In C/C++, it can
- dynamically load drivers so that applications do not have to directly link
- to them. (Since all drivers expose the same API, their symbols would
- collide otherwise.) In Python, it loads drivers and provides Python
- bindings on top.
+ A component that dynamically loads :term:`drivers <driver>` and forwards an
+ application's calls to them. In ADBC, the driver manager is the part of a
+ :term:`client library` that loads ADBC drivers. It can load any driver
+ built as a shared library, making it possible to use a driver written in
+ one language from an application written in another, and simplifies using
+ multiple drivers in a single application. The terms *driver manager* and
+ *client library* are often used interchangeably.
driver manifest
- A file (in TOML format) describing a :term:`driver`. This file's structure
- is part of the ADBC :doc:`specification <format/specification>`. A
- :term:`driver manager` can load a driver from a which simplifies the
- process for users.
+ In ADBC, a file (in TOML format) describing a :term:`driver`, with a
+ structure defined by the ADBC specification. A :term:`driver manager` can
+ load a driver from its manifest, which simplifies the process for users.
entrypoint
- The name of a function exported by a driver that the :term:`driver manager`
- calls when a driver is loaded to perform any initialization required by the
- driver. The name follows a convention which is outlined in
- :c:type:`AdbcDriverInitFunc` but another name may be used.
+ In ADBC, the name of a function exported by a driver that the
+ :term:`driver manager` calls when a driver is loaded to perform any
+ initialization required by the driver. The name follows a convention which
+ is outlined in :c:type:`AdbcDriverInitFunc` but another name may be used.
statement
- In ADBC, the statement object/struct holds state for executing a single
- query. The query itself, bind parameters, result sets, and so on are all
+ In the ADBC API, the statement object/struct holds state for executing a
+ single query. The query itself, bind parameters, result sets, and so on are all
tied to the statement. Multiple statements may be created from one
:term:`connection` (though not all drivers will support this).
@@ -96,12 +110,12 @@ Glossary
predictable semantics.
wire protocol
- The actual way a database driver connects to a database, issues commands,
- gets results, and so forth. For example, :term:`Arrow Flight SQL`, the
- `PostgreSQL wire protocol`_, or `Tabular Data Stream`_ (Microsoft SQL
- Server). Generally, an application is not going to implement and use this
- directly, but instead use something higher-level, like an ADBC, JDBC, or
- ODBC driver.
+ The actual way a driver connects to a :term:`database`, issues commands,
+ gets results, and so forth. Also called a database client-server protocol.
+ For example, :term:`Arrow Flight SQL`, the `PostgreSQL wire protocol`_, or
+ `Tabular Data Stream`_ (Microsoft SQL Server). Generally, an application
+ does not implement or use this directly, but instead uses something
+ higher-level, like an ADBC, JDBC, or ODBC driver.
.. _PostgreSQL wire protocol: https://www.postgresql.org/docs/current/protocol.html
.. _Substrait: https://substrait.io/
diff --git a/docs/source/index.rst b/docs/source/index.rst
index aacf289ba..e02557f18 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -39,191 +39,177 @@ Apache Arrow ADBC
**Cross-language**, **Arrow-native** database access.
-ADBC is a set of APIs and libraries for Arrow-native access to databases.
-Execute SQL and Substrait_ queries, query database catalogs, and more, all
-using Arrow data to eliminate unnecessary data copies, speed up access, and
-make it more convenient to build analytical applications.
+ADBC is a standardized set of APIs and libraries for fast, Arrow-native
+database access. Execute SQL queries, fetch results, ingest bulk data,
+explore catalogs, and more. ADBC uses Arrow columnar format to eliminate
+copies and conversions, speeding up data retrieval for analytics and AI
+applications.
-.. _Substrait: https://substrait.io/
-
-.. div::
-
- .. grid::
- :margin: 4 4 0 0
- :gutter: 1
-
- .. grid-item-card::
- :columns: 12 12 4 4
-
- Quickstart
- ^^^
-
- Get started with simple examples in your language of choice.
-
- +++
-
- .. button-ref:: cpp/quickstart
- :ref-type: doc
- :color: secondary
- :expand:
+Getting Started
+---------------
- C/C++
-
- .. button-link:: https://pkg.go.dev/github.com/apache/arrow-adbc/go/adbc
- :color: secondary
- :expand:
-
- Go
+.. grid:: 1 1 2 3
+ :margin: 4 4 0 0
+ :gutter: 3
- .. button-ref:: java/quickstart
- :ref-type: doc
- :color: secondary
- :expand:
+ .. grid-item-card:: :octicon:`plug` Available Drivers
+ :link: driver/index
+ :link-type: doc
- Java
+ Connect to a growing list of databases using ADBC drivers.
- .. button-ref:: javascript/index
- :ref-type: doc
- :color: secondary
- :expand:
+ .. grid-item-card:: :octicon:`code` Client Libraries
+ :link: client_libraries
+ :link-type: doc
- JavaScript
+ Use ADBC from C/C++, C#, Go, Java, JavaScript, Python, R, Ruby, and Rust.
- .. button-ref:: python/quickstart
- :ref-type: doc
- :color: secondary
- :expand:
+ .. grid-item-card:: :octicon:`tools` Writing Drivers
+ :link: driver/authoring
+ :link-type: doc
- Python
+ Create your own ADBC driver using the driver SDKs available in multiple languages.
- .. button-ref:: r/index
- :ref-type: doc
- :color: secondary
- :expand:
- R
+.. _dbc: https://docs.columnar.tech/dbc
+.. _Substrait: https://substrait.io/
- .. button-ref:: rust/quickstart
- :ref-type: doc
- :color: secondary
- :expand:
+Why ADBC?
+---------
- Rust
+.. grid:: 1 2 2 2
+ :margin: 4 4 0 0
+ :gutter: 1
- .. grid-item-card::
- :columns: 12 4 4 4
+ .. grid-item-card:: Arrow-native
+ :link: https://arrow.apache.org/
- Specification
- ^^^
+ Run queries and get back results in Arrow columnar format,
+ eliminating copies and conversions for blazing-fast transfer
+ to and from Arrow-native databases and engines.
- Learn about the underlying API specification.
+ +++
+ Learn about Apache Arrow
- +++
+ .. grid-item-card:: Multi-database
+ :link: driver/index
+ :link-type: doc
- .. button-link:: https://arrow.apache.org/blog/2023/01/05/introducing-arrow-adbc/
- :color: secondary
- :expand:
+ Connect to all kinds of databases through one vendor-neutral standard,
+ even ones that aren't Arrow-native. ADBC drivers optimize conversion
+ to/from Arrow where required.
- Introducing ADBC :octicon:`cross-reference`
+ +++
+ See Supported Drivers
- .. button-ref:: format/specification
- :ref-type: doc
- :color: secondary
- :expand:
+ .. grid-item-card:: Cross-language
+ :link: client_libraries
+ :link-type: doc
- Specification
+ Work in C/C++, C#, Go, Java, JavaScript / TypeScript, Python, R, Ruby,
+ Rust, and more. Use idiomatic APIs like DBAPI in Python,
+ ``database/sql`` in Go, and DBI in R.
- .. button-ref:: faq
- :ref-type: doc
- :color: secondary
- :expand:
+ +++
+ See Client Libraries
- FAQ
+ .. grid-item-card:: Full-featured
+ :link: format/comparison
+ :link-type: doc
- .. button-ref:: glossary
- :ref-type: doc
- :color: secondary
- :expand:
+ Execute SQL and Substrait, query database catalogs, inspect table
+ schemas, and more. ADBC handles common tasks without having to pull in
+ another database client.
- Glossary
+ +++
+ Compare to Other APIs
- .. grid-item-card::
- :columns: 12 4 4 4
+More Resources
+--------------
- Development
- ^^^
+.. grid:: 1 2 2 2
+ :margin: 4 4 0 0
+ :gutter: 2
- Report bugs, ask questions, and contribute to Apache Arrow.
+ .. grid-item-card:: Explore
- +++
+ .. button-ref:: integrations
+ :ref-type: doc
+ :color: secondary
+ :expand:
- .. button-link:: https://github.com/apache/arrow-adbc/issues
- :color: secondary
- :expand:
+ Tools & Integrations
- :fab:`github` Issues/Questions
+ .. button-ref:: connection_profiles
+ :ref-type: doc
+ :color: secondary
+ :expand:
- .. button-link:: https://arrow.apache.org/community/
- :color: secondary
- :expand:
+ Connection Profiles
- Mailing List :octicon:`cross-reference`
+ .. button-link:: https://arrow.apache.org/blog/2023/01/05/introducing-arrow-adbc/
+ :color: secondary
+ :expand:
- .. button-link:: https://github.com/apache/arrow-adbc/blob/main/CONTRIBUTING.md
- :color: secondary
- :expand:
+ Introducing ADBC :octicon:`cross-reference`
- Contributing :octicon:`cross-reference`
+ .. button-ref:: faq
+ :ref-type: doc
+ :color: secondary
+ :expand:
-Why ADBC?
-=========
+ FAQ
-.. grid:: 1 2 2 2
- :margin: 4 4 0 0
- :gutter: 1
+ .. button-ref:: glossary
+ :ref-type: doc
+ :color: secondary
+ :expand:
- .. grid-item-card:: Arrow-native
- :link: https://arrow.apache.org/
+ Glossary
- Execute queries and get back results in Arrow format, eliminating extra
- data copies for Arrow-native backends.
+ .. grid-item-card:: Community
- +++
- Learn about Apache Arrow
+ .. button-link:: https://github.com/apache/arrow-adbc/issues
+ :color: secondary
+ :expand:
- .. grid-item-card:: Backend-agnostic
- :link: driver/status
- :link-type: doc
+ :fab:`github` Issues / Questions
- Connect to all kinds of databases, even ones that aren't Arrow-native.
- ADBC drivers optimize conversion to/from Arrow where required, saving
- work for developers.
+ .. button-link:: https://arrow.apache.org/community/
+ :color: secondary
+ :expand:
- +++
- See Supported Drivers
+ Mailing List :octicon:`cross-reference`
- .. grid-item-card:: Cross-language
+ .. button-link:: https://github.com/apache/arrow-adbc/blob/main/CONTRIBUTING.md
+ :color: secondary
+ :expand:
- Work in C/C++, C#, Go, Java, Python, R, Ruby, Rust, and more.
+ Contributing :octicon:`cross-reference`
- .. grid-item-card:: Full-featured
+ .. button-link:: https://docs.adbc-drivers.org
+ :color: secondary
+ :expand:
- Execute SQL and Substrait, query database catalogs, inspect table
- schemas, and more. ADBC handles common tasks without having to pull in
- another database client.
+ Driver Foundry Docs :octicon:`cross-reference`
- .. grid-item-card:: Language-native
+.. toctree::
+ :maxdepth: 1
+ :titlesonly:
+ :caption: Connect
+ :hidden:
- Use language-native APIs that you're already familiar with, like DBAPI
- in Python, ``database/sql`` in Go, or DBI in R.
+ Client Libraries <client_libraries>
+ Drivers <driver/index>
+ Tools & Integrations <integrations>
+ Connection Profiles <connection_profiles>
.. toctree::
:maxdepth: 1
+ :caption: Build
:hidden:
- faq
- glossary
- genindex
+ Writing New Drivers <driver/authoring>
.. toctree::
:maxdepth: 1
@@ -237,22 +223,9 @@ Why ADBC?
JavaScript <javascript/index>
Python <python/index>
R <r/index>
+ Ruby <ruby/index>
Rust <rust/index>
-
-.. toctree::
- :maxdepth: 1
- :caption: Drivers
- :hidden:
-
- driver/installation
- driver/status
- driver/bigquery
- driver/duckdb
- driver/flight_sql
- driver/jdbc
- driver/postgresql
- driver/sqlite
- driver/authoring
+ Installation <installation>
.. toctree::
:maxdepth: 1
@@ -269,10 +242,19 @@ Why ADBC?
.. toctree::
:maxdepth: 1
- :caption: Development
+ :caption: Contribute
:hidden:
development/contributing
development/nightly
development/versioning
development/releasing
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Resources
+ :hidden:
+
+ faq
+ glossary
+ genindex
diff --git a/docs/source/driver/installation.rst b/docs/source/installation.rst
similarity index 87%
rename from docs/source/driver/installation.rst
rename to docs/source/installation.rst
index d3b2c189c..3a628ab0e 100644
--- a/docs/source/driver/installation.rst
+++ b/docs/source/installation.rst
@@ -32,12 +32,19 @@ Installation
https://apache.org/legal/release-policy#publication
> Your project's download page can only link to release artifacts that your PMC has approved.
-.. note::
+This page provides download and installation instructions for the official
+source release and the driver packages that are maintained in the
+``apache/arrow-adbc`` repository and voted on as part of the release.
- See individual driver pages in the sidebar for specific installation instructions.
+.. note:: To get up and running quickly, see instead:
-Source
-======
+ - :doc:`Client Libraries </client_libraries>` — install an ADBC client library for your language.
+ - :doc:`Drivers </driver/index>` — find and install a driver for your database. Most drivers are maintained and distributed elsewhere, not in this repository.
+
+.. _source:
+
+Source Release
+==============
Download the latest source release: |source_download| (|source_checksum|, |source_signature|)
@@ -49,8 +56,14 @@ Compilation instructions can be found in `CONTRIBUTING.md`_.
.. _instructions: https://www.apache.org/info/verification.html
.. _KEYS: https://downloads.apache.org/arrow/KEYS
+Driver Releases
+===============
+
+Installation instructions for the driver packages that are maintained
+in this repository and voted on as part of the release.
+
C/C++
-=====
+-----
Install the appropriate driver package. Packages for ``apt`` and ``dnf`` are provided as part of official releases.
@@ -116,7 +129,7 @@ Then they can be used via CMake, e.g.:
target_link_libraries(myapp PRIVATE AdbcDriverPostgreSQL::adbc_driver_postgresql_shared)
Java
-====
+----
Add a dependency on the driver package, for example:
@@ -124,7 +137,7 @@ Add a dependency on the driver package, for example:
- ``org.apache.arrow.adbc:adbc-driver-jdbc``
Python
-======
+------
Install the appropriate driver package.
@@ -137,7 +150,7 @@ For example, from PyPI:
- ``pip install adbc-driver-sqlite``
R
-===
+-
Install the appropriate driver package from CRAN:
@@ -154,7 +167,7 @@ Drivers not yet available on CRAN can be installed from R-multiverse:
install.packages("adbcflightsql", repos = "https://community.r-multiverse.org")
Ruby
-====
+----
Install the appropriate driver package for C/C++. You can use it from
Ruby.
diff --git a/docs/source/integrations.rst b/docs/source/integrations.rst
new file mode 100644
index 000000000..fd8628490
--- /dev/null
+++ b/docs/source/integrations.rst
@@ -0,0 +1,200 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied. See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+====================
+Tools & Integrations
+====================
+
+ADBC works alongside many popular data tools and frameworks. This page describes how ADBC fits into each ecosystem.
+
+----
+
+Apache DataFusion
+=================
+
+`Apache DataFusion <https://datafusion.apache.org>`_ integrates with ADBC in two ways:
+
+1. **DataFusion is available as an ADBC driver** — the `DataFusion ADBC driver <https://docs.adbc-drivers.org/drivers/datafusion/>`_ lets you run DataFusion queries from any ADBC client library.
+2. **ADBC table provider** — the `ADBC table provider for DataFusion <https://github.com/datafusion-contrib/datafusion-table-providers#adbc>`_ lets you query *other* databases from DataFusion. A table provider exposes an external data source as a table in DataFusion, so you can register a database table via an ADBC driver and query it with DataFusion SQL alongside your other data sources.
+
+----
+
+databow
+=======
+
+`databow <https://docs.columnar.tech/databow/>`_ is a command-line tool for querying databases via ADBC. It provides an interactive SQL shell with syntax highlighting, formatted output, and support for exporting results to JSON, CSV, or Arrow IPC files.
+
+See the `databow documentation <https://docs.columnar.tech/databow/>`_ for more details.
+
+----
+
+.. _dbc:
+
+dbc
+===
+
+`dbc <https://docs.columnar.tech/dbc>`__ is a command-line tool from `Columnar <https://columnar.tech>`__ for installing and managing ADBC drivers on your system. It handles downloading driver binaries, placing them in standard locations, and keeping them up to date—so you don't have to build drivers from source or manage shared libraries by hand.
+
+See the `dbc documentation <https://docs.columnar.tech/dbc>`_ for how to install and use dbc.
+
+----
+
+DuckDB
+======
+
+`DuckDB <https://duckdb.org>`_ integrates with ADBC in two ways:
+
+1. **DuckDB itself is an ADBC driver** — DuckDB (technically libduckdb) exposes an ADBC interface so you can connect to a DuckDB database from any ADBC client library. See :doc:`driver/duckdb` for details on using DuckDB as an ADBC driver.
+2. **DuckDB extensions** — Two DuckDB community extensions, `adbc <https://duckdb.org/community_extensions/extensions/adbc.html>`_ and `adbc_scanner <https://duckdb.org/community_extensions/extensions/adbc_scanner>`_, let you query *other* databases from DuckDB using ADBC drivers.
+
+----
+
+GDAL
+====
+
+`GDAL <https://gdal.org>`_ (Geospatial Data Abstraction Library) supports reading spatial data from databases via ADBC through its `ADBC OGR driver <https://gdal.org/en/stable/drivers/vector/adbc.html>`_ (added in GDAL 3.11). The driver is read-only. This lets you use any ADBC-compatible database as a vector data source in tools like ``ogrinfo`` and ``ogr2ogr``.
+
+See the `GDAL ADBC driver documentation <https://gdal.org/en/stable/drivers/vector/adbc.html>`_ for full details.
+
+----
+
+Go ``database/sql``
+===================
+
+The Go ADBC client library provides an adapter so ADBC drivers can be used through Go's standard `database/sql <https://pkg.go.dev/database/sql>`_ interface. This means you can use ADBC drivers with any library or framework that accepts a ``*sql.DB``.
+
+.. code-block:: go
+
+ import (
+ "database/sql"
+ "github.com/apache/arrow-adbc/go/adbc/sqldriver"
+ "github.com/apache/arrow-adbc/go/adbc/drivermgr"
+ )
+
+ // Register the ADBC driver manager as a database/sql driver.
+ sql.Register("flightsql", sqldriver.Driver{Driver: &drivermgr.Driver{}})
+
+ db, err := sql.Open("flightsql", "uri=grpc://localhost:12345")
+
+See the `Go documentation <https://pkg.go.dev/github.com/apache/arrow-adbc/go/adbc>`_ for full details.
+
+----
+
+pandas
+======
+
+`pandas <https://pandas.pydata.org>`_ can read query results from any ADBC driver via the ``adbc_driver_manager`` package. Because ADBC collects results as Arrow, the conversion to a pandas ``DataFrame`` is efficient and avoids unnecessary copies.
+
+.. code-block:: python
+
+ import adbc_driver_manager.dbapi as dbapi
+ import pandas as pd
+
+ # The postgresql driver must be installed first with: dbc install postgresql
+ with dbapi.connect(driver="postgresql", uri="postgresql://localhost:5432/mydb") as conn:
+ df = pd.read_sql("SELECT * FROM orders", conn)
+
+ADBC connections are compatible with ``pd.read_sql``, ``pd.read_sql_query``, and ``pd.read_sql_table``.
+
+See the recipe :ref:`Using Pandas and ADBC <recipe-postgresql-pandas>` for more examples.
+
+----
+
+Polars
+======
+
+`Polars <https://pola.rs>`_ has native ADBC support via ``read_database`` and ``write_database``. ADBC provides zero-copy Arrow transfer between Polars and the database.
+
+.. code-block:: python
+
+ import adbc_driver_manager.dbapi as dbapi
+ import polars as pl
+
+ # The postgresql driver must be installed first with: dbc install postgresql
+ with dbapi.connect(driver="postgresql", uri="postgresql://localhost:5432/mydb") as conn:
+ # Read from a database
+ df = pl.read_database(
+ query="SELECT * FROM orders",
+ connection=conn,
+ )
+
+ # Write to a database
+ df.write_database(
+ table_name="orders_copy",
+ connection=conn,
+ )
+
+See the `Polars database documentation <https://docs.pola.rs/user-guide/io/database/>`_ for more details.
+
+----
+
+R adbi
+======
+
+In R, the `adbi <https://adbi.r-dbi.org>`__ package provides a `DBI <https://github.com/r-dbi>`__ compliant interface to ADBC drivers.
+
+.. code-block:: r
+
+ library(DBI)
+
+ # Create an SQLite connection via adbi
+ con <- dbConnect(adbi::adbi(adbcdrivermanager::adbc_driver("sqlite")))
+
+ # Write a data.frame to a table in SQLite
+ dbWriteTable(con, "swiss", datasets::swiss)
+
+ # Query it back
+ dbGetQuery(con, "SELECT * from swiss WHERE Agriculture < 40")
+
+ # Take advantage of DBI's Arrow extension API to return results as Arrow (using nanoarrow)
+ dbGetQueryArrow(con, "SELECT * from swiss WHERE Agriculture < 40")
+
+R dplyr
+=======
+
+In R, `dplyr <https://dplyr.tidyverse.org>`__ accesses databases through the `DBI <https://dbi.r-dbi.org>`__ interface. The ``adbcdrivermanager`` package provides a DBI-compatible backend so you can use any ADBC driver with dplyr and ``dbplyr``.
+
+.. code-block:: r
+
+ library(adbi)
+ library(dplyr)
+
+ con <- DBI::dbConnect(
+ adbi(adbcdrivermanager::adbc_driver("postgresql")),
+ uri = "postgresql://localhost:5432/mydb"
+ )
+
+ orders <- tbl(con, "orders") |>
+ filter(status == "shipped") |>
+ collect()
+
+----
+
+Ruby Active Record
+==================
+
+The `activerecord-adbc-adapter <https://github.com/red-data-tools/activerecord-adbc-adapter>`_ gem allows you to use ADBC drivers as Active Record database adapters, enabling efficient Arrow-based database interaction for Rails applications.
+
+See the `activerecord-adbc-adapter documentation <https://www.rubydoc.info/gems/activerecord-adbc-adapter/>`_ for configuration options.
+
+----
+
+
+Add Your Own Here
+=================
+
+Know of an integratoin or tool not listed here? Contributions to this page are welcome via pull requests on `GitHub <https://github.com/apache/arrow-adbc>`_.
diff --git a/docs/source/java/jni.rst b/docs/source/java/jni.rst
index 1fbe0a550..920304afc 100644
--- a/docs/source/java/jni.rst
+++ b/docs/source/java/jni.rst
@@ -49,7 +49,7 @@ written in Java or another JVM language.
Drivers can be directly loaded via the
:external+java_adbc:jmember:`PARAM_DRIVER
-<org.apache.arrow.adbc.driver.jni.JniDriver#PARAM_PROFILE>` option. This takes
+<org.apache.arrow.adbc.driver.jni.JniDriver#PARAM_DRIVER>` option. This takes
a path to a driver, a :doc:`driver manifest <../format/driver_manifests>`, or
a name that will be passed to ``dlopen`` (or equivalent):
diff --git a/docs/source/java/quickstart.rst b/docs/source/java/quickstart.rst
index 08f355557..15b92b9f8 100644
--- a/docs/source/java/quickstart.rst
+++ b/docs/source/java/quickstart.rst
@@ -19,7 +19,7 @@
Quickstart
==========
-Here we'll briefly tour basic features of ADBC with the PostgreSQL driver for Java.
+Here we'll briefly tour basic features of ADBC with Java :doc:`JNI driver manager <./jni>` and the PostgreSQL driver.
Installation
============
@@ -30,53 +30,76 @@ To include ADBC in your Maven project, add the following dependency:
<dependency>
<groupId>org.apache.arrow.adbc</groupId>
- <artifactId>adbc-driver-jdbc</artifactId>
+ <artifactId>adbc-driver-jni</artifactId>
<version>${adbc.version}</version>
</dependency>
+Installing Drivers
+------------------
+
+See :ref:`driver-table-install` for instructions on installing ADBC drivers for
+the database you want to connect to. For the example below, you could install
+`dbc <https://docs.columnar.tech/dbc>`__ and then install the PostgreSQL driver with:
+
+.. code-block:: shell
+
+ dbc install postgresql
+
+Imports
+-------
+
For the examples in this section, the following imports are required:
.. code-block:: java
+ import java.util.HashMap;
+ import java.util.Map;
import org.apache.arrow.adbc.core.AdbcConnection;
import org.apache.arrow.adbc.core.AdbcDatabase;
import org.apache.arrow.adbc.core.AdbcDriver;
import org.apache.arrow.adbc.core.AdbcException;
import org.apache.arrow.adbc.core.AdbcStatement;
+ import org.apache.arrow.adbc.driver.jni.JniDriver;
+ import org.apache.arrow.memory.BufferAllocator;
+ import org.apache.arrow.memory.RootAllocator;
-JDBC-style API
-==============
-
-ADBC provides a high-level API in the style of the JDBC standard.
-
-Usage
------
+Basic Usage
+===========
.. code-block:: java
- final Map<String, Object> parameters = new HashMap<>();
- AdbcDriver.PARAM_URI.set(parameters, "jdbc:postgresql://localhost:5432/postgres");
+ Map<String, Object> parameters = new HashMap<>();
+ JniDriver.PARAM_DRIVER.set(parameters, "postgresql");
+ AdbcDriver.PARAM_URI.set(parameters, "postgresql://localhost:5432/postgres");
try (
BufferAllocator allocator = new RootAllocator();
- AdbcDatabase db = new JdbcDriver(allocator).open(parameters);
+ AdbcDatabase db = new JniDriver(allocator).open(parameters);
AdbcConnection adbcConnection = db.connect();
- AdbcStatement stmt = adbcConnection.createStatement()
-
+ AdbcStatement stmt = adbcConnection.createStatement();
) {
stmt.setSqlQuery("select * from foo");
- AdbcStatement.QueryResult queryResult = stmt.executeQuery();
- while (queryResult.getReader().loadNextBatch()) {
- // process batch
+ try (AdbcStatement.QueryResult queryResult = stmt.executeQuery()) {
+ while (queryResult.getReader().loadNextBatch()) {
+ // process batch
+ }
}
- } catch (AdbcException e) {
+ } catch (AdbcException e) {
// throw
}
In application code, the connection must be closed after usage or memory may leak.
It is recommended to wrap the connection in a try-with-resources block for automatic
-resource management. In this example, we are connecting to a PostgreSQL database,
+resource management. In this example, we are connecting to a PostgreSQL database,
specifically the default database "postgres".
Note that creating a statement is also wrapped in the try-with-resources block.
Assuming we have a table "foo" in the database, an example for setting and executing the
query is also provided.
+
+Next Steps
+==========
+
+- Check out the :doc:`Java API documentation <index>` for more details
+- See the :doc:`drivers </driver/index>` to see which databases are supported
+- Explore more examples in the `adbc-quickstarts repository <https://github.com/columnar-tech/adbc-quickstarts/tree/main/java>`_
+- Explore the `Java source code <https://github.com/apache/arrow-adbc/tree/main/java>`_ for additional examples
diff --git a/docs/source/javascript/quickstart.rst b/docs/source/javascript/quickstart.rst
index f6fdeab6c..c60ff9393 100644
--- a/docs/source/javascript/quickstart.rst
+++ b/docs/source/javascript/quickstart.rst
@@ -19,8 +19,7 @@
Quickstart
==========
-Here we'll briefly tour basic features of ADBC with the SQLite driver for
-Node.js.
+Here we'll briefly tour basic features of ADBC with JavaScript using the SQLite driver for Node.js.
Installation
============
@@ -36,37 +35,32 @@ Installation
.. note::
- Node.js 22+, Deno 2.0+, or Bun 1.1+ are required.
+ Node.js 22+, Deno 2.0+, or Bun 1.1+ are required. This does not work in the
+ browser: the driver manager loads driver shared libraries from the
+ filesystem, which browsers cannot do.
-To use any driver with the JavaScript driver manager, you'll need install the
-appropriate driver shared library for your platform separately and pass the
-absolute path to the driver manager.
+Installing Drivers
+------------------
-Some examples for the SQLite driver are provided below for convenience:
-
-`conda-forge <https://conda-forge.org/>`_:
+See :ref:`driver-table-install` for instructions on installing ADBC drivers for
+the database you want to connect to. For the example below, you could install
+`dbc <https://docs.columnar.tech/dbc>`__ from npm with:
.. code-block:: shell
- conda create -n adbc-sqlite -c conda-forge adbc-driver-sqlite
- conda run -n adbc-sqlite python -c "import adbc_driver_sqlite; print(adbc_driver_sqlite._driver_path())"
+ npm install -g @columnar-tech/dbc
-`PyPI <https://pypi.org>`_:
+and then install the SQLite driver with:
.. code-block:: shell
- python -m venv .venv
- source .venv/bin/activate
- pip install adbc-driver-sqlite
- python -c "import adbc_driver_sqlite; print(adbc_driver_sqlite._driver_path())"
-
-For apt and dnf packages, see :doc:`/driver/installation`.
+ dbc install sqlite
Creating a Database and Connection
==================================
The entry point is :external+js_adbc:jsclass:`AdbcDatabase`. Pass a ``driver``
-option to identify the backend — either a short name (resolved via
+option to identify the backend—either a short name (resolved via
:doc:`/format/driver_manifests` search paths) or absolute path to a driver
shared library:
@@ -251,3 +245,11 @@ queries:
}
await stmt.close();
+
+Next Steps
+==========
+
+- Check out the :doc:`JavaScript API documentation <index>` for more details
+- See the :doc:`drivers </driver/index>` to see which databases are supported
+- Explore more examples in the `adbc-quickstarts repository <https://github.com/columnar-tech/adbc-quickstarts/tree/main/javascript>`_
+- Explore the `JavaScript source code <https://github.com/apache/arrow-adbc/tree/main/js>`_ for additional examples
diff --git a/docs/source/python/quickstart.rst b/docs/source/python/quickstart.rst
index 0aef7c97b..2a54c06b3 100644
--- a/docs/source/python/quickstart.rst
+++ b/docs/source/python/quickstart.rst
@@ -19,14 +19,31 @@
Quickstart
==========
-Here we'll briefly tour basic features of ADBC with the SQLite driver.
+Here we'll briefly tour basic features of ADBC with Python using the SQLite driver.
Installation
============
.. code-block:: shell
- pip install adbc_driver_manager adbc_driver_sqlite pyarrow
+ pip install adbc_driver_manager pyarrow
+
+Installing Drivers
+------------------
+
+See :ref:`driver-table-install` for instructions on installing ADBC drivers for
+the database you want to connect to. For the example below, you could install
+`dbc <https://docs.columnar.tech/dbc>`__ from PyPI with:
+
+.. code-block:: shell
+
+ pipx install dbc
+
+and then install the SQLite driver with:
+
+.. code-block:: shell
+
+ dbc install sqlite
DBAPI (PEP 249)-style API
=========================
@@ -43,10 +60,10 @@ Creating a Connection
---------------------
.. doctest:: dbapi
- :skipif: adbc_driver_sqlite is None
+ :skipif: adbc_driver_manager is None
- >>> import adbc_driver_sqlite.dbapi
- >>> conn = adbc_driver_sqlite.dbapi.connect()
+ >>> from adbc_driver_manager import dbapi
+ >>> conn = dbapi.connect("sqlite")
In application code, the connection must be closed after usage or
memory may leak. Connections can be used as context managers to
@@ -56,7 +73,7 @@ Creating a Cursor
-----------------
.. doctest:: dbapi
- :skipif: adbc_driver_sqlite is None
+ :skipif: adbc_driver_manager is None
>>> cursor = conn.cursor()
@@ -70,7 +87,7 @@ We can execute a query and get the results via the normal,
row-oriented DBAPI interface:
.. doctest:: dbapi
- :skipif: adbc_driver_sqlite is None
+ :skipif: adbc_driver_manager is None
>>> cursor.execute("SELECT 1, 2.0, 'Hello, world!'")
<adbc_driver_manager.dbapi.Cursor ...>
@@ -81,7 +98,7 @@ row-oriented DBAPI interface:
We can also get the results as Arrow data via a non-standard method:
.. doctest:: dbapi
- :skipif: adbc_driver_sqlite is None
+ :skipif: adbc_driver_manager is None
>>> cursor.execute("SELECT 1, 2.0, 'Hello, world!'")
<adbc_driver_manager.dbapi.Cursor ...>
@@ -101,7 +118,7 @@ Parameterized Queries
We can bind parameters in our queries:
.. doctest:: dbapi
- :skipif: adbc_driver_sqlite is None
+ :skipif: adbc_driver_manager is None
>>> cursor.execute("SELECT ? + 1 AS the_answer", parameters=(41,))
<adbc_driver_manager.dbapi.Cursor ...>
@@ -119,7 +136,7 @@ APIs also offer additional methods. For example, we can insert a
table of Arrow data into a new database table:
.. doctest:: dbapi
- :skipif: adbc_driver_sqlite is None
+ :skipif: adbc_driver_manager is None
>>> import pyarrow
>>> table = pyarrow.table([[1, 2], ["a", None]], names=["ints", "strs"])
@@ -133,7 +150,7 @@ table of Arrow data into a new database table:
We can also append to an existing table:
.. doctest:: dbapi
- :skipif: adbc_driver_sqlite is None
+ :skipif: adbc_driver_manager is None
>>> table = pyarrow.table([[2, 3], [None, "c"]], names=["ints", "strs"])
>>> cursor.adbc_ingest("sample", table, mode="append")
@@ -150,7 +167,7 @@ We can get information about the driver and the database using another
extension method, this time on the connection itself:
.. doctest:: dbapi
- :skipif: adbc_driver_sqlite is None
+ :skipif: adbc_driver_manager is None
>>> conn.adbc_get_info()["vendor_name"]
'SQLite'
@@ -162,7 +179,7 @@ a nested structure describing all the catalogs, schemas, tables, and
columns:
.. doctest:: dbapi
- :skipif: adbc_driver_sqlite is None
+ :skipif: adbc_driver_manager is None
>>> info = conn.adbc_get_objects().read_all().to_pylist()
>>> main_catalog = info[0]
@@ -176,8 +193,16 @@ columns:
We can get the Arrow schema of a table:
.. doctest:: dbapi
- :skipif: adbc_driver_sqlite is None
+ :skipif: adbc_driver_manager is None
>>> conn.adbc_get_table_schema("sample")
ints: int64
strs: string
+
+Next Steps
+==========
+
+- Check out the :doc:`Python API documentation <index>` for more details
+- See the :doc:`drivers </driver/index>` to see which databases are supported
+- Explore more examples in the `adbc-quickstarts repository <https://github.com/columnar-tech/adbc-quickstarts/tree/main/python>`_
+- Explore the `Python source code <https://github.com/apache/arrow-adbc/tree/main/python>`_ for additional examples
diff --git a/docs/source/python/recipe/driver_manager_lowlevel.py b/docs/source/python/recipe/driver_manager_lowlevel.py
index bbff7b9a1..314ab488b 100644
--- a/docs/source/python/recipe/driver_manager_lowlevel.py
+++ b/docs/source/python/recipe/driver_manager_lowlevel.py
@@ -27,11 +27,8 @@
import pyarrow
import adbc_driver_manager
-import adbc_driver_sqlite
-#: The driver packages do still have conveniences to create the root
-#: :class:`AdbcDatabase <adbc_driver_manager.AdbcDatabase>` object.
-db: adbc_driver_manager.AdbcDatabase = adbc_driver_sqlite.connect()
+db: adbc_driver_manager.AdbcDatabase = adbc_driver_manager.AdbcDatabase(driver="sqlite")
#: The database must then be wrapped in a :class:`AdbcConnection
#: <adbc_driver_manager.AdbcConnection>`. This is similar in scope to the
#: DB-API :class:`Connection <adbc_driver_manager.dbapi.Connection>` class.
diff --git a/docs/source/python/recipe/driver_manager_prepare.py b/docs/source/python/recipe/driver_manager_prepare.py
index c780a0702..53ea081d5 100644
--- a/docs/source/python/recipe/driver_manager_prepare.py
+++ b/docs/source/python/recipe/driver_manager_prepare.py
@@ -37,9 +37,9 @@
import pyarrow
-import adbc_driver_sqlite.dbapi
+from adbc_driver_manager import dbapi
-conn = adbc_driver_sqlite.dbapi.connect()
+conn = dbapi.connect("sqlite")
with conn.cursor() as cur:
param_schema = cur.adbc_prepare("SELECT ? + 1")
diff --git a/docs/source/python/recipe/flightsql_dremio_connect.py b/docs/source/python/recipe/flightsql_dremio_connect.py
index a8bd1a62b..bac33fde3 100644
--- a/docs/source/python/recipe/flightsql_dremio_connect.py
+++ b/docs/source/python/recipe/flightsql_dremio_connect.py
@@ -24,13 +24,14 @@
import os
-import adbc_driver_flightsql.dbapi
import adbc_driver_manager
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_DREMIO_FLIGHTSQL_URI"]
username = os.environ["ADBC_DREMIO_FLIGHTSQL_USER"]
password = os.environ["ADBC_DREMIO_FLIGHTSQL_PASS"]
-conn = adbc_driver_flightsql.dbapi.connect(
+conn = dbapi.connect(
+ "flightsql",
uri,
db_kwargs={
adbc_driver_manager.DatabaseOptions.USERNAME.value: username,
diff --git a/docs/source/python/recipe/flightsql_oauth_client_credentials.py b/docs/source/python/recipe/flightsql_oauth_client_credentials.py
index b1559bc1f..a34db6a88 100644
--- a/docs/source/python/recipe/flightsql_oauth_client_credentials.py
+++ b/docs/source/python/recipe/flightsql_oauth_client_credentials.py
@@ -23,8 +23,8 @@
import os
-import adbc_driver_flightsql.dbapi
from adbc_driver_flightsql import DatabaseOptions, OAuthFlowType
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_TEST_FLIGHTSQL_URI"]
token_uri = os.environ["ADBC_OAUTH_TOKEN_URI"]
@@ -48,7 +48,7 @@ db_kwargs = {
if os.environ.get("ADBC_OAUTH_SKIP_VERIFY", "true").lower() in ("1", "true"):
db_kwargs[DatabaseOptions.TLS_SKIP_VERIFY.value] = "true"
-conn = adbc_driver_flightsql.dbapi.connect(uri, db_kwargs=db_kwargs)
+conn = dbapi.connect("flightsql", uri, db_kwargs=db_kwargs)
#: We can then execute queries as usual.
diff --git a/docs/source/python/recipe/flightsql_oauth_token_exchange.py b/docs/source/python/recipe/flightsql_oauth_token_exchange.py
index d678f49c2..ad03a5df8 100644
--- a/docs/source/python/recipe/flightsql_oauth_token_exchange.py
+++ b/docs/source/python/recipe/flightsql_oauth_token_exchange.py
@@ -23,8 +23,8 @@
import os
-import adbc_driver_flightsql.dbapi
from adbc_driver_flightsql import DatabaseOptions, OAuthFlowType, OAuthTokenType
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_TEST_FLIGHTSQL_URI"]
token_uri = os.environ["ADBC_OAUTH_TOKEN_URI"]
@@ -57,7 +57,7 @@ db_kwargs.update(
}
)
-conn = adbc_driver_flightsql.dbapi.connect(uri, db_kwargs=db_kwargs)
+conn = dbapi.connect("flightsql", uri, db_kwargs=db_kwargs)
#: We can then execute queries as usual.
diff --git a/docs/source/python/recipe/flightsql_sqlite_connect.py b/docs/source/python/recipe/flightsql_sqlite_connect.py
index 97148e6d6..f7f5c8fd7 100644
--- a/docs/source/python/recipe/flightsql_sqlite_connect.py
+++ b/docs/source/python/recipe/flightsql_sqlite_connect.py
@@ -21,10 +21,10 @@
import os
-import adbc_driver_flightsql.dbapi
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_SQLITE_FLIGHTSQL_URI"]
-conn = adbc_driver_flightsql.dbapi.connect(uri)
+conn = dbapi.connect("flightsql", uri)
#: We can then execute a simple query.
diff --git a/docs/source/python/recipe/flightsql_sqlite_max_msg_size.py b/docs/source/python/recipe/flightsql_sqlite_max_msg_size.py
index 1a77460d5..c316980f2 100644
--- a/docs/source/python/recipe/flightsql_sqlite_max_msg_size.py
+++ b/docs/source/python/recipe/flightsql_sqlite_max_msg_size.py
@@ -26,8 +26,8 @@
import os
-import adbc_driver_flightsql.dbapi
from adbc_driver_flightsql import DatabaseOptions
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_SQLITE_FLIGHTSQL_URI"]
@@ -46,13 +46,13 @@ SELECT printf('%.*c', 16384, 'x') FROM generate_series
#: When we execute the query, we'll get an error.
-conn = adbc_driver_flightsql.dbapi.connect(uri)
+conn = dbapi.connect("flightsql", uri)
with conn.cursor() as cur:
cur.execute(query)
try:
cur.fetchallarrow()
- except adbc_driver_flightsql.dbapi.InternalError:
+ except dbapi.InternalError:
# This exception is expected.
pass
else:
@@ -62,7 +62,8 @@ conn.close()
#: We can instead change the limit when connecting.
-conn = adbc_driver_flightsql.dbapi.connect(
+conn = dbapi.connect(
+ "flightsql",
uri,
db_kwargs={DatabaseOptions.WITH_MAX_MSG_SIZE.value: "2147483647"},
)
diff --git a/docs/source/python/recipe/flightsql_sqlite_options.py b/docs/source/python/recipe/flightsql_sqlite_options.py
index 4dee1e617..af18605bc 100644
--- a/docs/source/python/recipe/flightsql_sqlite_options.py
+++ b/docs/source/python/recipe/flightsql_sqlite_options.py
@@ -21,12 +21,13 @@
import os
-import adbc_driver_flightsql.dbapi
from adbc_driver_flightsql import ConnectionOptions, DatabaseOptions
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_SQLITE_FLIGHTSQL_URI"]
#: We can enable cookie support, which some server implementations require.
-conn = adbc_driver_flightsql.dbapi.connect(
+conn = dbapi.connect(
+ "flightsql",
uri,
db_kwargs={DatabaseOptions.WITH_COOKIE_MIDDLEWARE.value: "true"},
)
diff --git a/docs/source/python/recipe/postgresql.rst b/docs/source/python/recipe/postgresql.rst
index 279a1ef69..886fcbd41 100644
--- a/docs/source/python/recipe/postgresql.rst
+++ b/docs/source/python/recipe/postgresql.rst
@@ -78,6 +78,8 @@ Connection pooling with SQLAlchemy
.. recipe:: postgresql_pool.py
+.. _recipe-postgresql-pandas:
+
Using Pandas and ADBC
=====================
diff --git a/docs/source/python/recipe/postgresql_authenticate.py b/docs/source/python/recipe/postgresql_authenticate.py
index 12fc3aced..1491be94b 100644
--- a/docs/source/python/recipe/postgresql_authenticate.py
+++ b/docs/source/python/recipe/postgresql_authenticate.py
@@ -31,10 +31,10 @@
import os
-import adbc_driver_postgresql.dbapi
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_POSTGRESQL_TEST_URI"]
-conn = adbc_driver_postgresql.dbapi.connect(uri)
+conn = dbapi.connect("postgresql", uri)
with conn.cursor() as cur:
cur.execute("SELECT 1")
diff --git a/docs/source/python/recipe/postgresql_autocommit.py b/docs/source/python/recipe/postgresql_autocommit.py
index 91ed787d8..94309a1c7 100644
--- a/docs/source/python/recipe/postgresql_autocommit.py
+++ b/docs/source/python/recipe/postgresql_autocommit.py
@@ -26,12 +26,12 @@
import os
-import adbc_driver_postgresql.dbapi
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_POSTGRESQL_TEST_URI"]
# Enable autocommit mode
-conn = adbc_driver_postgresql.dbapi.connect(uri, autocommit=True)
+conn = dbapi.connect("postgresql", uri, autocommit=True)
with conn.cursor() as cur:
# In autocommit mode, this statement is automatically committed
diff --git a/docs/source/python/recipe/postgresql_create_append_table.py b/docs/source/python/recipe/postgresql_create_append_table.py
index d21722eaf..b93b06202 100644
--- a/docs/source/python/recipe/postgresql_create_append_table.py
+++ b/docs/source/python/recipe/postgresql_create_append_table.py
@@ -25,10 +25,10 @@ import os
import pyarrow
-import adbc_driver_postgresql.dbapi
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_POSTGRESQL_TEST_URI"]
-conn = adbc_driver_postgresql.dbapi.connect(uri)
+conn = dbapi.connect("postgresql", uri)
#: For the purposes of testing, we'll first make sure the tables we're about
#: to use don't exist.
diff --git a/docs/source/python/recipe/postgresql_create_dataset_table.py b/docs/source/python/recipe/postgresql_create_dataset_table.py
index 3aba1fb72..31d5b2de1 100644
--- a/docs/source/python/recipe/postgresql_create_dataset_table.py
+++ b/docs/source/python/recipe/postgresql_create_dataset_table.py
@@ -31,10 +31,10 @@ import pyarrow.dataset
import pyarrow.feather
import pyarrow.parquet
-import adbc_driver_postgresql.dbapi
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_POSTGRESQL_TEST_URI"]
-conn = adbc_driver_postgresql.dbapi.connect(uri)
+conn = dbapi.connect("postgresql", uri)
#: For the purposes of testing, we'll first make sure the tables we're about
#: to use don't exist.
diff --git a/docs/source/python/recipe/postgresql_create_temp_table.py b/docs/source/python/recipe/postgresql_create_temp_table.py
index b9e6acca6..324af364b 100644
--- a/docs/source/python/recipe/postgresql_create_temp_table.py
+++ b/docs/source/python/recipe/postgresql_create_temp_table.py
@@ -24,10 +24,10 @@ import os
import pyarrow
-import adbc_driver_postgresql.dbapi
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_POSTGRESQL_TEST_URI"]
-conn = adbc_driver_postgresql.dbapi.connect(uri)
+conn = dbapi.connect("postgresql", uri)
#: For the purposes of testing, we'll first make sure the tables we're about
#: to use don't exist.
@@ -82,7 +82,7 @@ conn.close()
#: After closing the connection, the temporary table is implicitly dropped.
#: If we reconnect, the table won't exist; we'll see only the 'normal' table.
-with adbc_driver_postgresql.dbapi.connect(uri) as conn:
+with dbapi.connect("postgresql", uri) as conn:
with conn.cursor() as cur:
cur.execute("SELECT COUNT(*) FROM example")
assert cur.fetchone() == (2,)
diff --git a/docs/source/python/recipe/postgresql_execute_bind.py b/docs/source/python/recipe/postgresql_execute_bind.py
index d4d782ab4..0d47173d7 100644
--- a/docs/source/python/recipe/postgresql_execute_bind.py
+++ b/docs/source/python/recipe/postgresql_execute_bind.py
@@ -27,10 +27,10 @@ import os
import pyarrow
-import adbc_driver_postgresql.dbapi
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_POSTGRESQL_TEST_URI"]
-conn = adbc_driver_postgresql.dbapi.connect(uri)
+conn = dbapi.connect("postgresql", uri)
#: We'll create an example table to test.
with conn.cursor() as cur:
diff --git a/docs/source/python/recipe/postgresql_execute_nocopy.py b/docs/source/python/recipe/postgresql_execute_nocopy.py
index 8a250b88b..b2120cd8c 100644
--- a/docs/source/python/recipe/postgresql_execute_nocopy.py
+++ b/docs/source/python/recipe/postgresql_execute_nocopy.py
@@ -26,16 +26,16 @@
import os
-import adbc_driver_postgresql.dbapi
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_POSTGRESQL_TEST_URI"]
-conn = adbc_driver_postgresql.dbapi.connect(uri)
+conn = dbapi.connect("postgresql", uri)
#: The option can be set when creating the cursor:
with conn.cursor(
adbc_stmt_kwargs={
- adbc_driver_postgresql.StatementOptions.USE_COPY.value: False,
+ "adbc.postgresql.use_copy": False,
}
) as cur:
cur.execute("SHOW ALL")
@@ -50,7 +50,7 @@ with conn.cursor(
with conn.cursor() as cur:
cur.adbc_statement.set_options(
**{
- adbc_driver_postgresql.StatementOptions.USE_COPY.value: False,
+ "adbc.postgresql.use_copy": False,
}
)
cur.execute("SHOW ALL")
diff --git a/docs/source/python/recipe/postgresql_get_query_schema.py b/docs/source/python/recipe/postgresql_get_query_schema.py
index 5e9ccf15f..44b17dc7e 100644
--- a/docs/source/python/recipe/postgresql_get_query_schema.py
+++ b/docs/source/python/recipe/postgresql_get_query_schema.py
@@ -25,10 +25,10 @@ import os
import pyarrow
-import adbc_driver_postgresql.dbapi
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_POSTGRESQL_TEST_URI"]
-conn = adbc_driver_postgresql.dbapi.connect(uri)
+conn = dbapi.connect("postgresql", uri)
#: We'll create an example table to test.
with conn.cursor() as cur:
diff --git a/docs/source/python/recipe/postgresql_get_table_schema.py b/docs/source/python/recipe/postgresql_get_table_schema.py
index f81ae2e96..810914ca0 100644
--- a/docs/source/python/recipe/postgresql_get_table_schema.py
+++ b/docs/source/python/recipe/postgresql_get_table_schema.py
@@ -25,10 +25,10 @@ import os
import pyarrow
-import adbc_driver_postgresql.dbapi
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_POSTGRESQL_TEST_URI"]
-conn = adbc_driver_postgresql.dbapi.connect(uri)
+conn = dbapi.connect("postgresql", uri)
#: We'll create some example tables to test.
with conn.cursor() as cur:
diff --git a/docs/source/python/recipe/postgresql_list_catalogs.py b/docs/source/python/recipe/postgresql_list_catalogs.py
index 610674dcd..96b704991 100644
--- a/docs/source/python/recipe/postgresql_list_catalogs.py
+++ b/docs/source/python/recipe/postgresql_list_catalogs.py
@@ -23,10 +23,10 @@
import os
-import adbc_driver_postgresql.dbapi
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_POSTGRESQL_TEST_URI"]
-conn = adbc_driver_postgresql.dbapi.connect(uri)
+conn = dbapi.connect("postgresql", uri)
#: We'll create an example table to look for.
with conn.cursor() as cur:
diff --git a/docs/source/python/recipe/postgresql_pandas.py b/docs/source/python/recipe/postgresql_pandas.py
index eaf7973fb..ff4494e33 100644
--- a/docs/source/python/recipe/postgresql_pandas.py
+++ b/docs/source/python/recipe/postgresql_pandas.py
@@ -31,10 +31,10 @@ import os
import pandas as pd
-import adbc_driver_postgresql.dbapi
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_POSTGRESQL_TEST_URI"]
-conn = adbc_driver_postgresql.dbapi.connect(uri)
+conn = dbapi.connect("postgresql", uri)
#: We'll use :external:py:meth:`pd.DataFrame.to_sql <pandas.DataFrame.to_sql>`
#: to create a sample table.
diff --git a/docs/source/python/recipe/postgresql_pool.py b/docs/source/python/recipe/postgresql_pool.py
index c5e0764e8..8f4b45db1 100644
--- a/docs/source/python/recipe/postgresql_pool.py
+++ b/docs/source/python/recipe/postgresql_pool.py
@@ -29,11 +29,11 @@ import os
import sqlalchemy.pool
-import adbc_driver_postgresql.dbapi
+from adbc_driver_manager import dbapi
uri = os.environ["ADBC_POSTGRESQL_TEST_URI"]
-source = adbc_driver_postgresql.dbapi.connect(uri)
+source = dbapi.connect("postgresql", uri)
#: :meth:`adbc_driver_manager.dbapi.Connection.adbc_clone` opens a new
#: connection from an existing connection, sharing internal resources where
#: possible. For example, the PostgreSQL driver will share the internal OID
diff --git a/docs/source/python/recipe/sqlite_batch_rows.py b/docs/source/python/recipe/sqlite_batch_rows.py
index c880f3a9d..e34ded6ce 100644
--- a/docs/source/python/recipe/sqlite_batch_rows.py
+++ b/docs/source/python/recipe/sqlite_batch_rows.py
@@ -25,9 +25,9 @@
#: result set has many NULL rows up front, you may consider increasing the
#: batch size so that the driver can infer the correct types.
-import adbc_driver_sqlite.dbapi
+from adbc_driver_manager import dbapi
-conn = adbc_driver_sqlite.dbapi.connect()
+conn = dbapi.connect("sqlite")
#: First we'll set up a demo table with 1024 NULL values.
@@ -73,7 +73,7 @@ with conn.cursor() as cur:
with conn.cursor() as cur:
cur.adbc_statement.set_options(
**{
- adbc_driver_sqlite.StatementOptions.BATCH_ROWS.value: 2048,
+ "adbc.sqlite.query.batch_rows": 2048,
}
)
cur.execute("SELECT * FROM demo")
diff --git a/docs/source/r/index.rst b/docs/source/r/index.rst
index f54a4c3f2..e828e1856 100644
--- a/docs/source/r/index.rst
+++ b/docs/source/r/index.rst
@@ -19,19 +19,46 @@
R
===
-ADBC in R is implemented as a suite of R packages. Most users will
-interact with ADBC via the `adbcdrivermanager <adbcdrivermanager/index.html>`_
-package and use drivers that are also distributed as R packages. In
-addition to the low-level interface provided by adbcdrivermanager,
-you can use ``read_adbc()``, ``write_adbc()`` and ``execute_adbc()``
-to quickly interact with an ADBC connection or database.
+ADBC is available in R through the `adbcdrivermanager
+<adbcdrivermanager/index.html>`_ package, which provides a low-level interface
+along with the ``read_adbc()``, ``write_adbc()``, and ``execute_adbc()`` helpers
+for quickly interacting with an ADBC connection or database.
+
+Installation
+============
+
+.. code-block:: r
+
+ install.packages(c("adbcdrivermanager", "arrow", "tibble"))
+
+Installing Drivers
+------------------
+
+See :ref:`driver-table-install` for instructions on installing ADBC drivers for
+the database you want to connect to. For the example below, you could install
+`dbc <https://docs.columnar.tech/dbc>`__ and then install the SQLite driver with:
+
+.. code-block:: shell
+
+ dbc install sqlite
+
+Basic Example
+=============
+
+This example demonstrates connecting to SQLite, writing a table, querying it,
+and cleaning up.
.. code-block:: r
library(adbcdrivermanager)
- # Use the driver manager to connect to a database
- db <- adbc_database_init(adbcsqlite::adbcsqlite(), uri = ":memory:")
+ # Create a driver instance
+ drv <- adbc_driver("sqlite")
+
+ # Initialize the database
+ db <- adbc_database_init(drv, uri = ":memory:")
+
+ # Create a connection
con <- adbc_connection_init(db)
# Write a table
@@ -40,7 +67,7 @@ to quickly interact with an ADBC connection or database.
# Query it
con |>
- read_adbc("SELECT * from mtcars") |>
+ read_adbc("SELECT * FROM mtcars") |>
tibble::as_tibble()
# Clean up
@@ -49,14 +76,62 @@ to quickly interact with an ADBC connection or database.
adbc_connection_release(con)
adbc_database_release(db)
-See individual package documentation for installation and usage
-details specific to each driver.
+Working with Arrow Data
+=======================
+
+ADBC natively returns Arrow data, which you can work with directly:
+
+.. code-block:: r
----------------------
-Package documentation
----------------------
+ # Get results as an Arrow table
+ arrow_table <- con |>
+ read_adbc("SELECT * FROM mtcars") |>
+ arrow::as_arrow_table()
+
+ # For large result sets, use a record batch reader
+ reader <- con |>
+ read_adbc("SELECT * FROM large_table") |>
+ arrow::as_record_batch_reader()
+
+ # Process in chunks
+ while (!is.null(batch <- reader$read_next_batch())) {
+ # Process batch
+ print(nrow(batch))
+ }
+
+Parameterized Queries
+=====================
+
+You can use parameterized queries for safe SQL execution:
+
+.. code-block:: r
+
+ stmt <- adbc_statement_init(con)
+ adbc_statement_set_sql_query(stmt, "DELETE FROM mtcars WHERE cyl = ?")
+ adbc_statement_bind(stmt, data.frame(8L))
+ adbc_statement_execute_query(stmt)
+
+Package Documentation
+=====================
+
+The ``adbcdrivermanager`` package is the R client library, and provides
+the driver manager used in the examples above:
- `adbcdrivermanager <adbcdrivermanager/index.html>`_
+
+A few drivers are also built as R packages and distributed on CRAN:
+
- `adbcflightsql <adbcflightsql/index.html>`_
- `adbcpostgresql <adbcpostgresql/index.html>`_
- `adbcsqlite <adbcsqlite/index.html>`_
+
+In general, though, we recommend installing drivers as shared libraries (see
+`Installing Drivers`_), which works with far more databases than are available
+as R packages.
+
+Next Steps
+==========
+
+- See the :doc:`drivers </driver/index>` to see which databases are supported
+- Explore more examples in the `adbc-quickstarts repository <https://github.com/columnar-tech/adbc-quickstarts/tree/main/r>`_
+- Explore the `R source code <https://github.com/apache/arrow-adbc/tree/main/r>`_ for additional examples
diff --git a/docs/source/ruby/index.rst b/docs/source/ruby/index.rst
new file mode 100644
index 000000000..aa6ce5762
--- /dev/null
+++ b/docs/source/ruby/index.rst
@@ -0,0 +1,159 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied. See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+====
+Ruby
+====
+
+**Red ADBC** is the Ruby binding for ADBC, built on top of ADBC GLib.
+It is distributed as the `red-adbc gem on RubyGems
+<https://rubygems.org/gems/red-adbc>`__.
+
+Installation
+============
+
+``red-adbc`` depends on the native Arrow GLib and ADBC GLib libraries. The
+`rubygems-requirements-system
+<https://rubygems.org/gems/rubygems-requirements-system>`__ plugin installs
+these system dependencies automatically using your system package manager, so
+install it first.
+
+With ``gem``:
+
+.. code-block:: shell
+
+ gem install rubygems-requirements-system
+ gem install red-adbc
+
+Or, with Bundler, add the plugin and the gem to your ``Gemfile``:
+
+.. code-block:: ruby
+
+ source "https://rubygems.org"
+
+ plugin "rubygems-requirements-system"
+
+ gem "red-adbc"
+
+.. dropdown:: Installing the GLib libraries manually
+
+ The ``rubygems-requirements-system`` plugin installs the native Arrow GLib
+ and ADBC GLib libraries automatically. If it can't (for example, on an
+ unsupported package manager), install them yourself before installing
+ ``red-adbc``:
+
+ **macOS with Homebrew:**
+
+ .. code-block:: shell
+
+ brew install apache-arrow-glib apache-arrow-adbc-glib
+
+ **Debian/Ubuntu:**
+
+ .. code-block:: shell
+
+ sudo apt install libarrow-glib-dev libadbc-glib-dev
+
+ **RHEL-compatible distributions:**
+
+ .. code-block:: shell
+
+ sudo dnf install arrow-glib-devel adbc-glib-devel
+
+ **Windows with RubyInstaller/MSYS2 UCRT64:**
+
+ .. code-block:: shell
+
+ pacman -S --needed mingw-w64-ucrt-x86_64-arrow mingw-w64-ucrt-x86_64-arrow-adbc-glib
+
+Installing Drivers
+------------------
+
+You also need a driver for the database you want to connect to. See
+:ref:`driver-table-install` for instructions. For the example below, you could
+install `dbc <https://docs.columnar.tech/dbc>`__ and then install the PostgreSQL
+driver with:
+
+.. code-block:: shell
+
+ dbc install postgresql
+
+Basic Example
+=============
+
+This example demonstrates connecting to PostgreSQL, executing a query, and reading results.
+
+.. code-block:: ruby
+
+ require "adbc"
+
+ database = ADBC::Database.new
+
+ begin
+ database.set_option("driver", "postgresql")
+ database.set_option("uri", "postgresql://user:password@localhost:5432/database")
+ database.set_load_flags(ADBC::LoadFlags::DEFAULT)
+ database.init
+
+ database.connect do |connection|
+ table, = connection.query("SELECT * FROM my_table;")
+ puts table
+ end
+ ensure
+ database.release
+ end
+
+Working with Results
+====================
+
+ADBC returns results as Arrow tables, which you can process using the Arrow Ruby library:
+
+.. code-block:: ruby
+
+ require "adbc"
+
+ database = ADBC::Database.new
+
+ begin
+ database.set_option("driver", "postgresql")
+ database.set_option("uri", "postgresql://user:password@localhost:5432/database")
+ database.set_load_flags(ADBC::LoadFlags::DEFAULT)
+ database.init
+
+ database.connect do |connection|
+ table, = connection.query("SELECT * FROM my_table;")
+
+ # Access columns
+ puts "Columns: #{table.schema.fields.map(&:name)}"
+
+ # Iterate over rows
+ table.each_record_batch do |batch|
+ batch.each do |row|
+ puts row
+ end
+ end
+ end
+ ensure
+ database.release
+ end
+
+Next Steps
+==========
+
+- See the :doc:`drivers </driver/index>` to see which databases are supported
+- Explore more examples in the `adbc-quickstarts repository <https://github.com/columnar-tech/adbc-quickstarts/tree/main/ruby>`_
+- Explore the `Ruby source code <https://github.com/apache/arrow-adbc/tree/main/ruby>`_ for additional examples
diff --git a/docs/source/rust/driver_manager.rst b/docs/source/rust/driver_manager.rst
index 3000fc6a0..2717afdbb 100644
--- a/docs/source/rust/driver_manager.rst
+++ b/docs/source/rust/driver_manager.rst
@@ -35,14 +35,18 @@ Usage
.. code-block:: rust
use adbc_core::options::AdbcVersion;
- use adbc_core::{Database, Driver};
+ use adbc_core::{Database, Driver, LOAD_FLAG_DEFAULT};
use adbc_driver_manager::ManagedDriver;
- // You must build/locate the driver yourself
- let mut driver = ManagedDriver::load_dynamic_from_filename(
- "/PATH/TO/libadbc_driver_sqlite.so",
+ // load_from_name searches for a driver via driver manifest (e.g.
+ // "sqlite.toml"). See the driver manifests documentation for details on
+ // search paths.
+ let mut driver = ManagedDriver::load_from_name(
+ "sqlite",
None,
AdbcVersion::default(),
+ LOAD_FLAG_DEFAULT,
+ None,
)
.expect("Failed to load driver");
let db = driver
diff --git a/docs/source/rust/quickstart.rst b/docs/source/rust/quickstart.rst
index 472bd9f58..d67fa2f19 100644
--- a/docs/source/rust/quickstart.rst
+++ b/docs/source/rust/quickstart.rst
@@ -19,21 +19,16 @@
Quickstart
==========
-Here we'll briefly tour using ADBC with the `DataFusion`_ driver.
-
-.. _DataFusion: https://datafusion.apache.org/
-
-.. note:: The DataFusion driver is maintained by a third party, the ADBC Driver Foundry (https://adbc-drivers.org). We're using it here since we don't maintain any Rust-based drivers directly.
+Here we'll briefly tour basic features of ADBC with Rust using the SQLite driver.
Installation
============
-Add a dependency on ``adbc_core`` and ``adbc_datafusion``:
+Add a dependency on ``adbc_core`` and ``adbc_driver_manager``:
.. code-block:: shell
- cargo add adbc_core
- cargo add --git https://github.com/adbc-drivers/datafusion adbc-driver-datafusion
+ cargo add adbc_core adbc_driver_manager
.. note:: If you get a compiler error (E0308, mismatched types) and a note about
multiple versions of the arrow crates in the dependency graph when you
@@ -49,34 +44,52 @@ Add a dependency on ``adbc_core`` and ``adbc_datafusion``:
the `Version Incompatibility Hazards <https://doc.rust-lang.org/cargo/reference/resolver.html#version-incompatibility-hazards>`__
in the Cargo documentation for more information.
-Loading DataFusion
-==================
+Installing Drivers
+------------------
-Create a driver instance, then a database handle, and then finally a
-connection. (This is a bit redundant for something like DataFusion, but the
-intent is that the database handle can hold shared state that multiple
-connections can share.)
+See :ref:`driver-table-install` for instructions on installing ADBC drivers for
+the database you want to connect to. For the example below, you could install
+`dbc <https://docs.columnar.tech/dbc>`__ and then install the SQLite driver with:
-.. code-block:: rust
+.. code-block:: shell
+
+ dbc install sqlite
+
+Loading a Driver
+================
- // These traits must be in scope
- use adbc_core::{Connection, Database, Driver, Statement};
+Use ``ManagedDriver::load_from_name`` to locate and load a driver by name. The driver manager
+searches for a driver manifest (e.g. ``sqlite.toml``) in the directories controlled by
+``load_flags``. See :doc:`/format/driver_manifests` for details on manifest search paths.
- let mut driver = adbc_driver_datafusion::DataFusionDriver {};
+.. code-block:: rust
+
+ use adbc_core::options::AdbcVersion;
+ use adbc_core::{Connection, Database, Driver, Statement, LOAD_FLAG_DEFAULT};
+ use adbc_driver_manager::ManagedDriver;
+
+ let mut driver = ManagedDriver::load_from_name(
+ "sqlite",
+ None,
+ AdbcVersion::default(),
+ LOAD_FLAG_DEFAULT,
+ None,
+ )
+ .expect("Failed to load driver");
let db = driver.new_database().expect("Failed to create database handle");
let mut conn = db.new_connection().expect("Failed to create connection");
Running Queries
===============
-To run queries, we can create a statement and set a query:
+To run queries, create a statement and set a query:
.. code-block:: rust
let mut stmt = conn.new_statement().expect("Failed to create statement");
stmt.set_sql_query("SELECT 1").expect("Failed to set SQL query");
-We can then execute the query to get an Arrow ``RecordBatchReader``:
+Execute the query to get an Arrow ``RecordBatchReader``:
.. code-block:: rust
@@ -85,3 +98,11 @@ We can then execute the query to get an Arrow ``RecordBatchReader``:
let batch = batch.expect("Failed to read batch");
println!("{:?}", batch);
}
+
+Next Steps
+==========
+
+- Check out the :doc:`Rust API documentation <index>` for more details
+- See the :doc:`drivers </driver/index>` to see which databases are supported
+- Explore more examples in the `adbc-quickstarts repository <https://github.com/columnar-tech/adbc-quickstarts/tree/main/rust>`_
+- Explore the `Rust source code <https://github.com/apache/arrow-adbc/tree/main/rust>`_ for additional examples
diff --git a/go/adbc/README.md b/go/adbc/README.md
index 8c7fc78bc..bcc7d6bee 100644
--- a/go/adbc/README.md
+++ b/go/adbc/README.md
@@ -23,7 +23,7 @@ The `adbc` package provides Go interface definitions for using Arrow data and da
## Getting Started
-To give a brief tour of what you can do with the `adbc` package, we'll show a brief example of using the [SQLite driver](https://arrow.apache.org/adbc/current/driver/sqlite.html).
+To give a brief tour of what you can do with the `adbc` package, we'll show an example of working with an SQLite database.
### Installation
@@ -33,6 +33,12 @@ First, assuming you've already created a Go module, add the `drivermgr` package
go get github.com/apache/arrow-adbc/go/adbc/drivermgr
```
+You'll also need a driver for the database you want to connect to. Drivers are distributed as shared libraries; see the [ADBC driver documentation](https://arrow.apache.org/adbc/current/driver/index.html) for the full list and installation instructions. For this example, you could install [dbc](https://docs.columnar.tech/dbc/), a third-party command-line tool for installing ADBC drivers (maintained independently of the Apache Arrow project), and then install the SQLite driver with:
+
+```sh
+dbc install sqlite
+```
+
### Imports
For imports, all we really need is `github.com/apache/arrow-adbc/go/adbc/drivermgr` to start but we'll import a few more modules now because we'll use them later.
@@ -62,12 +68,12 @@ func GettingStarted() error {
Any program using ADBC will start with creating a `Database`, a `Connection` to that `Database`, and usually one or more `Statement` objects.
-First we create a `Database`, providing `adbc_driver_sqlite` as the name of the driver to load:
+First we create a `Database`, providing `sqlite` as the name of the driver to load:
```go
var drv drivermgr.Driver
db, err := drv.NewDatabase(map[string]string{
- "driver": "adbc_driver_sqlite",
+ "driver": "sqlite",
})
if err != nil {
return err
diff --git a/ruby/README.md b/ruby/README.md
index 4a61734e1..9921ad848 100644
--- a/ruby/README.md
+++ b/ruby/README.md
@@ -47,7 +47,7 @@ $ gem install red-adbc
```ruby
require "adbc"
-ADBC::Database.open(driver: "adbc_driver_sqlite",
+ADBC::Database.open(driver: "sqlite",
uri: ":memory:") do |database|
database.connect do |connection|
puts(connection.query("SELECT 1"))