docs: document the --pre option (#297)

Adds documentation for the `--pre` option that was added to multiple
subcommands.

---------

Co-authored-by: Ian Cook <ianmcook@gmail.com>

Author: zeroshade

docs/guides/driver_list.md

@@ -112,6 +112,58 @@ $ cat dbc.toml
 version = '=0.1.0'
 ```
 
+## Pre-release Versions
+
+{{ since_version('v0.2.0') }}
+
+### 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`:
+
+```console
+$ 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:
+
+```console
+$ 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`:
+
+```toml
+[drivers.mysql]
+version = '>0.1.0'
+# dbc sync will FAIL, not install 0.1.1-beta.1
+```
+
+To allow `0.1.1-beta.1` to be installed in this case, you must either:
+
+- Use `dbc add --pre` to add `prerelease = '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:

docs/guides/finding_drivers.md

@@ -172,3 +172,42 @@ $ dbc search --verbose
    Available Versions:
     ╰── 0.1.1
 ```
+
+### Pre-release Versions
+
+{{ since_version('v0.2.0') }}
+
+By default, `dbc search` hides pre-release versions from search results. 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 include pre-release versions in search results, use the `--pre` flag:
+
+```console
+$ dbc search --pre
+```
+
+Without `--pre`, `dbc search` will:
+
+- Hide drivers that have exclusively pre-release versions (no stable versions)
+- Exclude pre-release versions from the available versions list
+
+With `--pre`, `dbc search` will:
+
+- Show drivers even if they have exclusively pre-release versions
+- Include pre-release versions in the available versions list when using `--verbose`
+
+For example, with `--pre --verbose`:
+
+```console
+$ dbc search --pre --verbose mysql
+• mysql
+   Title: ADBC Driver Foundry Driver for MySQL
+   Description: An ADBC Driver for MySQL developed by the ADBC Driver Foundry
+   License: Apache-2.0
+   Available Versions:
+    ├── 0.1.0
+    ├── 0.2.0-beta.1
+    ╰── 0.2.0
+```
+
+!!! note
+    Using the `--pre` flag with `dbc search` only affects the visibility of pre-release versions in search results. To actually install a pre-release version, you need to either use `--pre` with `dbc install` or use a version constraint that unambiguously references a pre-release (by including a pre-release suffix like `-beta.1`).

docs/guides/installing.md

@@ -74,6 +74,46 @@ The syntax for specifying a version may be familiar to you if you've used other
 !!! note
     dbc uses the [github.com/Masterminds/semver/v3](https://pkg.go.dev/github.com/Masterminds/semver/v3#section-readme) 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_version('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:
+
+```console
+$ 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:
+
+```console
+$ 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`:
+
+```console
+$ 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.

docs/reference/cli.md

@@ -71,6 +71,10 @@ $ dbc search [PATTERN]
 
 :   Print output as JSON instead of plaintext
 
+`--pre` {{ since_version('v0.2.0') }}
+
+:   Include pre-release drivers and versions (hidden by default)
+
 `--verbose`, `-v`
 
 :   Enable verbose output
@@ -111,6 +115,10 @@ $ dbc install [OPTIONS] <DRIVER>
 
 :   Allow installation of drivers without a signature file
 
+`--pre` {{ since_version('v0.2.0') }}
+
+:   Allow implicit installation of pre-release versions
+
 `--quiet`, `-q`
 
 :   Suppress all output
@@ -189,6 +197,10 @@ $ dbc add <DRIVER>
 
 :   Driver list to add to [default: ./dbc.toml]
 
+`--pre` {{ since_version('v0.2.0') }}
+
+:   Allow pre-release versions implicitly
+
 `--quiet`, `-q`
 
 :   Suppress all output

docs/reference/driver_list.md

@@ -19,15 +19,16 @@ limitations under the License.
 `dbc.toml` is the default filename dbc uses for a [driver list](../concepts/driver_list.md). This page outlines the structure of that file.
 
 This file uses the [TOML](https://toml.io) file format and contains a single TOML Table called "drivers".
-Each driver must have a name and may optionally have a version constraint. See [Version Constraints](../guides/installing.md#version-constraints) to learn how to specify version constraints.
+Each driver must have a name and may optionally have a version constraint and pre-release setting. See [Version Constraints](../guides/installing.md#version-constraints) to learn how to specify version constraints.
 
 ## Example
 
 The following driver list specifies:
 
-- Whatever is the latest version of the "mysql" driver
+- Whatever is the latest stable version of the "mysql" driver
 - The exact 1.4.0 version of the "duckdb" driver
-- The latest version in the 1.x.x major series for the "postgresql" driver.
+- The latest stable version in the 1.x.x major series for the "postgresql" driver
+- The latest version (including pre-releases) of the "snowflake" driver
 
 ```toml
 [drivers]
@@ -39,4 +40,50 @@ version = '=1.4.0'
 
 [drivers.postgresql]
 version = '=1.x.x'
+
+[drivers.snowflake]
+prerelease = 'allow'
+```
+
+## Fields
+
+### `version`
+
+Optional. A version constraint string that specifies which versions of the driver are acceptable. If omitted, dbc will use the latest stable version available.
+
+See [Version Constraints](../guides/installing.md#version-constraints) for the full syntax.
+
+### `prerelease`
+
+{{ since_version('v0.2.0') }}
+
+Optional. Controls whether pre-release versions should be considered during version resolution.
+
+- When set to `'allow'`, dbc will consider pre-release versions when selecting which version to install
+- When omitted or set to any other value, only stable (non-pre-release) versions will be considered
+
+This field is typically set automatically when using `dbc add --pre`.
+
+**Example:**
+
+```toml
+[drivers.mysql]
+prerelease = 'allow'
+```
+
+**Interaction with version constraints:**
+
+The `prerelease` field only affects implicit version resolution. When your `version` constraint unambiguously references a pre-release by including a pre-release suffix (like `version = '>=1.0.0-beta.1'`), pre-release versions will be considered regardless of this field.
+
+However, if your version constraint is ambiguous and only pre-release versions satisfy it, `dbc sync` will fail unless `prerelease = 'allow'` is set. For example, if a driver has versions `0.1.0` and `0.1.1-beta.1`:
+
+```toml
+[drivers.mysql]
+version = '>0.1.0'
+# This will FAIL during sync, not install 0.1.1-beta.1
 ```
+
+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'`