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 registry 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'
Pre-release Versions
Allowing Pre-release Versions
By default, when you add a driver to a driver list, dbc will only consider stable (non-pre-release) versions. If you want to allow pre-release versions when running dbc sync, use the --pre flag with dbc add:
$ dbc add --pre mysql
added mysql to driver list
use `dbc sync` to install the drivers in the list
$ cat dbc.toml
[drivers]
[drivers.mysql]
prerelease = 'allow'
The prerelease = 'allow' field tells dbc sync to consider pre-release versions when resolving which version to install.
Note
The prerelease = 'allow' field only affects implicit version resolution. When your version constraint unambiguously references a pre-release (by including a pre-release suffix like -beta.1), that constraint will match pre-release versions regardless of the prerelease field.
Adding Specific Pre-release Versions
You can add a driver with a version constraint that references a specific pre-release version without using the --pre flag. When your version constraint unambiguously references a pre-release by including a pre-release suffix, the prerelease field is not added:
$ dbc add "mysql=1.0.0-beta.1"
added mysql to driver list with constraint =1.0.0-beta.1
use `dbc sync` to install the drivers in the list
$ cat dbc.toml
[drivers]
[drivers.mysql]
version = '=1.0.0-beta.1'
The version constraint =1.0.0-beta.1 unambiguously indicates you want a pre-release, so prerelease = 'allow' is not needed.
However, if your version constraint is ambiguous and only a pre-release version satisfies it, dbc sync will fail rather than install the pre-release. For example, if a driver has versions 0.1.0 and 0.1.1-beta.1:
To allow 0.1.1-beta.1 to be installed in this case, you must either:
- Use
dbc add --preto addprerelease = 'allow' - Change the constraint to reference the pre-release:
version = '>=0.1.1-beta.1'
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: