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:

$ dbc search
bigquery           An ADBC driver for Google BigQuery developed by the ADBC Driver Foundry
databricks         An ADBC Driver for Databricks developed by the ADBC Driver Foundry
duckdb             An ADBC driver for DuckDB developed by the DuckDB Foundation
flightsql          An ADBC driver for Apache Arrow Flight SQL developed under the Apache Software Foundation
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
redshift           An ADBC driver for Amazon Redshift developed by Columnar
snowflake          An ADBC driver for Snowflake developed under the Apache Software Foundation
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.

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

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

When dbc updates a driver like this, the old driver is uninstalled first. ADBC driver manifests provide a mechanism to support having multiple versions of the same driver installed at the same time and dbc may provide a convenient way to do this in a future release.

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

$ tree $ADBC_DRIVER_PATH
/home/user/drivers
├── mysql_linux_amd64_v0.1.0
│   ├── libadbc_driver_mysql.so
│   ├── libadbc_driver_mysql.so.sig
│   ├── LICENSE
│   └── NOTICE
└── mysql.toml

2 directories, 5 files

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.

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 insted 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").

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