From 49a4decaeed0578f59ffb29058f41b7f8b1ed7c4 Mon Sep 17 00:00:00 2001 From: Bryce Mecum Date: Mon, 20 Jul 2026 09:32:31 -0700 Subject: [PATCH 1/3] Update index.md Update index.md Update driver_list.md Update driver_manifest.md Update driver_manifest.md Update first_steps.md Update first_steps.md Update first_steps.md Update first_steps.md Update continuous_integration.md Update driver.md Update installing.md Update private_drivers.md Update python_notebooks.md Update python_notebooks.md Update config_level.md Update supported_platforms.md Update installing.md --- docs/concepts/driver.md | 12 ++++++------ docs/concepts/driver_list.md | 10 +++++++--- docs/concepts/driver_manifest.md | 8 ++++---- docs/getting_started/first_steps.md | 22 +++++++++++++--------- docs/guides/continuous_integration.md | 6 +++--- docs/guides/installing.md | 10 +++++----- docs/guides/private_drivers.md | 10 +++++----- docs/guides/python_notebooks.md | 12 ++++++------ docs/index.md | 8 ++++---- docs/reference/config_level.md | 6 +++--- docs/reference/supported_platforms.md | 6 +++--- 11 files changed, 59 insertions(+), 51 deletions(-) diff --git a/docs/concepts/driver.md b/docs/concepts/driver.md index 9488185b..5ba59a27 100644 --- a/docs/concepts/driver.md +++ b/docs/concepts/driver.md @@ -24,12 +24,12 @@ In the context of dbc, "driver" means "ADBC driver." It's ADBC drivers that dbc ## What Is an ADBC Driver? -At a high level, an ADBC driver is a library that wraps the client for the database you want to use and exposes that database to you with a consistent API: the [ADBC API](https://arrow.apache.org/adbc/main/format/specification.html). +At a high level, an ADBC driver is a library that wraps the client for the database you want to use and exposes that database to you with a consistent API: the [ADBC API](https://arrow.apache.org/adbc/current/format/specification.html). -For example, if you're using the [ADBC SQLite Driver](https://arrow.apache.org/adbc/main/driver/sqlite.html) in C++ code and you want to run a SQL query, you'd call two functions (in order): +For example, if you're using the [ADBC SQLite Driver](https://arrow.apache.org/adbc/current/driver/sqlite.html) in C++ code and you want to run a SQL query, you'd call two functions (in order): -- [`AdbcStatementSetSqlQuery`](https://arrow.apache.org/adbc/main/cpp/api/group__adbc-statement-sql.html#ga40254bb2c39711f5d2772cb78f349e4a) -- [`AdbcStatementExecuteQuery`](https://arrow.apache.org/adbc/main/cpp/api/group__adbc-statement.html#ga1f653045678d9d5d51780e37e3b644a6) +- [`AdbcStatementSetSqlQuery`](https://arrow.apache.org/adbc/current/cpp/api/group__adbc-statement-sql.html#ga40254bb2c39711f5d2772cb78f349e4a) +- [`AdbcStatementExecuteQuery`](https://arrow.apache.org/adbc/current/cpp/api/group__adbc-statement.html#ga1f653045678d9d5d51780e37e3b644a6) Inside the driver, these two functions call corresponding functions in the [SQLite API](https://www.sqlite.org/cintro.html): @@ -42,5 +42,5 @@ While there's no hard requirement for a driver to have a 1:1 correspondence like If you're interested in learning more about ADBC drivers or ADBC, check out these two pages: -- [How Drivers and the Driver Manager Work Together](https://arrow.apache.org/adbc/main/format/how_manager.html) -- [ADBC Frequently Asked Questions](https://arrow.apache.org/adbc/main/faq.html) +- [How Drivers and the Driver Manager Work Together](https://arrow.apache.org/adbc/current/format/how_manager.html) +- [ADBC Frequently Asked Questions](https://arrow.apache.org/adbc/current/faq.html) diff --git a/docs/concepts/driver_list.md b/docs/concepts/driver_list.md index d93bce86..f1893c1f 100644 --- a/docs/concepts/driver_list.md +++ b/docs/concepts/driver_list.md @@ -16,8 +16,12 @@ limitations under the License. # Driver List -The term "driver list" refers to the `dbc.toml` file managed by dbc. A driver list is ideal for checking into version control alongside your project. +The term "driver list" refers to the `dbc.toml` file managed by [dbc](../index.md). A driver list is a declarative way to specify which [drivers](./driver.md) your project needs, making it ideal for checking into [version control](../guides/version_control.md) alongside your project. -See the [driver list](../guides/driver_list.md) guide to learn how to use a driver list. -See the [driver list](../reference/driver_list.md) reference for information about the format of the file. +## Learn More + +- See the [driver list guide](../guides/driver_list.md) to learn how to create and use a driver list +- See the [driver list reference](../reference/driver_list.md) for detailed information about the file format +- Learn how to use driver lists in [continuous integration](../guides/continuous_integration.md) +- Understand how to manage driver lists in [version control](../guides/version_control.md) diff --git a/docs/concepts/driver_manifest.md b/docs/concepts/driver_manifest.md index e5581e15..dd58108a 100644 --- a/docs/concepts/driver_manifest.md +++ b/docs/concepts/driver_manifest.md @@ -16,11 +16,11 @@ limitations under the License. # Driver Manifest -The term "driver manifest" refers to an [ADBC Driver Manfifest](https://arrow.apache.org/adbc/current/format/driver_manifests.html). +The term "driver manifest" refers to an [ADBC Driver Manifest](https://arrow.apache.org/adbc/current/format/driver_manifests.html). -In short, a driver manifest is a metadata file that stores key information about a driver, including the information a [Driver Manager](./driver_manager.md) needs to load it. +In short, a driver manifest is a metadata file that stores key information about a [driver](./driver.md), including the information a [driver manager](./driver_manager.md) needs to load it. -For example, here's an example driver manifest for the MySQL ADBC driver: +For example, here's an example driver manifest for the [MySQL ADBC driver](https://docs.adbc-drivers.org/drivers/mysql): ```toml manifest_version = 1 @@ -38,4 +38,4 @@ version = '1.1.0' macos_arm64 = '/Users/user/Library/Application Support/ADBC/Drivers/mysql_macos_arm64_v0.1.0' ``` -Many details about how driver manifests work are outlined in the [ADBC Driver Manifests](https://arrow.apache.org/adbc/current/format/driver_manifests.html) documentation. +Many details about how driver manifests work are outlined in the [ADBC Driver Manifests](https://arrow.apache.org/adbc/current/format/driver_manifests.html) documentation. When you [install a driver](../guides/installing.md) with dbc, it creates and manages driver manifests for you automatically. diff --git a/docs/getting_started/first_steps.md b/docs/getting_started/first_steps.md index 2eff61e1..82033641 100644 --- a/docs/getting_started/first_steps.md +++ b/docs/getting_started/first_steps.md @@ -24,7 +24,7 @@ On this page, we'll break down using dbc into three steps: 2. Loading the driver with an ADBC driver manager 3. Using the driver to run queries -The process will be similar no matter which ADBC driver you are using but, for the purposes of this guide, we'll be using the BigQuery ADBC driver. +The process will be similar no matter which ADBC driver you are using but, for the purposes of this guide, we'll be using the [BigQuery ADBC driver](https://docs.adbc-drivers.org/drivers/bigquery). Once you're finished, you will have successfully installed, loaded, and used the BigQuery ADBC driver to query a [BigQuery public dataset](https://cloud.google.com/bigquery/public-data). @@ -32,7 +32,7 @@ Once you're finished, you will have successfully installed, loaded, and used the To run through the steps on this page, you'll need at a minimum, -- dbc (See [Installation](./installation.md)) +- [dbc](../index.md) (See [Installation](./installation.md)) - A recent Python installation with pip - The [Google Cloud CLI](https://cloud.google.com/cli) and a Google account to use it with @@ -69,9 +69,9 @@ If all went well, your credentials are now saved locally and the BigQuery driver ## Installing a Driver -Let's use dbc to install the BigQuery ADBC driver. +Let's use dbc to [install](../guides/installing.md) the BigQuery ADBC driver. -First, run `dbc search` to find the exact name of the driver: +First, run [`dbc search`](../reference/cli.md#search) to find the exact name of the driver: ```console @@ -108,13 +108,13 @@ $ dbc install bigquery Installed bigquery 1.0.0 to /Users/user/Library/Application Support/ADBC/Drivers ``` -The BigQuery ADBC driver is now installed and usable by any driver manager. +The BigQuery ADBC driver is now installed and usable by any [driver manager](../concepts/driver_manager.md). -For more information on on how to find drivers, see the [Finding Drivers](../guides/finding_drivers.md) guide. +For more information on how to find drivers, see the [Finding Drivers](../guides/finding_drivers.md) guide. To learn more about what happens when you install a driver, see the [Installing Drivers](../guides/installing.md) guide. ## Installing a Driver Manager -To load any driver you install with dbc, you'll need an ADBC driver manager. +To load any driver you [install](../guides/installing.md) with dbc, you'll need an [ADBC driver manager](../concepts/driver_manager.md). Let's install the driver manager for Python. To learn about how to install driver managers for other languages, see the [Installing a Driver Manager](../guides/driver_manager.md) guide. @@ -140,7 +140,7 @@ You're now ready to load the BigQuery driver and run some queries. ## Loading & Using a Driver -The `adbc_driver_manager` package provides a high-level [DBAPI-style](https://peps.python.org/pep-0249/) interface that may be familiar to you if you've connected to databases using Python before. +The `adbc_driver_manager` package provides a high-level [DBAPI-style](https://peps.python.org/pep-0249/) interface that may be familiar to you if you've connected to databases using Python before. For more details about the Python ADBC API, see the [Python ADBC documentation](https://arrow.apache.org/adbc/current/python/index.html). Import it like this: @@ -293,4 +293,8 @@ Now you've run through a complete example of the process outlined at the start o As mentioned above, the process will be similar for any driver so hopefully you can adapt the steps here to another database. -dbc can do a lot more than just install drivers. If you're interested in learning everything dbc can do, visit the [dbc CLI](../reference/cli.md) reference. +If you're interested in learning everything can do with ADBC and dbc, check out these guides: + +- [Managing drivers with driver lists](../guides/driver_list.md) +- [Using dbc in Python notebooks](../guides/python_notebooks.md) +- [Using dbc in continuous integration](../guides/continuous_integration.md) diff --git a/docs/guides/continuous_integration.md b/docs/guides/continuous_integration.md index 6732df65..3af0a580 100644 --- a/docs/guides/continuous_integration.md +++ b/docs/guides/continuous_integration.md @@ -16,13 +16,13 @@ limitations under the License. # Continuous Integration -dbc works well in non-interactive environments such as on continuous integration (CI) platforms. You may also want to read through our [Version Control](./version_control.md) guide as these two concepts are related. +[dbc](../index.md) works well in non-interactive environments such as on continuous integration (CI) platforms. You may also want to read through our [Version Control](./version_control.md) guide as these two concepts are related. For more information on installing dbc, see the [Installation](../getting_started/installation.md) guide. ## GitHub Actions We recommend using the [columnar-tech/setup-dbc](https://github.com/columnar-tech/setup-dbc) action if you're using [GitHub Actions](https://docs.github.com/en/actions) for CI. -As an example, here's a workflow that automatically installs all drivers listed in your [driver list](../concepts/driver_list.md) before running your tests: +As an example, here's a workflow that automatically [installs](./installing.md) all [drivers](../concepts/driver.md) listed in your [driver list](../concepts/driver_list.md) before running your tests: ```yaml name: Test @@ -45,7 +45,7 @@ See the [columnar-tech/setup-dbc README](https://github.com/columnar-tech/setup- ## Other CI Systems -To use dbc with other CI systems, we recommend using our command line installers because they will always install the latest version of dbc for whatever platform you run them on. +To use dbc with other CI systems, we recommend using our [command line installers](../getting_started/installation.md) because they will always install the latest version of dbc for whatever [platform](../reference/supported_platforms.md) you run them on. As an example for you to adapt to your system, here's a GitHub Actions workflow that installs and makes dbc available without using [columnar-tech/setup-dbc](https://github.com/columnar-tech/setup-dbc): diff --git a/docs/guides/installing.md b/docs/guides/installing.md index a584d9f9..2966c0de 100644 --- a/docs/guides/installing.md +++ b/docs/guides/installing.md @@ -16,12 +16,12 @@ limitations under the License. # Installing Drivers -Once you've [installed dbc](../getting_started/installation.md), the first thing you'll probably want to do is install a driver. +Once you've [installed dbc](../getting_started/installation.md), the first thing you'll probably want to do is install a [driver](../concepts/driver.md). But before you can install a driver, you need to know what drivers are available and how to refer to them. ## Finding a Driver -To find out what drivers are available, use `dbc search`: +To find out what [drivers](../concepts/driver.md) are available, use [`dbc search`](../reference/cli.md#search). For more details, see the [Finding Drivers](./finding_drivers.md) guide: ```console @@ -45,11 +45,11 @@ teradata [private] An ADBC driver for Teradata developed by Columnar ``` -The short names in lowercase on the left of the output are the names you need to pass to `dbc install`. +The short names in lowercase on the left of the output are the names you need to pass to [`dbc install`](../reference/cli.md#install). These drivers are available from Columnar's [driver registry](../concepts/driver_registry.md). !!! note - The drivers listed above with the `[private]` label require a license to use. See [Private Drivers](./private_drivers.md) to learn how to use these drivers. + The drivers listed above with the `[private]` label require a license to use. See [Private Drivers](./private_drivers.md) to learn how to use these drivers. ## Installing a Driver @@ -166,7 +166,7 @@ Where this installs depends on your operating system: !!! note - See [Manifest Location and Discovery](https://arrow.apache.org/adbc/main/format/driver_manifests.html#manifest-location-and-discovery) for complete documentation of where the ADBC driver managers will search for drivers. dbc has the same behavior. + See [Manifest Location and Discovery](https://arrow.apache.org/adbc/current/format/driver_manifests.html#manifest-location-and-discovery) for complete documentation of where the [ADBC driver managers](../concepts/driver_manager.md) will search for [drivers](../concepts/driver.md). dbc has the same behavior. !!! note diff --git a/docs/guides/private_drivers.md b/docs/guides/private_drivers.md index a68a83fb..e7168cc4 100644 --- a/docs/guides/private_drivers.md +++ b/docs/guides/private_drivers.md @@ -18,7 +18,7 @@ limitations under the License. {{ since_version('v0.2.0') }} -Most drivers available with dbc are hosted on Columnar's public [driver registry](../concepts/driver_registry.md). However, some of the drivers you see when you run `dbc search` may be marked with a `[private]` label. +Most [drivers](../concepts/driver.md) available with [dbc](../index.md) are hosted on Columnar's public [driver registry](../concepts/driver_registry.md). However, some of the drivers you see when you run [`dbc search`](../reference/cli.md#search) may be marked with a `[private]` label. To install and use these drivers, you must: @@ -29,7 +29,7 @@ Continue reading to learn how to log in and start a trial. ## Logging In -To log into Columnar's private driver registry, run `dbc auth login`. This will automatically create an account for you the first time you log in. +To log into Columnar's private [driver registry](../concepts/driver_registry.md), run [`dbc auth login`](../reference/cli.md#auth-login). This will automatically create an account for you the first time you log in. You will see the following in your terminal and your default web browser will be opened: @@ -52,7 +52,7 @@ Licenses can be obtained from the [Licenses](https://console.columnar.tech/licen dbc will automatically download your license if you: 1. Have an active license -2. Run `dbc install` with a private driver +2. Run [`dbc install`](../reference/cli.md#install) with a private driver #### Manual Install with dbc @@ -78,7 +78,7 @@ You may also use a custom location by setting the environment variable `XDG_DATA ## Logging Out -To log out, run `dbc auth logout`. +To log out, run [`dbc auth logout`](../reference/cli.md#auth-logout). By default, the `logout` command doesn't purge any driver licenses from your system and only removes your login credentials. If you wish remove the local copy of your license run: @@ -97,7 +97,7 @@ $ dbc auth logout --purge ## API Keys -dbc also supports logging in to private driver registries via API key. This is primarily intended for use in [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) systems or any system where logging in with a web browser is not possible. +dbc also supports logging in to private [driver registries](../concepts/driver_registry.md) via API key. This is primarily intended for use in [continuous integration](./continuous_integration.md) systems or any system where logging in with a web browser is not possible. To create an API key, open a web browser to your [API keys](https://console.columnar.tech/apikeys) page. diff --git a/docs/guides/python_notebooks.md b/docs/guides/python_notebooks.md index 7fd65dcd..48ae22a2 100644 --- a/docs/guides/python_notebooks.md +++ b/docs/guides/python_notebooks.md @@ -16,7 +16,7 @@ limitations under the License. # Python Notebooks -dbc can be installed and used directly in Python notebooks (such as [Jupyter](https://jupyter.org) or [Google Colab](https://colab.google)). +[dbc](../index.md) can be [installed](../getting_started/installation.md) and used directly in Python notebooks (such as [Jupyter](https://jupyter.org) or [Google Colab](https://colab.google)). Each of the following code blocks is designed to be executed as an individual cell in your notebook. Install the `dbc`, `adbc-driver-manager`, and `pyarrow` packages: @@ -25,7 +25,7 @@ Install the `dbc`, `adbc-driver-manager`, and `pyarrow` packages: %pip install dbc adbc_driver_manager pyarrow ``` -Install the `duckdb` driver: +Install the `duckdb` [driver](../concepts/driver.md): ```python !dbc install duckdb @@ -33,16 +33,16 @@ Install the `duckdb` driver: !!! note - This guide uses the DuckDB driver for simplicity. - To list all available drivers, run `!dbc search`. + This guide uses the [DuckDB driver](https://arrow.apache.org/adbc/current/driver/duckdb.html) for simplicity. + To list all available drivers, run `!dbc search`. See the [Finding Drivers](./finding_drivers.md) guide for more information. -Import the `dbapi` module: +Import the `dbapi` module from the [ADBC driver manager](../concepts/driver_manager.md): ```python from adbc_driver_manager import dbapi ``` -Connect to a database via ADBC, create a cursor, execute queries, and fetch the result as a PyArrow Table: +Connect to a database via [ADBC](https://arrow.apache.org/adbc/), create a cursor, execute queries, and fetch the result as a [PyArrow](https://arrow.apache.org/docs/python/) Table: ```python with ( diff --git a/docs/index.md b/docs/index.md index 9cd89c31..4f57d98e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1527,17 +1527,17 @@ dbc is the command-line tool for installing and managing [ADBC](https://arrow.ap let mut driver = ManagedDriver::load_from_name("trino", ... ) ``` -
For a more detailed walkthrough on how to use dbc, check out our [First steps](./getting_started/first_steps.md) page or any of our [Guides](./guides/index.md). +
For a more detailed walkthrough on how to use dbc, check out our [First Steps](./getting_started/first_steps.md) page or any of our [Guides](./guides/index.md). ## Features - Install pre-built [ADBC](https://arrow.apache.org/adbc) drivers with a single command -- Manage numerous drivers without conflicts -- Install drivers just for your user or system-wide - Create reproducible environments with [driver list](concepts/driver_list.md) files -- Cross-platform: Runs on macOS, Linux, and Windows - Installable with pip, Docker, and more (See [Installation](./getting_started/installation.md)) - Works great in CI/CD environments (See [Continuous Integration](./guides/continuous_integration.md)) +- Manage numerous [drivers](./concepts/driver.md) without conflicts using [driver manifests](./concepts/driver_manifest.md) +- Install drivers just for your user or [system-wide](./reference/config_level.md) +- Cross-platform: Runs on [macOS, Linux, and Windows](./reference/supported_platforms.md) ## Help diff --git a/docs/reference/config_level.md b/docs/reference/config_level.md index a076dbc4..cdfa94db 100644 --- a/docs/reference/config_level.md +++ b/docs/reference/config_level.md @@ -16,12 +16,12 @@ limitations under the License. # Config Level Reference -Various dbc subcommands (like [install](cli.md#install), [sync](cli.md#sync), [list](cli.md#list)) take a `--level` argument which gives you control over where dbc installs or looks for drivers. +Various [dbc](../index.md) subcommands (like [install](cli.md#install), [sync](cli.md#sync), [list](cli.md#list)) take a `--level` argument which gives you control over where dbc installs or looks for [drivers](../concepts/driver.md). ## Default Behavior When the `--level` argument is not explicitly set for the command you are running, dbc first searches a list of environment variables, before defaulting to the [User](#user) level. -When `--level` is explicitly set, dbc installs drivers in that level and ignores any environment variables that might be set. +When `--level` is explicitly set, dbc [installs drivers](../guides/installing.md) in that level and ignores any environment variables that might be set. dbc searches the following environment variables, in order: @@ -54,4 +54,4 @@ For example, if you are in a Python virtual environment, you can still override ## More Info -See [ADBC Driver Manager and Manifests](https://arrow.apache.org/adbc/main/format/driver_manifests.html) for more detail. +See [ADBC Driver Manager and Manifests](https://arrow.apache.org/adbc/current/format/driver_manifests.html) for more detail. For information on installing the ADBC driver manager for your language, see the [Installing a Driver Manager](../guides/driver_manager.md) guide. diff --git a/docs/reference/supported_platforms.md b/docs/reference/supported_platforms.md index 8ddf860b..c786ed2b 100644 --- a/docs/reference/supported_platforms.md +++ b/docs/reference/supported_platforms.md @@ -16,7 +16,7 @@ limitations under the License. # Supported Platforms -dbc is supported on the following platforms: +[dbc](../index.md) is supported on the following platforms: - macOS (Apple Silicon) - macOS (Intel) @@ -28,8 +28,8 @@ dbc is developed, tested, and packaged for these platforms. If you find any prob ## Driver Support -Drivers that you can install with dbc are generally available for all of the above platforms. -When dbc [installs](../guides/installing.md) a driver, it tries to find a driver matching the platform it's being run on and will return an error if one isn't found. +[Drivers](../concepts/driver.md) that you can [install](../guides/installing.md) with dbc are generally available for all of the above platforms. +When dbc installs a driver, it automatically detects your platform and tries to find a [driver package](../concepts/driver_manifest.md) matching your system. If a driver isn't available for your platform, you'll receive an error. For example, on arm64 Windows you would get this error: From e785259ca1dd1b2bd42382a0f98e1c9aba5e8a15 Mon Sep 17 00:00:00 2001 From: Bryce Mecum Date: Wed, 22 Jul 2026 11:15:30 -0700 Subject: [PATCH 2/3] Update docs/guides/private_drivers.md Co-authored-by: Ian Cook --- docs/guides/private_drivers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/private_drivers.md b/docs/guides/private_drivers.md index e7168cc4..f8872248 100644 --- a/docs/guides/private_drivers.md +++ b/docs/guides/private_drivers.md @@ -29,7 +29,7 @@ Continue reading to learn how to log in and start a trial. ## Logging In -To log into Columnar's private [driver registry](../concepts/driver_registry.md), run [`dbc auth login`](../reference/cli.md#auth-login). This will automatically create an account for you the first time you log in. +To log into Columnar's private [driver registry](../concepts/driver_registry.md), run [`dbc auth login`](../reference/cli.md#login). This will automatically create an account for you the first time you log in. You will see the following in your terminal and your default web browser will be opened: From c122ebf46da6faf4bf077970cc8b6b3b8b0f6bb8 Mon Sep 17 00:00:00 2001 From: Bryce Mecum Date: Wed, 22 Jul 2026 11:15:37 -0700 Subject: [PATCH 3/3] Update docs/guides/private_drivers.md Co-authored-by: Ian Cook --- docs/guides/private_drivers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/private_drivers.md b/docs/guides/private_drivers.md index f8872248..2c1e0710 100644 --- a/docs/guides/private_drivers.md +++ b/docs/guides/private_drivers.md @@ -78,7 +78,7 @@ You may also use a custom location by setting the environment variable `XDG_DATA ## Logging Out -To log out, run [`dbc auth logout`](../reference/cli.md#auth-logout). +To log out, run [`dbc auth logout`](../reference/cli.md#logout). By default, the `logout` command doesn't purge any driver licenses from your system and only removes your login credentials. If you wish remove the local copy of your license run: