Using a Driver List
dbc can create and manage lists of drivers using a driver list file.
By default, a driver list has the name dbc.toml, though this can be overridden.
Note
This functionality is similar to files from other tools such as Python's requirements.txt.
A driver list is ideal for checking into version control alongside your project and is useful for recording not only which drivers your project needs but also the specific versions of each.
Creating a Driver List
Create a driver list with dbc init:
Driver lists uses the TOML format and contains a TOML table of drivers. See the driver list reference for more detail.
Adding a Driver
While you can edit dbc.toml manually, dbc has subcommands for working with the list.
To add a driver to the list, use dbc add:
$ dbc add mysql
added mysql to driver list
use `dbc sync` to install the drivers in the list
$ cat dbc.toml
[drivers]
[drivers.mysql]
When run, the add command automatically checks that a driver matching the pattern exists in the driver index and will fail if a matching driver can't be found.
Note
dbc add accepts the same syntax for driver names and versions as dbc install. See the Installing Drivers.
If you look closely at the above output, you'll notice that it's telling you to run dbc sync to install the driver(s) in the list. This is because dbc add only modifies the driver list and you need to use dbc sync to actually install the driver you just added.
Synchronizing
Use dbc sync to ensure that all the drivers in a driver list are installed:
The first time you run dbc sync, dbc creates a lockfile in the same directory as the driver list.
By default, this file is called dbc.lock but will match the name of your driver list file if you choose to use a custom one.
When you run dbc sync and a lockfile already exists, dbc will install the exact versions in the lockfile.
To upgrade the versions in the lockfile, delete the lockfile and run dbc sync.
Lockfile
dbc sync automatically creates a lockfile file in the same directory as the driver list. By default, this file is called dbc.lock but will match the name of your driver list file if you choose to use a custom one.
The lockfile records the exact version of the drivers that were installed, including version, platform, and a checksum:
$ cat dbc.lock
version = 1
[[drivers]]
name = 'mysql'
version = '0.1.0'
platform = 'macos_arm64'
checksum = 'e989f8c49262359093f03e2f43a796b163d2774de519e07cef14ebd63590c81d'
Every time you run dbc sync, this file is updated with the exact information about each driver that was installed.
It's a good idea to track dbc.lock as well as dbc.toml in version control if you want to ensure a completely reproducible set of drivers.
Version Constraints
Each driver in a driver list can optionally include a version constraint which dbc will respect when you run dbc sync. You can add a driver to the list with the same syntax as you used for dbc install, see Installing Drivers.
$ dbc add "mysql=0.1.0"
added mysql to driver list with constraint =0.1.0
use `dbc sync` to install the drivers in the list
$ cat dbc.toml
[drivers]
[drivers.mysql]
version = '=0.1.0'
Removing Drivers
Drivers can be removed from a driver list with the dbc remove command:
Using a Custom Filename
By default, dbc assumes a driver list has the filename dbc.toml. However, you can override this if you prefer another name or want to maintain multiple driver lists in one project (e.g., separate development and production lists).
All of the commands shown earlier on this page allow you to override the filename, for example: