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
• 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

The short names in lowercase on the left of the output are the names you need to pass to dbc install.

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 specifiying 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 *).

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 enviroments 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 enviroments before Conda environments.

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:

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