diff --git a/README.md b/README.md index 2ba31cf9..e7e58c4e 100644 --- a/README.md +++ b/README.md @@ -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) | | - -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 -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).