From 294ba522e47bcd1036b8509f55c3ccd13f7f5b8a Mon Sep 17 00:00:00 2001 From: Matt Topol Date: Fri, 12 Jun 2026 14:24:28 -0400 Subject: [PATCH] docs(registry): document configurable driver registries Document the configurable driver registry feature: the global config.toml and project dbc.toml [[registries]] syntax, priority ordering across project/global/built-in registries, and the replace_defaults behavior. Split out of #360 so the docs can be reviewed and merged separately. --- docs/concepts/driver_registry.md | 55 ++++++++++++++++++++++++++++++++ docs/reference/driver_list.md | 36 +++++++++++++++++++++ 2 files changed, 91 insertions(+) diff --git a/docs/concepts/driver_registry.md b/docs/concepts/driver_registry.md index df744bb4..281efd7b 100644 --- a/docs/concepts/driver_registry.md +++ b/docs/concepts/driver_registry.md @@ -21,3 +21,58 @@ dbc installs drivers from a "driver registry" which is an internet-accessible in By default, dbc is configured to communicate with Columnar's public and private driver registries. Most drivers will be from the public registry but some will be marked with a `[private]` label which means they're from the private registry. See [Private Drivers](../guides/private_drivers.md) for information on how to install and use private drivers. When you run a command like [`dbc search`](../reference/cli.md#search) or [`dbc install`](../reference/cli.md#install), dbc gets information about the drivers that are available from each configured registry by downloading its `index.yaml` or using a cached copy. + +## Configuring registries + +{{ since_version('v0.4.0') }} + +Alongside the built-in default registries, you can configure dbc to use additional driver registries at two levels: + +- **Global**: a `config.toml` in your user config directory applies to every dbc command. +- **Project**: a `[[registries]]` section in a project's [`dbc.toml`](../reference/driver_list.md#registries) applies to dbc commands run in that project. + +The global `config.toml` lives in your user config directory: + +- Linux: `~/.config/columnar/dbc/config.toml` +- macOS: `~/Library/Application Support/Columnar/dbc/config.toml` +- Windows: `%AppData%\Columnar\dbc\config.toml` + +Both files use the same `[[registries]]` syntax. Each entry requires a `url` (which must be an `http` or `https` URL) and may include an optional `name` that is shown as a `[name]` tag in `dbc search` output: + +```toml +[[registries]] +url = "https://my-registry.example.com" +name = "my-registry" +``` + +### Priority and conflicts + +When the same driver is published by more than one registry, dbc resolves the conflict by registry priority, highest first: + +1. Project registries (`dbc.toml`) +2. Global registries (`config.toml`) +3. Built-in default registries + +Registries are deduplicated by URL and, when a driver appears in more than one registry, the highest-priority registry wins. + +### Replacing the default registries + +Set `replace_defaults = true` to drop the built-in default registries and use only the registries you configure: + +```toml +replace_defaults = true + +[[registries]] +url = "https://my-registry.example.com" +name = "my-registry" +``` + +In a global `config.toml`, `replace_defaults` is either `true` or `false` (the default). In a project `dbc.toml` it has a third state — omitting it inherits the global config's value, `true` drops the built-in defaults, and `false` forces the built-in defaults back on even when the global config set `replace_defaults = true`. + +### Which commands use which registries + +- Global `config.toml` registries are used by **every** dbc command. +- Project `dbc.toml` registries are used by the commands that manage or discover drivers for the current project — [`dbc add`](../reference/cli.md#add), [`dbc sync`](../reference/cli.md#sync), [`dbc search`](../reference/cli.md#search), [`dbc info`](../reference/cli.md#info), and [`dbc docs`](../reference/cli.md#docs) — which read `dbc.toml` from the current directory. +- [`dbc install`](../reference/cli.md#install) installs into a user- or system-level [config level](../reference/config_level.md) rather than the project, so it uses only the global and built-in default registries and does not read a project `dbc.toml`. + +Setting the `DBC_BASE_URL` environment variable overrides all registry configuration and points dbc at a single registry. diff --git a/docs/reference/driver_list.md b/docs/reference/driver_list.md index ec26abb1..5b4cc6aa 100644 --- a/docs/reference/driver_list.md +++ b/docs/reference/driver_list.md @@ -87,3 +87,39 @@ To allow the pre-release in this case, either: - Add `prerelease = 'allow'` - Change the constraint to reference the pre-release: `version = '>=0.1.1-beta.1'` + +## Registries + +{{ since_version('v0.4.0') }} + +A driver list may declare additional [driver registries](../concepts/driver_registry.md#configuring-registries) to resolve drivers from, using one or more `[[registries]]` entries and an optional top-level `replace_defaults` key. These registries are used by `dbc add`, `dbc sync`, `dbc search`, `dbc info`, and `dbc docs` when run against this driver list. + +```toml +replace_defaults = false + +[[registries]] +url = "https://my-registry.example.com" +name = "my-registry" + +[drivers] +[drivers.my-driver] +version = '>=1.0.0' +``` + +### `url` + +Required. The base URL of the registry. Must be an `http` or `https` URL with a host. + +### `name` + +Optional. A short label for the registry, shown as a `[name]` tag in `dbc search` output to indicate which registry a driver came from. + +### `replace_defaults` + +Optional. Controls whether dbc's built-in default registries are used in addition to the ones you configure. + +- Omitted: inherit the value from the global `config.toml`. +- `true`: use only the configured project and global registries; drop the built-in defaults. +- `false`: always include the built-in defaults, even if the global `config.toml` set `replace_defaults = true`. + +See [Configuring registries](../concepts/driver_registry.md#configuring-registries) for the full priority order across project, global, and built-in registries.