Metadata-Version: 2.4
Name: benchbox
Version: 0.4.1
Summary: Embedded benchmark datasets and queries for database evaluation. Implements TPC-H, TPC-DS, TPC-DI and other industry-standard benchmarks.
Author-email: Joe Harris <joe@benchbox.dev>
License: MIT
Project-URL: Homepage, https://github.com/BenchBox-dev/benchbox
Project-URL: Bug Tracker, https://github.com/BenchBox-dev/benchbox/issues
Project-URL: Documentation, https://benchbox.readthedocs.io/
Project-URL: Repository, https://github.com/BenchBox-dev/benchbox.git
Project-URL: Changelog, https://github.com/BenchBox-dev/benchbox/blob/release/CHANGELOG.md
Keywords: benchmark,database,tpc-h,tpc-ds,tpc-di,analytics,olap,performance-testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Testing :: Acceptance
Classifier: Topic :: System :: Benchmark
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textcharts>=0.1.0
Requires-Dist: sqlglot<31.0.0,>=25.6.0
Requires-Dist: click<9.0.0,>=8.3.3
Requires-Dist: rich>=13.0.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: packaging>=24.0
Requires-Dist: pyarrow<25.0.0,>=21.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: zstandard>=0.20.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: duckdb<2.0.0,>=1.5.0; extra == "dev"
Requires-Dist: tox>=4.13.0; extra == "dev"
Requires-Dist: pyspark>=3.5.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.2.0; extra == "docs"
Requires-Dist: roman-numerals<4.0; extra == "docs"
Requires-Dist: furo>=2025.9.25; extra == "docs"
Requires-Dist: myst-parser>=2.0.0; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid>=0.8.1; extra == "docs"
Requires-Dist: pygments>=2.18.0; extra == "docs"
Requires-Dist: sphinx-tags>=0.4.0; extra == "docs"
Requires-Dist: sphinx-design>=0.6.0; extra == "docs"
Requires-Dist: ablog>=0.11.13; python_version >= "3.11" and extra == "docs"
Provides-Extra: viz
Provides-Extra: explorer
Requires-Dist: duckdb<2.0.0,>=1.0.0; extra == "explorer"
Provides-Extra: all
Requires-Dist: duckdb<2.0.0,>=1.5.0; extra == "all"
Requires-Dist: clickhouse-connect>=0.10.0; extra == "all"
Requires-Dist: clickhouse-driver>=0.2.0; extra == "all"
Requires-Dist: databricks-sql-connector>=2.0.0; extra == "all"
Requires-Dist: databricks-sdk>=0.20.0; extra == "all"
Requires-Dist: databricks-connect<19,>=14.0.0; extra == "all"
Requires-Dist: datafusion>=54.0.0; extra == "all"
Requires-Dist: pyarrow>=10.0.0; extra == "all"
Requires-Dist: firebolt-sdk>=1.18.0; extra == "all"
Requires-Dist: google-cloud-bigquery>=3.0.0; extra == "all"
Requires-Dist: google-cloud-storage>=2.0.0; extra == "all"
Requires-Dist: redshift-connector>=2.0.0; extra == "all"
Requires-Dist: snowflake-connector-python>=3.0.0; extra == "all"
Requires-Dist: trino>=0.328.0; extra == "all"
Requires-Dist: presto-python-client>=0.8.4; extra == "all"
Requires-Dist: psycopg[binary]>=3.1; extra == "all"
Requires-Dist: pyodbc>=4.0.0; extra == "all"
Requires-Dist: azure-identity>=1.15.0; extra == "all"
Requires-Dist: azure-storage-file-datalake>=12.14.0; extra == "all"
Requires-Dist: pyathena>=3.0.0; extra == "all"
Requires-Dist: boto3>=1.20.0; extra == "all"
Requires-Dist: cloudpathlib[azure,gs,s3]>=0.15.0; extra == "all"
Requires-Dist: pandas>=3.0.0; extra == "all"
Requires-Dist: chdb>=0.10.0; sys_platform != "win32" and extra == "all"
Requires-Dist: deltalake>=1.2.1; extra == "all"
Requires-Dist: pyiceberg>=0.10.0; extra == "all"
Requires-Dist: influxdb3-python>=0.10.0; extra == "all"
Requires-Dist: pymysql>=1.1.0; extra == "all"
Requires-Dist: singlestoredb>=1.0.0; extra == "all"
Requires-Dist: polars>=1.35.2; extra == "all"
Requires-Dist: dask[distributed]>=2025.1.0; extra == "all"
Requires-Dist: pyspark[connect]>=3.5.0; extra == "all"
Provides-Extra: cloud
Requires-Dist: databricks-sql-connector>=2.0.0; extra == "cloud"
Requires-Dist: databricks-sdk>=0.20.0; extra == "cloud"
Requires-Dist: firebolt-sdk>=1.18.0; extra == "cloud"
Requires-Dist: google-cloud-bigquery>=3.0.0; extra == "cloud"
Requires-Dist: google-cloud-storage>=2.0.0; extra == "cloud"
Requires-Dist: redshift-connector>=2.0.0; extra == "cloud"
Requires-Dist: snowflake-connector-python>=3.0.0; extra == "cloud"
Requires-Dist: trino>=0.328.0; extra == "cloud"
Requires-Dist: pyathena>=3.0.0; extra == "cloud"
Requires-Dist: boto3>=1.20.0; extra == "cloud"
Requires-Dist: cloudpathlib[azure,gs,s3]>=0.15.0; extra == "cloud"
Provides-Extra: cloudstorage
Requires-Dist: cloudpathlib[azure,gs,s3]>=0.15.0; extra == "cloudstorage"
Provides-Extra: duckdb
Requires-Dist: duckdb<2.0.0,>=1.5.0; extra == "duckdb"
Provides-Extra: ducklake
Requires-Dist: duckdb<2.0.0,>=1.5.0; extra == "ducklake"
Provides-Extra: clickhouse
Requires-Dist: clickhouse-driver>=0.2.0; extra == "clickhouse"
Provides-Extra: clickhouse-server
Requires-Dist: clickhouse-driver>=0.2.0; extra == "clickhouse-server"
Provides-Extra: clickhouse-cloud
Requires-Dist: clickhouse-connect>=0.10.0; extra == "clickhouse-cloud"
Provides-Extra: databricks
Requires-Dist: databricks-sql-connector>=2.0.0; extra == "databricks"
Requires-Dist: databricks-sdk>=0.20.0; extra == "databricks"
Requires-Dist: cloudpathlib>=0.15.0; extra == "databricks"
Provides-Extra: bigquery
Requires-Dist: google-cloud-bigquery>=3.0.0; extra == "bigquery"
Requires-Dist: google-cloud-storage>=2.0.0; extra == "bigquery"
Requires-Dist: cloudpathlib>=0.15.0; extra == "bigquery"
Provides-Extra: redshift
Requires-Dist: redshift-connector>=2.0.0; extra == "redshift"
Requires-Dist: boto3>=1.20.0; extra == "redshift"
Requires-Dist: cloudpathlib>=0.15.0; extra == "redshift"
Provides-Extra: snowflake
Requires-Dist: snowflake-connector-python>=3.0.0; extra == "snowflake"
Requires-Dist: cloudpathlib[azure,gs,s3]>=0.15.0; extra == "snowflake"
Provides-Extra: trino
Requires-Dist: trino>=0.328.0; extra == "trino"
Requires-Dist: cloudpathlib>=0.15.0; extra == "trino"
Provides-Extra: presto
Requires-Dist: presto-python-client>=0.8.4; extra == "presto"
Requires-Dist: cloudpathlib>=0.15.0; extra == "presto"
Provides-Extra: postgresql
Requires-Dist: psycopg[binary]>=3.1; extra == "postgresql"
Provides-Extra: questdb
Requires-Dist: psycopg[binary]>=3.1; extra == "questdb"
Requires-Dist: requests>=2.28.0; extra == "questdb"
Provides-Extra: synapse
Requires-Dist: pyodbc>=4.0.0; extra == "synapse"
Provides-Extra: fabric
Requires-Dist: pyodbc>=4.0.0; extra == "fabric"
Requires-Dist: azure-identity>=1.15.0; extra == "fabric"
Requires-Dist: azure-storage-file-datalake>=12.14.0; extra == "fabric"
Provides-Extra: athena
Requires-Dist: pyathena>=3.0.0; extra == "athena"
Requires-Dist: boto3>=1.20.0; extra == "athena"
Provides-Extra: datafusion
Requires-Dist: datafusion>=54.0.0; extra == "datafusion"
Requires-Dist: pyarrow>=10.0.0; extra == "datafusion"
Provides-Extra: firebolt
Requires-Dist: firebolt-sdk>=1.18.0; extra == "firebolt"
Requires-Dist: cloudpathlib>=0.15.0; extra == "firebolt"
Provides-Extra: databend
Requires-Dist: databend-driver>=0.28.0; extra == "databend"
Provides-Extra: doris
Requires-Dist: pymysql>=1.0.0; extra == "doris"
Provides-Extra: influxdb
Requires-Dist: influxdb3-python>=0.10.0; extra == "influxdb"
Requires-Dist: pyarrow>=10.0.0; extra == "influxdb"
Provides-Extra: starrocks
Requires-Dist: pymysql>=1.1.0; extra == "starrocks"
Provides-Extra: singlestore
Requires-Dist: singlestoredb>=1.0.0; extra == "singlestore"
Provides-Extra: tpcdi
Requires-Dist: pandas>=3.0.0; extra == "tpcdi"
Provides-Extra: clickhouse-local
Requires-Dist: chdb>=0.10.0; sys_platform != "win32" and extra == "clickhouse-local"
Provides-Extra: table-formats
Requires-Dist: deltalake>=1.2.1; extra == "table-formats"
Requires-Dist: pyiceberg>=0.10.0; extra == "table-formats"
Requires-Dist: vortex-data>=0.29.0; extra == "table-formats"
Provides-Extra: ai-primitives
Requires-Dist: sentence-transformers>=2.0.0; extra == "ai-primitives"
Requires-Dist: torch>=2.0.0; extra == "ai-primitives"
Requires-Dist: textblob>=0.17.0; extra == "ai-primitives"
Requires-Dist: spacy>=3.0.0; extra == "ai-primitives"
Provides-Extra: pandas
Requires-Dist: pandas>=3.0.0; extra == "pandas"
Provides-Extra: dataframe-pandas
Requires-Dist: pandas>=3.0.0; extra == "dataframe-pandas"
Provides-Extra: dask
Requires-Dist: dask[distributed]>=2025.1.0; extra == "dask"
Requires-Dist: pandas>=3.0.0; extra == "dask"
Provides-Extra: dataframe-dask
Requires-Dist: dask[distributed]>=2025.1.0; extra == "dataframe-dask"
Requires-Dist: pandas>=3.0.0; extra == "dataframe-dask"
Provides-Extra: cudf
Provides-Extra: dataframe-cudf
Provides-Extra: polars
Requires-Dist: polars>=1.35.2; extra == "polars"
Provides-Extra: dataframe-polars
Requires-Dist: polars>=1.35.2; extra == "dataframe-polars"
Provides-Extra: pyspark
Requires-Dist: pyspark>=3.5.0; extra == "pyspark"
Provides-Extra: lakesail
Requires-Dist: pyspark[connect]>=3.5.0; extra == "lakesail"
Provides-Extra: velox
Requires-Dist: pyspark[connect]>=3.5.0; extra == "velox"
Provides-Extra: dataframe-pyspark
Requires-Dist: pyspark>=3.5.0; extra == "dataframe-pyspark"
Provides-Extra: dataframe-datafusion
Requires-Dist: datafusion>=54.0.0; extra == "dataframe-datafusion"
Requires-Dist: pyarrow>=10.0.0; extra == "dataframe-datafusion"
Provides-Extra: dataframe-pandas-family
Requires-Dist: pandas>=3.0.0; extra == "dataframe-pandas-family"
Requires-Dist: dask[distributed]>=2025.1.0; extra == "dataframe-pandas-family"
Provides-Extra: dataframe-expression-family
Requires-Dist: polars>=1.35.2; extra == "dataframe-expression-family"
Requires-Dist: pyspark>=3.5.0; extra == "dataframe-expression-family"
Requires-Dist: datafusion>=54.0.0; extra == "dataframe-expression-family"
Provides-Extra: dataframe-all
Requires-Dist: pandas>=3.0.0; extra == "dataframe-all"
Requires-Dist: dask[distributed]>=2025.1.0; extra == "dataframe-all"
Requires-Dist: polars>=1.35.2; extra == "dataframe-all"
Requires-Dist: pyspark>=3.5.0; extra == "dataframe-all"
Requires-Dist: datafusion>=54.0.0; extra == "dataframe-all"
Provides-Extra: quick-start
Requires-Dist: polars>=1.35.2; extra == "quick-start"
Provides-Extra: cloud-spark-aws
Requires-Dist: boto3>=1.34.0; extra == "cloud-spark-aws"
Provides-Extra: cloud-spark-gcp
Requires-Dist: google-cloud-dataproc>=5.0.0; extra == "cloud-spark-gcp"
Requires-Dist: google-cloud-storage>=2.0.0; extra == "cloud-spark-gcp"
Provides-Extra: cloud-spark-azure
Requires-Dist: azure-identity>=1.15.0; extra == "cloud-spark-azure"
Requires-Dist: azure-storage-file-datalake>=12.14.0; extra == "cloud-spark-azure"
Requires-Dist: requests>=2.31.0; extra == "cloud-spark-azure"
Provides-Extra: cloud-spark-snowflake
Requires-Dist: snowflake-snowpark-python>=1.11.0; extra == "cloud-spark-snowflake"
Requires-Dist: pyspark>=3.5.0; extra == "cloud-spark-snowflake"
Provides-Extra: cloud-spark-databricks
Requires-Dist: databricks-sql-connector>=2.0.0; extra == "cloud-spark-databricks"
Requires-Dist: databricks-sdk>=0.20.0; extra == "cloud-spark-databricks"
Requires-Dist: databricks-connect<19,>=14.0.0; extra == "cloud-spark-databricks"
Requires-Dist: cloudpathlib>=0.15.0; extra == "cloud-spark-databricks"
Provides-Extra: cloud-spark
Requires-Dist: boto3>=1.34.0; extra == "cloud-spark"
Requires-Dist: google-cloud-dataproc>=5.0.0; extra == "cloud-spark"
Requires-Dist: google-cloud-storage>=2.0.0; extra == "cloud-spark"
Requires-Dist: azure-identity>=1.15.0; extra == "cloud-spark"
Requires-Dist: azure-storage-file-datalake>=12.14.0; extra == "cloud-spark"
Requires-Dist: requests>=2.31.0; extra == "cloud-spark"
Requires-Dist: snowflake-snowpark-python>=1.11.0; extra == "cloud-spark"
Requires-Dist: pyspark>=3.5.0; extra == "cloud-spark"
Requires-Dist: databricks-sql-connector>=2.0.0; extra == "cloud-spark"
Requires-Dist: databricks-sdk>=0.20.0; extra == "cloud-spark"
Requires-Dist: databricks-connect<19,>=14.0.0; extra == "cloud-spark"
Requires-Dist: cloudpathlib>=0.15.0; extra == "cloud-spark"
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2; extra == "mcp"
Requires-Dist: duckdb<2.0.0,>=1.5.0; extra == "mcp"
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.44; extra == "mcp"
Requires-Dist: opentelemetry-sdk<2,>=1.44; extra == "mcp"
Provides-Extra: spark
Requires-Dist: pyspark>=4.0.1; extra == "spark"
Dynamic: license-file

<!-- Copyright 2026 Joe Harris / BenchBox Project. Licensed under the MIT License. -->

```
█                   █    █
█▀▀▄ █▀▀█ █▀▀▄ █▀▀▀ █▀▀▄ █▀▀▄ ▄▀▀▄ ▀▄▄▀
█▄▄▀ █▄▄▄ █  █ █▄▄▄ █  █ █▄▄▀ ▀▄▄▀ ▄▀▀▄
```

# BenchBox

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Beta Software](https://img.shields.io/badge/Status-Beta-blue.svg)](https://github.com/BenchBox-dev/benchbox/issues)
[![codecov](https://codecov.io/github/BenchBox-dev/BenchBox/graph/badge.svg?token=3NY6DK7MDO)](https://codecov.io/github/BenchBox-dev/BenchBox)
[![PyPI Release](https://img.shields.io/pypi/v/benchbox)](https://pypi.org/project/benchbox/)
[![PyPI Downloads](https://img.shields.io/pepy/dt/benchbox.svg?label=PyPI%20Downloads)](https://pypi.org/project/benchbox/)

BenchBox is an open-source Python toolkit for benchmarking analytical data
platforms. It generates and loads data, runs repeatable workloads, validates
execution, and records comparable results through one workflow.

Use BenchBox to evaluate local databases, cloud data warehouses, and DataFrame
runtimes with the same benchmark definitions. It is built for data engineers,
platform evaluators, and performance practitioners who need evidence they can
inspect and reproduce.

BenchBox focuses on online analytical processing (OLAP). If you need an
online transaction processing (OLTP) benchmark, see the
[comparison of database benchmarking tools](docs/concepts/benchmarking-tools-compared.md).

## Why BenchBox?

- **Run recognized workloads.** Use TPC-H, TPC-DS, TPC-DI, ClickBench, SSB,
  Join Order Benchmark, and BenchBox's focused primitive workloads.
- **Compare different kinds of engines.** Run the same benchmark against SQL
  databases, cloud warehouses, and native DataFrame APIs.
- **Control the full run.** Generate data, create schemas, load tables, execute
  queries, validate results, and capture metrics from one command.
- **Reproduce results.** Record the benchmark, scale, platform, configuration,
  tuning, environment, timings, and validation evidence in structured result
  bundles.
- **Inspect before you spend.** Preview planned queries, files, phases, and
  configuration with dry-run support.
- **Analyze and share evidence.** Compare runs, render terminal charts, export
  reports, and contribute results to the public Results Explorer.

## Quick Start

The quickest local path uses DuckDB and a small TPC-H dataset.

### 1. Install BenchBox with DuckDB

Using [uv](https://docs.astral.sh/uv/):

```bash
uv add benchbox --extra duckdb
```

Using pip:

```bash
python -m pip install "benchbox[duckdb]"
```

DuckDB is an optional dependency. A plain `benchbox` installation includes
SQLite but does not include DuckDB.

The commands below use the `benchbox` executable installed by either method.
If you used `uv add` and have not activated the project environment, prefix
each command with `uv run --`.

### 2. Run a benchmark

```bash
benchbox run \
  --platform duckdb \
  --benchmark tpch \
  --scale 0.01
```

This command generates about 10 MB of TPC-H data, loads it into DuckDB, runs
the benchmark, validates the execution, and stores the result under
`benchmark_runs/`.

### 3. Inspect the result

```bash
benchbox results
```

The summary lists each recent run's benchmark, platform, timestamp, duration,
query count, and BenchBox version.

To preview a run without executing it:

```bash
benchbox run \
  --dry-run ./preview \
  --platform duckdb \
  --benchmark tpch \
  --scale 0.01
```

Continue with the [five-minute guide](docs/usage/getting-started.md), or see
the [installation guide](docs/usage/installation.md) for other platforms and
package extras.

## What can you benchmark?

### Benchmarks

BenchBox includes several kinds of analytical workloads:

- **TPC standards:** TPC-H, TPC-DS, and TPC-DI
- **Academic benchmarks:** SSB, AMPLab, and Join Order Benchmark
- **Industry and real-world workloads:** ClickBench, H2O DB Benchmark, NYC
  Taxi, Flight Data, TSBS DevOps, and CoffeeShop
- **Focused primitives:** read, write, transaction, metadata, and AI operations
- **AI and machine learning:** Vector Search
- **Experimental variants:** TPC-DS One Big Table, TPC-Havoc, TPC-H Skew, and
  TPC-H Data Vault

See the [benchmark catalog](docs/benchmarks/index.md) for workload details,
resource guidance, and selection help.

### Platforms

BenchBox uses adapters to run workloads across three broad groups:

- local and embedded SQL engines, such as DuckDB, SQLite, and DataFusion;
- cloud warehouses and distributed SQL engines, such as Snowflake, BigQuery,
  Databricks, Redshift, ClickHouse, Spark, Trino, and PrestoDB; and
- native DataFrame runtimes, such as Polars, Pandas, PySpark, DataFusion,
  Dask, and cuDF.

Support status and published evidence answer different questions. A supported
adapter can be available before the public results corpus contains a run for
that platform. Check the [platform guides](docs/platforms/index.md),
[platform comparison matrix](docs/platforms/comparison-matrix.md), and
[public support contract](docs/reference/public-contracts.md) before planning
a comparison.

<!-- benchbox-registry-counts:start -->

- Platform registry: **50** metadata entries; **46** SQL-capable; **18** DataFrame-capable; **14** dual-mode; support status counts: stable=5, beta=28, experimental=16, deprecated=1.
- Benchmark registry: **23** metadata entries; **22** public discovery entries.

<!-- benchbox-registry-counts:end -->

These counts come from BenchBox's registries and are checked in the test suite.
Use `benchbox platforms list` and `benchbox benchmarks list` for the current
names and support details.

## Results you can inspect and compare

Each run records more than a headline time. Result bundles can include query
timings, validation status, resource measurements, platform configuration,
tuning evidence, environment metadata, cost data, and captured query plans.
The available fields depend on the platform and run configuration.

Use the CLI to inspect, visualize, and export local results:

```bash
uv run -- benchbox results
uv run -- benchbox visualize benchmark_runs/results/*.json
uv run -- benchbox export --last --format html
```

The public [BenchBox Results Explorer](https://benchbox.dev/results/) lets you
inspect published runs and their provenance. Comparisons are meaningful only
when the workload, scale, phase, configuration, tuning, hardware, and evidence
are compatible; a shared benchmark name alone is not enough.

To contribute a complete run, follow the
[result contribution guide](docs/contributing-results.md). It explains local
validation, privacy safeguards, trust labels, and the `published-results`
submission process.

## Learn more

| Goal | Start here |
| --- | --- |
| Install BenchBox | [Installation and environment setup](docs/usage/installation.md) |
| Run your first benchmark | [Getting started in five minutes](docs/usage/getting-started.md) |
| Learn the CLI | [CLI quick reference](docs/usage/cli-quick-start.md) |
| Choose a benchmark | [Benchmark catalog](docs/benchmarks/index.md) |
| Choose a platform | [Platform selection guide](docs/platforms/platform-selection-guide.md) |
| Use a DataFrame runtime | [DataFrame platforms](docs/platforms/dataframe.md) |
| Use the Python API | [Python API reference](docs/reference/python-api/index.rst) |
| Find examples | [Examples guide](docs/usage/examples.md) |
| Troubleshoot a run | [Troubleshooting guide](docs/usage/troubleshooting.md) |
| Understand the design | [Architecture overview](docs/concepts/architecture.md) |
| Add a platform | [Adding new platforms](docs/development/adding-new-platforms.md) |
| Create a custom benchmark | [Custom benchmark guide](docs/advanced/custom-benchmarks.md) |

The [documentation index](docs/README.md) links to the complete user,
reference, design, and contributor documentation.

## Installation and platform setup

The quick start intentionally installs only the DuckDB extra. BenchBox offers
separate extras for cloud services, database drivers, DataFrame libraries, and
development tools so that you install only what you need.

See the [installation guide](docs/usage/installation.md) for the supported
package managers and extras. Then use the dependency checker for your target
platform:

```bash
uv run -- benchbox check-deps --platform databricks
```

Platform guides cover credentials, connection settings, and platform-specific
options. Do not put credentials in configuration files that you commit.

## Project status

> **BenchBox is BETA software.** The CLI and core workflows are usable, but
> public APIs may change before 1.0.

Current release: v0.4.1.

Support labels describe the stability of each public surface. The
`benchbox.experimental` namespace has no compatibility guarantee and can change
or be removed without notice. Read the
[public contracts and support taxonomy](docs/reference/public-contracts.md)
before depending on an experimental or beta interface.

See [PyPI](https://pypi.org/project/benchbox/) for published releases and
[DISCLAIMER.md](DISCLAIMER.md) for project limitations. Release and versioning
details live in the
[backward-compatibility policy](docs/reference/backward-compatibility.md) and
[release guide](docs/operations/release-guide.md).

## Contributing

Bug reports, documentation improvements, platform adapters, benchmark work,
and result contributions are welcome.

- Read [CONTRIBUTING.md](CONTRIBUTING.md) before changing the codebase.
- Use [GitHub Issues](https://github.com/BenchBox-dev/benchbox/issues) for bugs
  and feature requests.
- Use [GitHub Discussions](https://github.com/BenchBox-dev/benchbox/discussions)
  for questions and ideas.
- Follow the [result contribution guide](docs/contributing-results.md) to add a
  benchmark run to the public corpus.

## Disclaimer

BenchBox is an independent open-source project. It is not affiliated with the
Transaction Processing Performance Council or with Joe Harris's past or
present employers. See [DISCLAIMER.md](DISCLAIMER.md) for details.

## License

BenchBox is available under the [MIT License](LICENSE).
