diff --git a/.gitignore b/.gitignore index 9f6ddb38..f45a283c 100644 --- a/.gitignore +++ b/.gitignore @@ -47,3 +47,5 @@ cdn-dev .venv .claude + +__pycache__ diff --git a/docs/concepts/driver_registry.md b/docs/concepts/driver_registry.md index 621b1954..df744bb4 100644 --- a/docs/concepts/driver_registry.md +++ b/docs/concepts/driver_registry.md @@ -16,6 +16,8 @@ limitations under the License. # Driver Registry -dbc installs drivers from a "driver registry" which is an internet-accessible index of installable [ADBC driver](./driver.md) packages. Currently, dbc supports a single driver registry which is located at [https://dbc-cdn.columnar.tech](https://dbc-cdn.columnar.tech) and is managed by [Columnar](https://columnar.tech). +dbc installs drivers from a "driver registry" which is an internet-accessible index of installable [ADBC driver](./driver.md) packages. -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 in the driver registry by downloading `index.yaml` from [https://dbc-cdn.columnar.tech](https://dbc-cdn.columnar.tech/index.yaml) or using a cached copy. +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. diff --git a/docs/guides/finding_drivers.md b/docs/guides/finding_drivers.md index be8e52c5..e7ab8a68 100644 --- a/docs/guides/finding_drivers.md +++ b/docs/guides/finding_drivers.md @@ -49,6 +49,18 @@ $ dbc search sql • sqlite - An ADBC driver for SQLite developed under the Apache Software Foundation ``` +## Private Drivers + +If you are [logged in](./private_drivers.md) to a private registry, you will see some drivers marked with a `[private]` label: + +```console +$ dbc search +... +oracle [private] An ADBC driver for Oracle Database developed by Columnar +``` + +These drivers can be [installed](./installing.md) and added to [driver lists](../concepts/driver_list.md) just like regular drivers. + ## Options ### Verbose diff --git a/docs/guides/private_drivers.md b/docs/guides/private_drivers.md new file mode 100644 index 00000000..9e27f7c2 --- /dev/null +++ b/docs/guides/private_drivers.md @@ -0,0 +1,107 @@ + + +# Private Drivers + +{{ since_version('v0.2.0') }} + +Most drivers available with dbc are hosted on Columnar's public [driver registry](../concepts/driver_registry.md). However, some of the drivers you see when you run `dbc search` may be marked with a `[private]` label. + +To install and use these drivers, you must: + +1. Log in to [Columnar Cloud](https://cloud.columnar.tech) with dbc +2. Start a trial license + +Continue reading to learn how to log in and start a trial. + +## Logging In + +To log into Columnar's private driver registry, run `dbc auth login`. This will automatically create an account for you the first time you log in. + +You will see the following in your terminal and your default web browser will be opened: + +```console +$ dbc auth login +Opening https://auth.columnar.tech/activate?user_code=XXXX-XXXX in your default web browser... +⠏ Waiting for confirmation... +``` + +In your browser, you will see a **Device Confirmation** prompt and, once you click **Confirm**, you will be redirected to log in with the provider of your choice. Once you log in, you will be redirected to [Columnar Cloud](https://cloud.columnar.tech/). Keep the tab open and continue on to the next step. + +## Starting a Trial + +To install and use a private driver, you must start a trial and obtain a license. This is a separate step from logging in. + +Licenses can be obtained from your [Account](https://cloud.columnar.tech/account) page on Columnar Cloud by clicking **Start Free 14-Day Trial**. Follow any instructions in the dialog that opens up and click **Accept** to create your license. + +### Downloading Your License + +dbc will automatically download your license if you: + +1. Have an active license +2. Run `dbc install` with a private driver + +If you'd prefer to download the license manually, you can click **Download License File** and place the downloaded file in the appropriate location for your operating system: + +- Windows: `%LocalAppData%/dbc/credentials` +- macOS: `~/Library/Application Support/Columnar/dbc/credentials` +- Linux: `~/.local/share/dbc/credentials` + +You may also use a custom location by setting the environment variable `XDG_DATA_HOME` to an absolute path of your choosing. If you do this, you must ensure you set the same value of `XDG_DATA_HOME` when loading drivers with the [driver manager](../concepts/driver_manager.md) for the drivers to find your license. + +## Logging Out + +To log out, run `dbc auth logout`. + +By default, the `logout` command doesn't purge any driver licenses from your system and only removes your login credentials. If you wish remove the local copy of your license run: + +```console +$ dbc auth logout --purge +``` + +!!! note + + Note that this command only removes the local copy of your license and does not cancel any active licenses you may have in your [Columnar Cloud](https://cloud.columnar.tech) account. + +!!! warning + + ADBC drivers that require a license (i.e., private drivers) will stop working after you run this command. You can re-download your license with `dbc auth login`. See [Downloading Your License](#downloading-your-license). + + +## API Keys + +dbc also supports logging in to private driver registries via API key. This is primarily intended for use in [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) systems or any system where logging in with a web browser is not possible. + +To create an API key, open a web browser to your [API keys](https://cloud.columnar.tech/apikeys) page. + +!!! note inline end + + If you've already created an API key, you will see a **Create API Key** button instead. + +If you haven't created any API keys before, you will see a **Create Your First API Key** button. After clicking it, enter a name, optionally choose an expiration, and click **Create**. On the following screen, you will see your new API key and instructions to copy it to your clipboard. + +!!! note + + API keys grant full access to your account so be sure to store it in a secure way. + + +Then to use your API key to log in, run: + +```console +$ dbc auth login --api-key "" +``` + +Once you've run this successfully, dbc is now logged in and you can install private drivers as you would normally. diff --git a/docs/macros.py b/docs/macros.py new file mode 100644 index 00000000..6296ecd7 --- /dev/null +++ b/docs/macros.py @@ -0,0 +1,28 @@ +# Copyright 2026 Columnar Technologies Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + + +def define_env(env): + @env.macro + def since_version(version): + """Create a "since v1.2.3" badge for annotation features with. + + Args: + version: git tag for version + """ + return ( + f'' + f'SINCE {version}' + f'' + ) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 4ac5f054..c99cd9cd 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -46,6 +46,7 @@ $ dbc [OPTIONS]
dbc sync

Install the drivers from the driver list

dbc info

Get information about a driver

dbc docs

Open driver documentation in a web browser

+
dbc auth

Manage driver registry credentials

## search @@ -301,3 +302,52 @@ $ dbc docs `--quiet`, `-q` : Suppress all output + +## auth + +{{ since_version('v0.2.0') }} + +

Usage

+ +```console +$ dbc auth login +$ dbc auth logout +``` + +

Subcommands

+ +### login + +

Arguments

+ +`REGISTRYURL` + +: Optional. URL of the driver registry to authenticate with. Defaults to [https://dbc-cdn-private.columnar.tech/](https://dbc-cdn-private.columnar.tech/). + +

Options

+ +`--clientid CLIENTID` + +: OAuth Client ID (can also be set via `DBC_OAUTH_CLIENT_ID`) + +`--api-key API-KEY` + +: Authenticate using an API key instead of OAuth (use '-' to read from stdin) + +### logout + +

Arguments

+ +`REGISTRYURL` + +: Optional. URL of the driver registry to log out from. Defaults to [https://dbc-cdn-private.columnar.tech/](https://dbc-cdn-private.columnar.tech/). + +

Options

+ +`--purge` + +: Remove all local auth credentials for dbc + + !!! warning + + ADBC drivers that require a license (i.e., private drivers) will stop working after you run this command. You can re-download your license with `dbc auth login`. See [Downloading Your License](../guides/private_drivers.md#downloading-your-license). diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 8b8f5244..323d84cb 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -2,6 +2,35 @@ --md-default-bg-color: rgb(33, 33, 33); --md-code-bg-color: rgb(45, 45, 45); } + +/* since_version badge styling. see macros.py */ +.version-badge { + background: var(--md-accent-fg-color); + color: var(--md-accent-bg-color); + padding: 2px 6px; + border-radius: 3px; + font-size: 0.75em; + font-weight: bold; + display: inline-block; +} + +.version-badge a { + color: inherit; + text-decoration: none; +} + +.version-badge a:hover { + color: inherit; + text-decoration: underline; +} + +/* Disable highlighting for shell built-ins. This means words in console blocks +like echo, export, logout, and source will use the same color as other commands +and won't show up highlighted as purple. */ +.highlight .nb { + color: inherit; +} + /* Hide the site name in the header... */ .md-header__title .md-header__topic:first-of-type { display: none !important; diff --git a/mkdocs.yml b/mkdocs.yml index 14c22367..3689ae66 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,6 +46,7 @@ nav: - Using a Driver List: guides/driver_list.md - Driver Managers: guides/driver_manager.md - Python Notebooks: guides/python_notebooks.md + - Private Drivers: guides/private_drivers.md - Concepts: - concepts/index.md - Driver: concepts/driver.md @@ -119,6 +120,8 @@ exclude_docs: | extra_javascript: - scripts/extra.js plugins: + - macros: + module_name: docs/macros - privacy - search - social: diff --git a/pixi.lock b/pixi.lock index fceecac4..8a988778 100644 --- a/pixi.lock +++ b/pixi.lock @@ -182,6 +182,7 @@ environments: - pypi: https://files.pythonhosted.org/packages/0f/e7/aa315e6a749d9b96c2504a1ba0ba031ba2d0517e972ce22682e3fccecb09/cssselect2-0.8.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/07/6c/aa3f2f849e01cb6a001cd8554a88d4c77c5c1a31c95bdf1cf9301e6d9ef4/defusedxml-0.7.1-py2.py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/f7/ec/67fbef5d497f86283db54c22eec6f6140243aae73265799baaaa19cd17fb/ghp_import-2.1.0-py3-none-any.whl + - pypi: https://files.pythonhosted.org/packages/1f/7f/13cd798d180af4bf4c0ceddeefba2b864a63c71645abc0308b768d67bb81/hjson-3.1.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/62/a1/3d680cbfd5f4b8f15abc1d571870c5fc3e594bb582bc3b64ea099db13e56/jinja2-3.1.6-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/70/81/54e3ce63502cd085a0c556652a4e1b919c45a446bd1e5300e10c44c8c521/markdown-3.10-py3-none-any.whl @@ -195,6 +196,7 @@ environments: - pypi: https://files.pythonhosted.org/packages/22/5b/dbc6a8cddc9cfa9c4971d59fb12bb8d42e161b7e7f8cc89e49137c5b279c/mkdocs-1.6.1-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/9f/d4/029f984e8d3f3b6b726bd33cafc473b75e9e44c0f7e80a5b29abc466bdea/mkdocs_get_deps-0.2.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/ad/2b/82928cc9e8d9269cd79e7ebf015efdc4945e6c646e86ec1d4dba1707f215/mkdocs_llmstxt-0.5.0-py3-none-any.whl + - pypi: https://files.pythonhosted.org/packages/51/62/9fffba5bb9ed3d31a932ad35038ba9483d59850256ee0fea7f1187173983/mkdocs_macros_plugin-1.5.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/04/87/eefe8d5e764f4cf50ed91b943f8e8f96b5efd65489d8303b7a36e2e79834/mkdocs_material-9.7.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/5b/54/662a4743aa81d9582ee9339d4ffa3c8fd40a4965e033d77b9da9774d3960/mkdocs_material_extensions-1.3.1-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/20/12/38679034af332785aac8774540895e234f4d07f7545804097de4b666afd8/packaging-25.0-py3-none-any.whl @@ -211,6 +213,8 @@ environments: - pypi: https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/46/2c/1462b1d0a634697ae9e55b3cecdcb64788e8b7d63f54d923fcd0bb140aed/soupsieve-2.8.3-py3-none-any.whl + - pypi: https://files.pythonhosted.org/packages/17/43/47c7cf84b3bd74a8631b02d47db356656bb8dff6f2e61a4c749963814d0d/super_collections-0.6.2-py3-none-any.whl + - pypi: https://files.pythonhosted.org/packages/33/d1/8bb87d21e9aeb323cc03034f5eaf2c8f69841e40e4853c2627edf8111ed3/termcolor-3.3.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/e6/34/ebdc18bae6aa14fbee1a08b63c015c72b64868ff7dae68808ab500c492e2/tinycss2-1.4.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/a7/c2/fe1e52489ae3122415c51f387e221dd0773709bad6c6cdaa599e8a2c5185/urllib3-2.5.0-py3-none-any.whl @@ -266,6 +270,7 @@ environments: - pypi: https://files.pythonhosted.org/packages/0f/e7/aa315e6a749d9b96c2504a1ba0ba031ba2d0517e972ce22682e3fccecb09/cssselect2-0.8.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/07/6c/aa3f2f849e01cb6a001cd8554a88d4c77c5c1a31c95bdf1cf9301e6d9ef4/defusedxml-0.7.1-py2.py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/f7/ec/67fbef5d497f86283db54c22eec6f6140243aae73265799baaaa19cd17fb/ghp_import-2.1.0-py3-none-any.whl + - pypi: https://files.pythonhosted.org/packages/1f/7f/13cd798d180af4bf4c0ceddeefba2b864a63c71645abc0308b768d67bb81/hjson-3.1.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/62/a1/3d680cbfd5f4b8f15abc1d571870c5fc3e594bb582bc3b64ea099db13e56/jinja2-3.1.6-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/70/81/54e3ce63502cd085a0c556652a4e1b919c45a446bd1e5300e10c44c8c521/markdown-3.10-py3-none-any.whl @@ -279,6 +284,7 @@ environments: - pypi: https://files.pythonhosted.org/packages/22/5b/dbc6a8cddc9cfa9c4971d59fb12bb8d42e161b7e7f8cc89e49137c5b279c/mkdocs-1.6.1-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/9f/d4/029f984e8d3f3b6b726bd33cafc473b75e9e44c0f7e80a5b29abc466bdea/mkdocs_get_deps-0.2.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/ad/2b/82928cc9e8d9269cd79e7ebf015efdc4945e6c646e86ec1d4dba1707f215/mkdocs_llmstxt-0.5.0-py3-none-any.whl + - pypi: https://files.pythonhosted.org/packages/51/62/9fffba5bb9ed3d31a932ad35038ba9483d59850256ee0fea7f1187173983/mkdocs_macros_plugin-1.5.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/04/87/eefe8d5e764f4cf50ed91b943f8e8f96b5efd65489d8303b7a36e2e79834/mkdocs_material-9.7.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/5b/54/662a4743aa81d9582ee9339d4ffa3c8fd40a4965e033d77b9da9774d3960/mkdocs_material_extensions-1.3.1-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/20/12/38679034af332785aac8774540895e234f4d07f7545804097de4b666afd8/packaging-25.0-py3-none-any.whl @@ -295,6 +301,8 @@ environments: - pypi: https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/46/2c/1462b1d0a634697ae9e55b3cecdcb64788e8b7d63f54d923fcd0bb140aed/soupsieve-2.8.3-py3-none-any.whl + - pypi: https://files.pythonhosted.org/packages/17/43/47c7cf84b3bd74a8631b02d47db356656bb8dff6f2e61a4c749963814d0d/super_collections-0.6.2-py3-none-any.whl + - pypi: https://files.pythonhosted.org/packages/33/d1/8bb87d21e9aeb323cc03034f5eaf2c8f69841e40e4853c2627edf8111ed3/termcolor-3.3.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/e6/34/ebdc18bae6aa14fbee1a08b63c015c72b64868ff7dae68808ab500c492e2/tinycss2-1.4.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/a7/c2/fe1e52489ae3122415c51f387e221dd0773709bad6c6cdaa599e8a2c5185/urllib3-2.5.0-py3-none-any.whl @@ -645,6 +653,10 @@ packages: - markdown ; extra == 'dev' - flake8 ; extra == 'dev' - wheel ; extra == 'dev' +- pypi: https://files.pythonhosted.org/packages/1f/7f/13cd798d180af4bf4c0ceddeefba2b864a63c71645abc0308b768d67bb81/hjson-3.1.0-py3-none-any.whl + name: hjson + version: 3.1.0 + sha256: 65713cdcf13214fb554eb8b4ef803419733f4f5e551047c9b711098ab7186b89 - conda: https://conda.anaconda.org/conda-forge/linux-64/icu-75.1-he02047a_0.conda sha256: 71e750d509f5fa3421087ba88ef9a7b9be11c53174af3aa4d06aff4c18b38e8e md5: 8b189310083baabfb622af68fd9d3ae3 @@ -1203,6 +1215,29 @@ packages: - mdformat>=0.7.21 - mdformat-tables>=1.0 requires_python: '>=3.10' +- pypi: https://files.pythonhosted.org/packages/51/62/9fffba5bb9ed3d31a932ad35038ba9483d59850256ee0fea7f1187173983/mkdocs_macros_plugin-1.5.0-py3-none-any.whl + name: mkdocs-macros-plugin + version: 1.5.0 + sha256: c10fabd812bf50f9170609d0ed518e54f1f0e12c334ac29141723a83c881dd6f + requires_dist: + - hjson + - jinja2 + - mkdocs>=0.17 + - packaging + - pathspec + - python-dateutil + - pyyaml + - requests + - super-collections>=0.6.2 + - termcolor + - pytest ; extra == 'test' + - mkdocs-include-markdown-plugin ; extra == 'test' + - mkdocs-macros-test ; extra == 'test' + - mkdocs-material>=6.2 ; extra == 'test' + - mkdocs-test>=0.6.0 ; extra == 'test' + - mkdocs-d2-plugin ; extra == 'test' + - mkdocs-mermaid2-plugin ; extra == 'doc' + requires_python: '>=3.8' - pypi: https://files.pythonhosted.org/packages/04/87/eefe8d5e764f4cf50ed91b943f8e8f96b5efd65489d8303b7a36e2e79834/mkdocs_material-9.7.0-py3-none-any.whl name: mkdocs-material version: 9.7.0 @@ -1674,6 +1709,24 @@ packages: version: 2.8.3 sha256: ed64f2ba4eebeab06cc4962affce381647455978ffc1e36bb79a545b91f45a95 requires_python: '>=3.9' +- pypi: https://files.pythonhosted.org/packages/17/43/47c7cf84b3bd74a8631b02d47db356656bb8dff6f2e61a4c749963814d0d/super_collections-0.6.2-py3-none-any.whl + name: super-collections + version: 0.6.2 + sha256: 291b74d26299e9051d69ad9d89e61b07b6646f86a57a2f5ab3063d206eee9c56 + requires_dist: + - hjson + - pytest>=7.0 ; extra == 'test' + - rich ; extra == 'test' + - pyyaml ; extra == 'test' + requires_python: '>=3.8' +- pypi: https://files.pythonhosted.org/packages/33/d1/8bb87d21e9aeb323cc03034f5eaf2c8f69841e40e4853c2627edf8111ed3/termcolor-3.3.0-py3-none-any.whl + name: termcolor + version: 3.3.0 + sha256: cf642efadaf0a8ebbbf4bc7a31cec2f9b5f21a9f726f4ccbb08192c9c26f43a5 + requires_dist: + - pytest ; extra == 'tests' + - pytest-cov ; extra == 'tests' + requires_python: '>=3.10' - pypi: https://files.pythonhosted.org/packages/e6/34/ebdc18bae6aa14fbee1a08b63c015c72b64868ff7dae68808ab500c492e2/tinycss2-1.4.0-py3-none-any.whl name: tinycss2 version: 1.4.0 diff --git a/pixi.toml b/pixi.toml index 6fa35ba1..59aab115 100644 --- a/pixi.toml +++ b/pixi.toml @@ -35,8 +35,9 @@ cdn-generate = "python scripts/cdn.py" cdn-serve = "python -m http.server -d cdn-dev" [feature.docs.pypi-dependencies] -mkdocs-material = { version = "*", extras = ["imaging"] } mkdocs-llmstxt = "*" +mkdocs-material = { version = "*", extras = ["imaging"] } +mkdocs-macros-plugin = "*" [feature.docs.dependencies] cairo = ">=1.18.4,<2"