tpch-runner


Nametpch-runner JSON
Version 1.0.1 PyPI version JSON
download
home_pageNone
SummaryA tool for running TPC-H benchmarks and analyzing results.
upload_time2025-02-22 22:07:06
maintainerNone
docs_urlNone
authorNone
requires_python>=3.7
licenseMIT
keywords tpc-h benchmark database performance
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # tpch\_runner: TPC-H Benchmark Tool

tpch\_runner is a database-agnostic TPC-H benchmark tool designed for running and analyzing the TPC-H benchmark across multiple databases. It allows easy setup, execution, and result analysis, make TPC-H testing of their database systems much more efficiently.

## Features

- **CLI-driven TPC-H benchmarking**:
  - Manage database connections.
  - Generate and load TPC-H test data.
  - Prepare databases (e.g., table creation, optimization, and data reloading).
  - Run individual queries or full TPC-H Powertests.
- **Comprehensive Result Analysis**:
  - Manage, validate, and compare benchmark results.
  - Generate charts to visualize Powertest results.
  - Bundle a small dataset for verifying database setup and TPC-H compliance.
- **Multi-database support**:
  - Built-in support for MySQL, PostgreSQL, DuckDB, and RapidsDB.
  - Open architecture to easily integrate additional databases.

## Installation

Getting started with **tpch_runner** is quick and simple. Just clone the repository and install it in editable mode:

```sh
# install by clone from github repository
git clone https://github.com/your-repo/tpch_runner.git
cd tpch_runner
pip install -e .

# install from Pypi package
pip install tpch_runner
```

### Important Notes

- **Test Data Generation**: **tpch_runner** supports TPC-H test data generation but **does not include dbgen or qgen**. You need to manually add the following compiled files to the `tpch_runner/tpch/tool` directory:
  - `dbgen`
  - `qgen`
  - `dists.dss`
- **Line Delimiters**:
  - The official TPC-H `dbgen` uses `|\n` line delimiters, which some databases (e.g., PostgreSQL) may not support. You can either remove these delimiters manually or use a [TPC-H dbgen variant](https://github.com/gregrahn/tpch-kit) that avoids them.

## Getting Started

To use **tpch_runner**, simply run the `runner` CLI tool. Use `-h` or `--help` for detailed help on any command:

```sh
$ runner -h
Usage: runner [OPTIONS] COMMAND [ARGS]...
```

### Typical Benchmark Workflow

1. Set up a database connection.
2. Prepare the TPC-H database (create tables, generate and load data, optimize).
3. Run individual queries or a full TPC-H Powertest.
4. Analyze benchmark results.
5. Compare results across different runs or databases.

### Example Commands

- **Add a Database Connection**:

```sh
$ runner db add -H localhost -t mysql -u root -W -d tpch -a mysql2 -p 3306
Enter database password:
[INFO] Added database connection.
```

- **Create Tables**:

```sh
runner db create -a my1
```

- **Load Data**:

```sh
runner db load -a duck -m ','
```

- **Run a Single Query:**

```sh
runner run query -a duck 15 --no-report
```

- **Run a TPC-H Powertest**

```sh
runner run powertest -a duck
```

- **Result Analysis:**

```sh
$ runner power list
+------+----------+---------------------+-----------+---------------+---------+
|   ID | DB       | Date                | Success   |   Runtime (s) | Scale   |
|------+----------+---------------------+-----------+---------------+---------|
|    2 | mysql    | 2025-01-19 21:48:23 | True      |        0.0492 | small   |
|   10 | rapidsdb | 2025-01-27 19:44:22 | True      |        5.5694 | small   |
|   17 | duckdb   | 2025-01-30 20:21:50 | True      |        0.8701 | small   |
|   20 | pg       | 2025-01-30 23:53:07 | True      |       14.8139 | 1       |
+------+----------+---------------------+-----------+---------------+---------+
```

- **Validate Test Results:**

```sh
runner power validate 18
```

- **Compare two test results:**

```sh
runner power compare -s 11 -d 20
```

- **Generate Comparison Charts:**

```sh
runner power multi 2 16 18
```

## Result Analysis

**tpch_runner** provides a variety of ways to analyze and visualize your benchmarking results:

- Manage Powertest and query results.
- View test result details.
- Validate results against known good answers.
- Compare results from different databases or test runs.
- Generate line and bar charts for visualizing Powertest performance.
- Create multi-result comparison charts.

![barchart-Powertest](./docs/imgs/duckdb_20250130_202150.png)

![linechart-multi-comparison](./docs/imgs/line-rapidsdb-pg-pg-multi.png)

## Supported Databases

- MySQL
- PostgreSQL
- RapidsDB
- DuckDB

Integrating additional databases is straightforward by **tpch_runner**'s open architecture.

---

For more details, refer to the documentation or run `runner -h` for CLI usage guidance.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "tpch-runner",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": null,
    "keywords": "TPC-H, benchmark, database, performance",
    "author": null,
    "author_email": "Robert Li <lgprobert@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/38/59/3a17bb122cc2041741f270650095b5c0756657f11faa41b69dd40d80b98e/tpch_runner-1.0.1.tar.gz",
    "platform": null,
    "description": "# tpch\\_runner: TPC-H Benchmark Tool\n\ntpch\\_runner is a database-agnostic TPC-H benchmark tool designed for running and analyzing the TPC-H benchmark across multiple databases. It allows easy setup, execution, and result analysis, make TPC-H testing of their database systems much more efficiently.\n\n## Features\n\n- **CLI-driven TPC-H benchmarking**:\n  - Manage database connections.\n  - Generate and load TPC-H test data.\n  - Prepare databases (e.g., table creation, optimization, and data reloading).\n  - Run individual queries or full TPC-H Powertests.\n- **Comprehensive Result Analysis**:\n  - Manage, validate, and compare benchmark results.\n  - Generate charts to visualize Powertest results.\n  - Bundle a small dataset for verifying database setup and TPC-H compliance.\n- **Multi-database support**:\n  - Built-in support for MySQL, PostgreSQL, DuckDB, and RapidsDB.\n  - Open architecture to easily integrate additional databases.\n\n## Installation\n\nGetting started with **tpch_runner** is quick and simple. Just clone the repository and install it in editable mode:\n\n```sh\n# install by clone from github repository\ngit clone https://github.com/your-repo/tpch_runner.git\ncd tpch_runner\npip install -e .\n\n# install from Pypi package\npip install tpch_runner\n```\n\n### Important Notes\n\n- **Test Data Generation**: **tpch_runner** supports TPC-H test data generation but **does not include dbgen or qgen**. You need to manually add the following compiled files to the `tpch_runner/tpch/tool` directory:\n  - `dbgen`\n  - `qgen`\n  - `dists.dss`\n- **Line Delimiters**:\n  - The official TPC-H `dbgen` uses `|\\n` line delimiters, which some databases (e.g., PostgreSQL) may not support. You can either remove these delimiters manually or use a [TPC-H dbgen variant](https://github.com/gregrahn/tpch-kit) that avoids them.\n\n## Getting Started\n\nTo use **tpch_runner**, simply run the `runner` CLI tool. Use `-h` or `--help` for detailed help on any command:\n\n```sh\n$ runner -h\nUsage: runner [OPTIONS] COMMAND [ARGS]...\n```\n\n### Typical Benchmark Workflow\n\n1. Set up a database connection.\n2. Prepare the TPC-H database (create tables, generate and load data, optimize).\n3. Run individual queries or a full TPC-H Powertest.\n4. Analyze benchmark results.\n5. Compare results across different runs or databases.\n\n### Example Commands\n\n- **Add a Database Connection**:\n\n```sh\n$ runner db add -H localhost -t mysql -u root -W -d tpch -a mysql2 -p 3306\nEnter database password:\n[INFO] Added database connection.\n```\n\n- **Create Tables**:\n\n```sh\nrunner db create -a my1\n```\n\n- **Load Data**:\n\n```sh\nrunner db load -a duck -m ','\n```\n\n- **Run a Single Query:**\n\n```sh\nrunner run query -a duck 15 --no-report\n```\n\n- **Run a TPC-H Powertest**\n\n```sh\nrunner run powertest -a duck\n```\n\n- **Result Analysis:**\n\n```sh\n$ runner power list\n+------+----------+---------------------+-----------+---------------+---------+\n|   ID | DB       | Date                | Success   |   Runtime (s) | Scale   |\n|------+----------+---------------------+-----------+---------------+---------|\n|    2 | mysql    | 2025-01-19 21:48:23 | True      |        0.0492 | small   |\n|   10 | rapidsdb | 2025-01-27 19:44:22 | True      |        5.5694 | small   |\n|   17 | duckdb   | 2025-01-30 20:21:50 | True      |        0.8701 | small   |\n|   20 | pg       | 2025-01-30 23:53:07 | True      |       14.8139 | 1       |\n+------+----------+---------------------+-----------+---------------+---------+\n```\n\n- **Validate Test Results:**\n\n```sh\nrunner power validate 18\n```\n\n- **Compare two test results:**\n\n```sh\nrunner power compare -s 11 -d 20\n```\n\n- **Generate Comparison Charts:**\n\n```sh\nrunner power multi 2 16 18\n```\n\n## Result Analysis\n\n**tpch_runner** provides a variety of ways to analyze and visualize your benchmarking results:\n\n- Manage Powertest and query results.\n- View test result details.\n- Validate results against known good answers.\n- Compare results from different databases or test runs.\n- Generate line and bar charts for visualizing Powertest performance.\n- Create multi-result comparison charts.\n\n![barchart-Powertest](./docs/imgs/duckdb_20250130_202150.png)\n\n![linechart-multi-comparison](./docs/imgs/line-rapidsdb-pg-pg-multi.png)\n\n## Supported Databases\n\n- MySQL\n- PostgreSQL\n- RapidsDB\n- DuckDB\n\nIntegrating additional databases is straightforward by **tpch_runner**'s open architecture.\n\n---\n\nFor more details, refer to the documentation or run `runner -h` for CLI usage guidance.\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A tool for running TPC-H benchmarks and analyzing results.",
    "version": "1.0.1",
    "project_urls": {
        "Homepage": "https://github.com/lgprobert/tpch_runner"
    },
    "split_keywords": [
        "tpc-h",
        " benchmark",
        " database",
        " performance"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "ac64cd9942ef577c2e96264a98c8033952aa92affbb639bf4e489ea262eccc93",
                "md5": "e4f319ffb6bc501e9488b5835d1984a4",
                "sha256": "f3cb44532ad11f859f0d3f3af8ad298b8ff9de79fee49c651c6ecc56b9df7172"
            },
            "downloads": -1,
            "filename": "tpch_runner-1.0.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "e4f319ffb6bc501e9488b5835d1984a4",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 39051,
            "upload_time": "2025-02-22T22:07:03",
            "upload_time_iso_8601": "2025-02-22T22:07:03.440584Z",
            "url": "https://files.pythonhosted.org/packages/ac/64/cd9942ef577c2e96264a98c8033952aa92affbb639bf4e489ea262eccc93/tpch_runner-1.0.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "38593a17bb122cc2041741f270650095b5c0756657f11faa41b69dd40d80b98e",
                "md5": "beff9e025617d78933e2ce9a8f6b992f",
                "sha256": "bdaca5ca4fb5018878236c0ba7fbb3bd2c50869a3b3c16f3b4c2bc8135480275"
            },
            "downloads": -1,
            "filename": "tpch_runner-1.0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "beff9e025617d78933e2ce9a8f6b992f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 31319,
            "upload_time": "2025-02-22T22:07:06",
            "upload_time_iso_8601": "2025-02-22T22:07:06.761753Z",
            "url": "https://files.pythonhosted.org/packages/38/59/3a17bb122cc2041741f270650095b5c0756657f11faa41b69dd40d80b98e/tpch_runner-1.0.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-22 22:07:06",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "lgprobert",
    "github_project": "tpch_runner",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "tpch-runner"
}
        
Elapsed time: 1.61665s