Skip to content

Installing Drivers

Once you've installed dbc, the first thing you'll probably want to do is install a driver. 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. For more details, see the Finding Drivers guide:

$ dbc search
bigquery             An ADBC driver for Google BigQuery developed by the ADBC Driver Foundry
chdb                 An embedded ADBC driver powered by ClickHouse
clickhouse           An ADBC driver for ClickHouse developed by ClickHouse, Inc.
databricks           An ADBC Driver for Databricks developed by the ADBC Driver Foundry
datafusion           An ADBC driver for Apache DataFusion developed by the ADBC Driver Foundry
duckdb               An ADBC driver for DuckDB developed by the DuckDB Foundation
exasol               An ADBC driver for Exasol developed by Exasol Labs
firebolt             An ADBC driver for Firebolt
flightsql            An ADBC driver for Apache Arrow Flight SQL developed under the Apache Software Foundation
mariadb              An ADBC Driver for MariaDB developed by the ADBC Driver Foundry
mssql                An ADBC driver for Microsoft SQL Server developed by Columnar
mysql                An ADBC Driver for MySQL developed by the ADBC Driver Foundry
postgresql           An ADBC driver for PostgreSQL developed under the Apache Software Foundation
quack                An ADBC driver for remote DuckDB via Quack
redshift             An ADBC driver for Amazon Redshift developed by Columnar
snowflake            An ADBC driver for Snowflake developed under the Apache Software Foundation
spark                An ADBC driver for Apache Spark developed by the ADBC Driver Foundry
sqlite               An ADBC driver for SQLite developed under the Apache Software Foundation
trino                An ADBC Driver for Trino developed by the ADBC Driver Foundry
oracle     [private] An ADBC driver for Oracle Database developed by Columnar
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. These drivers are available from the public ADBC driver registry.

Note

The drivers listed above with the [private] label require a license to use. See Private Drivers to learn how to use these drivers.

Installing a Driver

To install a specific driver, such as mysql, run:

$ dbc install mysql
[✓] searching
[✓] downloading
[✓] installing
[✓] verifying signature

Installed mysql 0.1.0 to /Users/user/Library/Application Support/ADBC/Drivers

Local package archives must include a driver payload named by Files.driver.

To confirm the driver is installed, run dbc list:

$ dbc list
DRIVER  VERSION  LEVEL  LOCATION

mysql   0.1.0    user   /Users/user/Library/Application Support/ADBC/Drivers

Version Constraints

By default, dbc installs the latest version of the package you specify. To install a specific version, you can pass a version constraint with the name:

$ dbc install "mysql=0.1.0"

The syntax for specifying a version may be familiar to you if you've used other package managers.

Note

dbc uses the github.com/Masterminds/semver/v3 package whose README has a good overview of the syntax it allows. In short, you can use =, !=, >, <, >=, <=, ~, ^, ranges like 1.2 - 1.4.5, and wildcards (x, X, or *).

Pre-release Versions

SINCE v0.2.0

Allowing Pre-release Versions

By default, dbc acts as if pre-release versions don't exist when searching for and installing drivers. Pre-release versions follow semantic versioning conventions and include version identifiers like 1.0.0-alpha.1, 2.0.0-beta.3, or 1.5.0-rc.1.

To allow dbc to install a pre-release version when it's the newest version available, use the --pre flag:

$ dbc install --pre mysql

This will allow dbc to consider pre-release versions when selecting the latest version to install.

Note

The --pre flag allows dbc to install a pre-release version when you didn't ask for it explicitly. Without --pre, your version constraint must contain a pre-release suffix (like -beta.1) for dbc to consider pre-release versions.

Installing Specific Pre-release Versions

You can install a specific pre-release version without using the --pre flag if your version constraint unambiguously references a pre-release by including a pre-release suffix:

$ dbc install "mysql=1.0.0-beta.1"
$ dbc install "mysql>=1.0.0-beta.1"

However, if your version constraint is ambiguous and only a pre-release version satisfies it, dbc will fail rather than install the pre-release. For example, if a driver has versions 0.1.0 and 0.1.1-beta.1:

$ dbc install "mysql>0.1.0"
# This will FAIL, not install 0.1.1-beta.1

To install 0.1.1-beta.1 in this case, you must either:

  • Use --pre: dbc install --pre "mysql>0.1.0"
  • Reference the pre-release explicitly: dbc install "mysql>=0.1.1-beta.1"

Updating a Driver

dbc doesn't offer a specific "update" or "upgrade" command but dbc install can do essentially the same thing.

For example, if you were to run dbc install mysql and get version 0.1.0, if — at some point in the future — version 0.2.0 were to be released, re-running dbc install mysql would upgrade your installed version to 0.2.0.

Note

dbc prepares and validates the new package before replacing the driver registration. It then makes a conservative attempt to clean up the previous owned payload.

Installing System Wide

By default, dbc installs drivers to the standard user-level ADBC driver path suitable for your system:

  • macOS: ~/Library/Application Support/ADBC/Drivers
  • Linux: ~/.config/adbc/drivers
  • Windows: %LOCAL_APPDATA%\ADBC\Drivers

Numerous dbc subcommands, including install, accept an optional --level flag which can used to install drivers system-wide. Note that we run this command with sudo because otherwise the directory may not be writable:

$ sudo dbc install --level system mysql
[✓] searching
[✓] downloading
[✓] installing
[✓] verifying signature

Installed mysql 0.1.0 to /Library/Application Support/ADBC/Drivers

Where this installs depends on your operating system:

  • macOS: /Library/Application Support/ADBC/Drivers
  • Linux: /etc/adbc/drivers
  • Windows: C:\Program Files\ADBC\Drivers

Note

See Manifest Location and Discovery for complete documentation of where the ADBC driver managers will search for drivers. dbc has the same behavior.

Note

Also see the Config Level reference for more detail on this behavior.

ADBC_DRIVER_PATH

For complete control over where dbc installs drivers, set the ADBC_DRIVER_PATH environment variable to a path (or list of paths) where you want to install drivers. For example:

$ mkdir "$HOME/drivers"
$ export ADBC_DRIVER_PATH="$HOME/drivers"
$ dbc install mysql

[✓] searching
[✓] downloading
[✓] installing
[✓] verifying signature

Installed mysql 0.1.0 to /home/user/drivers

$ ls "$ADBC_DRIVER_PATH"
mysql.toml

dbc stores the package payload in a hidden .dbc-package-g-* subdirectory of the same directory. dbc may also leave small hidden lock files (such as .dbc.* or .<driver>.dbc) there; they are safe to leave in place.

Note

If you set $ADBC_DRIVER_PATH environment variable with dbc, you will also need to re-use the same shell or set it in your ADBC driver manager code explicitly. For example:

import os
from pathlib import Path

from adbc_driver_manager import dbapi

os.environ["ADBC_DRIVER_PATH"] = str(Path.home() / "drivers")

with dbapi.connect(driver="mysql") as con:
  pass

Python Support

By default, dbc automatically detects whether you've activated a Python virtual environment and will install (and uninstall) drivers from the virtual environment rather than the user or system-level paths.

~/tmp/my-adbc-project
$ python3 -m venv .venv

~/tmp/my-adbc-project
$ source .venv/bin/activate.fish

~/tmp/my-adbc-project
.venv $ dbc install mysql
[✓] searching
[✓] downloading
[✓] installing
[✓] verifying signature

Installed mysql 0.1.0 to /Users/user/tmp/my-adbc-project/.venv/etc/adbc/drivers

Note

ADBC_DRIVER_PATH takes precedence over a virtual environment. dbc (and ADBC driver managers) use the following precedence hierarchy: ADBC_DRIVER_PATH before virtual environments before Conda environments.

Conda Support

By default, dbc automatically detects whether you've activated a Conda environment and will install (and uninstall) drivers from the Conda environment rather than the user or system-level paths.

$ conda create -n my-adbc-project
$ conda activate my-adbc-project
my-adbc-project $ dbc install mysql
[✓] searching
[✓] downloading
[✓] installing
[✓] verifying signature

Installed mysql 0.1.0 to /opt/homebrew/Caskroom/miniforge/base/envs/my-adbc-project/etc/adbc/drivers

Note

ADBC_DRIVER_PATH and/or an activated Python virtual environment will take precedence over a Conda environment. dbc (and ADBC driver managers) use the following precedence hierarchy: ADBC_DRIVER_PATH before virtual environments before Conda environments.

Archive Verification

When the registry publishes a SHA-256 hash for a package, dbc checks the downloaded archive against it before installing anything. If the hash does not match, the installation is aborted and any existing installation of the driver is left in place. The --no-verify flag skips only signature verification; it does not skip this archive hash check. Packages from registries that don't publish a hash are not checked this way.

From Local Archive

dbc can install drivers from local archives as an alternative for users who can't or don't want to install from a Driver Registry. This is meant for advanced use cases and requires understanding the ADBC Driver Manifests spec and loading process.

To install from a local archive, pass the path to a local archive instead of a name and set the --no-verify flag to skip signature verification:

$ dbc install --no-verify some_driver.tar.gz
Installing from local package: some_driver.tar.gz

[✓] installing
[-] verifying signature

Installed some_driver 1.0.0 to /Users/user/Library/Application Support/ADBC/Drivers

Note

Make note of the name "some_driver" printed above as this will be the name to use when loading the driver with a Driver Manager. i.e., dbapi.connect(driver="some_driver").

GitHub Actions

To use dbc with GitHub Actions, we recommend the official columnar-tech/setup-dbc action. See the Continuous Integration guide for more detail and examples.

Uninstalling Drivers

You can uninstall a driver with the dbc uninstall subcommand.

$ dbc uninstall mysql

Driver `mysql` uninstalled successfully!

Similar to the install command, dbc uninstall takes a --level argument. If, for example, you installed a driver with --level system, you would want also pass that argument to dbc uninstall:

$ sudo dbc install --level system mysql
$ sudo dbc uninstall --level system mysql

Since it's possible to install the same driver to multiple locations, dbc will only uninstall the first driver it finds. dbc will search in the following order:

  1. Environment
    1. ADBC_DRIVER_PATH
    2. VIRTUAL_ENV
    3. CONDA_PREFIX
  2. User
  3. System

Uninstall removes an owned driver payload when safe cleanup is available, while external registrations are removed without deleting their libraries; package files may remain on platforms such as WebAssembly. Metadata from legacy installs may remain after the driver library is removed.

In Go programs, config.UninstallDriverShared was removed in v0.4; use config.UninstallDriver or Client.Uninstall instead.