Skip to content

docs: simplify readme #353

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
amoeba merged 1 commit into from
Apr 14, 2026
+37 −144
Merged

docs: simplify readme #353

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 37 additions & 144 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,205 +20,98 @@ limitations under the License.
[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/columnar-tech/dbc)](https://github.com/columnar-tech/dbc/releases)
[![Release dbc](https://github.com/columnar-tech/dbc/actions/workflows/release.yml/badge.svg)](https://github.com/columnar-tech/dbc/actions/workflows/release.yml)

## Overview

**dbc is the command-line tool for installing and managing [ADBC](https://arrow.apache.org/adbc) drivers.**

dbc can:

* Install pre-built [ADBC](https://arrow.apache.org/adbc) drivers with a single command
* Install drivers in your user account, on the system, or in virtual environments
* Manage isolated, reproducible project environments with driver lists and lockfiles
* Run on macOS, Linux, and Windows
* Be installed in many ways (with pip, standalone installers, Docker images, and more)
* Work in CI/CD environments

## Installation

There are multiple ways to install dbc:
## Install dbc

### From PyPI
### Shell (Linux/macOS)

For simple installation, we recommend the popular [pipx](https://pipx.pypa.io/stable/installation) tool which will automatically put it on your `PATH`:

```sh
pipx install dbc
```

You can also just test it out instead of installing it:

```sh
pipx run dbc
curl -LsSf https://dbc.columnar.tech/install.sh | sh
```

You can also use a virtual environment:
### Homebrew

```sh
python -m venv .venv
source .venv/bin/activate
pip install dbc
```

### Standalone Installer

#### macOS or Linux

You can download the install script and execute it:

```sh
curl -LsSf https://dbc.columnar.tech/install.sh | sh
brew install columnar-tech/tap/dbc
```

If your system doesn't have `curl` you can also use `wget`:
### uv

```sh
wget -q0- https://dbc.columnar.tech/install.sh | sh
```

If you want to inspect the script before use, you can simply run:

```sh
curl -LsSf https://dbc.columnar.tech/install.sh | less
uv tool install dbc
```

#### Windows
### pipx

Download the Windows graphical installer for your architecture:

| Architecture | Installer |
| ------------ | ------------------------------------------------------- |
| x64 (64-bit) | <https://dbc.columnar.tech/latest/dbc-latest-x64.msi> |

Or use `irm` to download the install script and execute it with `iex`:

```sh
powershell -ExecutionPolicy ByPass -c "irm https://dbc.columnar.tech/install.ps1 | iex
```

Changing the [execution policy](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4#powershell-execution-policies) allows running a script from the internet.

Of course, you can also inspect the script before use:

```sh
powershell -c "irm https://dbc.columnar.tech/install.ps1 | more"
pipx install dbc
```

### GitHub Releases

Release artifacts for dbc can also be downloaded directly from [GitHub Releases](https://github.com/columnar-tech/dbc/releases). Included in the artifacts are also
cryptographic signatures and a checksum file to ensure nothing has been tampered with.

Each release includes the following assets allowing you to install using your preferred method:
### PowerShell (Windows)

- `.tar.gz` or `.zip` archives containing the appropriate binary for all supported platforms and architectures
- `.deb` and `.rpm` installation packages
- An `msi` installer package for Windows
- `.snap` packages
- Python wheel packages that bundle the dbc executable binary

### Docker

Docker images are also provided with standalone binaries that can be easily run using:

```sh
docker run --rm -it columnar/dbc:latest --help
```

#### Available Images

The following distroless images are available for linux-based `amd64` and `arm64`
architectures:

- `columnar/dbc:latest`
- `columnar/dbc:{major}.{minor}.{patch}`, e.g. `columnar/dbc:0.0.1`

## Homebrew

You can install dbc from our Homebrew tap by running:

```console
$ brew install columnar-tech/tap/dbc
powershell -ExecutionPolicy ByPass -c irm https://dbc.columnar.tech/install.ps1 | iex
```

This will automatically configure our tap and install dbc from it. If you'd rather do this as two separate commands, you can run:
### WinGet

```console
$ brew tap columnar-tech/tap
$ brew install dbc
```
winget install dbc
```

### Windows MSI

## Getting Started
[Download the MSI installer](https://dbc.columnar.tech/latest/dbc-latest-x64.msi)

Once you have dbc available to you on the command line, you can install an ADBC
driver and make it available to your user. For example, to install the snowflake driver:
For more installation options, see the [installation docs](docs/getting_started/installation.md).

```sh
dbc install snowflake
```
## Getting Started

Alternately, when working on a project you can create a `dbc.toml` file to create a
list of drivers to install to create a reproducible environment:
Search for available drivers:

```sh
cd <path/to/project>
dbc init # creates dbc.toml
dbc add snowflake # adds this to the driver list
dbc sync # install drivers and create dbc.lock
dbc search
```

Using `dbc add` also allows version constraints:
Install a driver:

```sh
dbc add "snowflake>=1.0.0"
dbc sync # looks for and installs a version >=1.0.0
dbc install snowflake
```

### Using the Driver

The simplest way to use the driver is via Python with [`adbc-driver-manager`](https://pypi.org/project/adbc-driver-manager/).
*Note: version 1.8.0 added support for driver manifests, so you'll need that version of the driver manager or higher*.
Use it with Python:

```sh
dbc install snowflake
pip install "adbc-driver-manager>=1.8.0"
```

Using the driver is easy:

```python
import adbc_driver_manager.dbapi as adbc

snowflake_connect_args = {
"username": "USER",
"password": "PASS",
"adbc.snowflake.sql.account": "ACCOUNT-IDENT",
"adbc.snowflake.sql.db": "SNOWFLAKE_SAMPLE_DATA",
# other connect options
}

with adbc.connect(
driver="snowflake",
db_kwargs=snowflake_connect_args,
db_kwargs={
"username": "USER",
"password": "PASS",
"adbc.snowflake.sql.account": "ACCOUNT-IDENT",
# ... other connection options
},
) as con, con.cursor() as cursor:
cursor.execute("SELECT * FROM CUSTOMER LIMIT 5")
table = cursor.fetch_arrow_table()

print(table)
print(cursor.fetch_arrow_table())
```

For more detailed information on using dbc, see the [documentation](https://docs.columnar.tech/dbc). Also check out the [ADBC Quickstarts](https://github.com/columnar-tech/adbc-quickstarts) repo to learn how to use ADBC with a variety of languages and databases.
You can also manage drivers in a project using a [driver list](docs/guides/driver_list.md). And you can store connection options in a [connection profile](https://arrow.apache.org/adbc/current/format/connection_profiles.html) instead of in your code.

## Communications

For general questions and discussion, use the GitHub [discussions](https://github.com/columnar-tech/dbc/discussions).
For more details, see the [dbc documentation](https://docs.columnar.tech/dbc) and the [ADBC Quickstarts](https://github.com/columnar-tech/adbc-quickstarts).

To report an issue, request a feature, or contribute an improvement, use the GitHub
[issues](https://github.com/columnar-tech/dbc/issues) and
[PRs](https://github.com/columnar-tech/dbc/pulls).
## Communications

See [CONTRIBUTING.md](./CONTRIBUTING.md) for more information on contributing.
- [Discussions](https://github.com/columnar-tech/dbc/discussions) for questions
- [Issues](https://github.com/columnar-tech/dbc/issues) to report bugs or request features
- See [CONTRIBUTING.md](./CONTRIBUTING.md) for contributing

## Code of Conduct

By choosing to contribute to dbc, you agree to follow our [Code of Conduct](https://github.com/columnar-tech/.github/blob/main/CODE_OF_CONDUCT.md).
By contributing to dbc, you agree to follow our [Code of Conduct](https://github.com/columnar-tech/.github/blob/main/CODE_OF_CONDUCT.md).
Loading