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..2c1e0710 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#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#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: