/timescaledb-benchmarker

A Benchmarker for your TimescaleDB instance. This is just a demo project and is not meant for production use.

Primary LanguageGoMIT LicenseMIT

Timescale Benchmarker

License All Contributors GitHub Actions Workflow Status last commit GitHub go.mod Go version

A Benchmarker for your TimescaleDB instance. This is just a demo project and is not meant for production use.

Installation

Go install

You can install the binary globally by running:

go install github.com/smoya/timescaledb-benchmarker/cmd/benchmarker@latest

Precompiled binaries

You will find precompiled binaries on the releases page. Architectures supported:

  • Darwin AMD64 (Apple Intel)
  • Darwin ARM64 (Apple Silicon)
  • Linux AMD64
  • Windows AMD64

Please feel free to open an issue requesting the inclusion of any other architecture compiled binary for new releases.

Docker

This project contains a Dockerfile in order to build its Docker image. You can find all the Docker images at Docker Hub.

Run this CLI app from :

docker run smoya/timescaledb-benchmarker

Please refer to the Usage section for the full list of available commands.

Demo

This project contains a Docker Compose file that can be used for demoing the benchmarker. Fixtures are available under deployments/data.

Please run:

docker compose -f deployments/docker-compose/compose.yml up

This will spin up two containers:

  1. timescaledb: using timescale/timescaledb docker image. This spins up a TimescaleDB database (no HA). It is configured to run init scripts that will create and populate the DB with the files located under deployments/data.
  2. timescaledb-benchmarker: using [smoya/timescaledb-benchmarker], which is the image that we build in this repository.

You can overwrite the default environment variables by using the --env flag. Please refer to Configuration for the full list of supported flags and environment variables.

Executing the benchmark

The benchmarker will use the data from deployments/data/query_params.csv in order to generate the queries for the benchmark.

Please run the following in a new shell:

docker exec timescaledb-benchmarker timescaledb-benchmarker benchmark select

The deployments/docker-compose/compose.yml file contains the required environment variables set. However, you can overwrite them or add new ones via the --env flag.

I.e., if you want to disable the debug log level, please run:

docker exec --env TIMESCALEDB_BENCHMARKER_BENCHMARK_DEBUG=false timescaledb-benchmarker timescaledb-benchmarker benchmark select

Usage

This CLI app is a binary that offers mainly a CLI GUI, split into several commands. Find the docs for each of the commands in docs/cmd.

Development

Prerequisites

  • Go v1.23 or higher.
  • Optional: Docker. Used for building and running the CLI app in an isolated env.
    • Additionally, there is a compose.yml that spins up this app plus a TimescaleDB DB instance (including fixtures). More info on the Demo section.

Build

A dedicated Makefile target is available:

make build

You will find the compiled binary under bin/out directory.

Lint

golangci-lint is used for linting the code. A dedicated Makefile target is available:

make lint

Test

Unit tests are available for each .go file. Testify toolkit is installed and in use.

There are two Makefile targets:

  1. make test, which runs all tests with the native go race condition detector.
  2. make coverage, which runs all tests as make test does plus it shows up code coverage statistics.

Releases

Releases are handled automatically on each push to the main branch via Semantic Release. Commits are following Conventional Commits, and releases will only happen when commits have certain prefixes:

  • feat: a MINOR release will happen. Example: feat: add a new feature.
  • fix: a PATCH release will happen. Example: fix: add a new fix.
  • any of the previous with a ! suffix: a MAJOR release will happen. Example: feat!: add a new breaking change.

Internal docs

A set of internal docs and design decisions can be found in docs/internal.md. If you want to know why some things are like they are, that is for you.

Contributing

Contributions are always encouraged! Please submit your PR's or issues. Tag or assign any of the code owners (at this moment, only me: @smoya) as reviewers. Be aware of the LICENSE of this project before submitting your PR.

Feel free to ping me if you have any doubts or need an onboarding of this project.

Contributors

This project follows All Contributors for recognizing contributors.

Thanks goes to these people ♥️:


Sergio Moya
💻 📖 💡 🤔 🚇 🚧 📆 🔬 ⚠️ ✅