From 3c3607daa0ce96c9dd8bef2693d9fcddcd255a8a Mon Sep 17 00:00:00 2001 From: ETHenzlere <92583189+ETHenzlere@users.noreply.github.com> Date: Sun, 1 Oct 2023 17:37:04 +0200 Subject: [PATCH 1/3] Update README.md --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index 801a3abd3..87d602105 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ BenchBase (formerly [OLTPBench](https://github.com/oltpbenchmark/oltpbench/)) is **Table of Contents** +- [Prerequisites](#prerequisites) - [Quickstart](#quickstart) - [Description](#description) - [Usage Guide](#usage-guide) @@ -16,6 +17,13 @@ BenchBase (formerly [OLTPBench](https://github.com/oltpbenchmark/oltpbench/)) is --- +## Prerequisites + +Java 17 needs to be installed on the system in order to run the benchbase commands. + +It can be downloaded directly from the [official download page.](https://www.oracle.com/java/technologies/downloads/#java17) + + ## Quickstart To clone and build BenchBase using the `postgres` profile, @@ -151,6 +159,17 @@ mvn clean compile exec:java -P postgres -Dexec.args="-b tpcc -c config/postgres/ this is equivalent to the steps above but eliminates the need to first package and then extract the distribution. +### How to configure Database access + +The configuration files located in the `/config` folder define the username and password needed to connect to the databases. They can be adapted on a global level by editing the `*_config.xml` files of the corresponding database. + +If there is already a built distribution, the config can also be adapted directly in the `/config` folder of the build. + +```xml +admin +password +``` + ### How to Enable Logging To enable logging, e.g., for the PostgreSQL JDBC driver, add the following JVM property when starting... From 44fac74641e82739c3d6904225c4e65a8ff76329 Mon Sep 17 00:00:00 2001 From: Eric Enzler Date: Tue, 3 Oct 2023 12:58:28 +0200 Subject: [PATCH 2/3] Split Prerequisites into two sections --- README.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 87d602105..049051214 100644 --- a/README.md +++ b/README.md @@ -19,10 +19,19 @@ BenchBase (formerly [OLTPBench](https://github.com/oltpbenchmark/oltpbench/)) is ## Prerequisites -Java 17 needs to be installed on the system in order to run the benchbase commands. +### Non-Containerized -It can be downloaded directly from the [official download page.](https://www.oracle.com/java/technologies/downloads/#java17) +Java 17 needs to be installed on the machine in order to run the benchbase commands. +Java can be downloaded from the [official download page.](https://www.oracle.com/java/technologies/downloads/#java17) + +### Containerized + +Benchbase supports the usage inside of docker containers. + +Docker can be downloaded from the [official download page.](https://docs.docker.com/get-docker/) + +> See the [docker section](#how-to-use-with-docker) for more details on how to use benchbase with docker. ## Quickstart @@ -187,7 +196,7 @@ To modify the logging level you can update [`logging.properties`](src/main/resou ./mvnw -B release:perform ``` -### How use with Docker +### How to use with Docker - Build or pull a dev image to help building from source: From 5da6c30e3f259fc610f66715aa8d34abb84b2e57 Mon Sep 17 00:00:00 2001 From: Eric Enzler Date: Thu, 26 Oct 2023 10:22:23 +0200 Subject: [PATCH 3/3] PR comments + Formatting --- README.md | 189 +++++++++++++++++++++++------------------------ config/README.md | 69 +++++++++++++++++ 2 files changed, 163 insertions(+), 95 deletions(-) create mode 100644 config/README.md diff --git a/README.md b/README.md index 049051214..1bb4339fe 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,14 @@ BenchBase (formerly [OLTPBench](https://github.com/oltpbenchmark/oltpbench/)) is **Table of Contents** -- [Prerequisites](#prerequisites) -- [Quickstart](#quickstart) -- [Description](#description) -- [Usage Guide](#usage-guide) -- [Contributing](#contributing) -- [Known Issues](#known-issues) -- [Credits](#credits) -- [Citing This Repository](#citing-this-repository) +- [Prerequisites](#prerequisites) +- [Quickstart](#quickstart) +- [Description](#description) +- [Usage Guide](#usage-guide) +- [Contributing](#contributing) +- [Known Issues](#known-issues) +- [Credits](#credits) +- [Citing This Repository](#citing-this-repository) --- @@ -77,24 +77,24 @@ features, e.g., per-transaction-type latency and throughput logs. The BenchBase framework has the following benchmarks: -* [AuctionMark](https://github.com/cmu-db/benchbase/wiki/AuctionMark) -* [CH-benCHmark](https://github.com/cmu-db/benchbase/wiki/CH-benCHmark) -* [Epinions.com](https://github.com/cmu-db/benchbase/wiki/epinions) -* hyadapt -- pending configuration files -* [NoOp](https://github.com/cmu-db/benchbase/wiki/NoOp) -* [OT-Metrics](https://github.com/cmu-db/benchbase/wiki/OT-Metrics) -* [Resource Stresser](https://github.com/cmu-db/benchbase/wiki/Resource-Stresser) -* [SEATS](https://github.com/cmu-db/benchbase/wiki/Seats) -* [SIBench](https://github.com/cmu-db/benchbase/wiki/SIBench) -* [SmallBank](https://github.com/cmu-db/benchbase/wiki/SmallBank) -* [TATP](https://github.com/cmu-db/benchbase/wiki/TATP) -* [TPC-C](https://github.com/cmu-db/benchbase/wiki/TPC-C) -* [TPC-H](https://github.com/cmu-db/benchbase/wiki/TPC-H) -* TPC-DS -- pending configuration files -* [Twitter](https://github.com/cmu-db/benchbase/wiki/Twitter) -* [Voter](https://github.com/cmu-db/benchbase/wiki/Voter) -* [Wikipedia](https://github.com/cmu-db/benchbase/wiki/Wikipedia) -* [YCSB](https://github.com/cmu-db/benchbase/wiki/YCSB) +- [AuctionMark](https://github.com/cmu-db/benchbase/wiki/AuctionMark) +- [CH-benCHmark](https://github.com/cmu-db/benchbase/wiki/CH-benCHmark) +- [Epinions.com](https://github.com/cmu-db/benchbase/wiki/epinions) +- hyadapt -- pending configuration files +- [NoOp](https://github.com/cmu-db/benchbase/wiki/NoOp) +- [OT-Metrics](https://github.com/cmu-db/benchbase/wiki/OT-Metrics) +- [Resource Stresser](https://github.com/cmu-db/benchbase/wiki/Resource-Stresser) +- [SEATS](https://github.com/cmu-db/benchbase/wiki/Seats) +- [SIBench](https://github.com/cmu-db/benchbase/wiki/SIBench) +- [SmallBank](https://github.com/cmu-db/benchbase/wiki/SmallBank) +- [TATP](https://github.com/cmu-db/benchbase/wiki/TATP) +- [TPC-C](https://github.com/cmu-db/benchbase/wiki/TPC-C) +- [TPC-H](https://github.com/cmu-db/benchbase/wiki/TPC-H) +- TPC-DS -- pending configuration files +- [Twitter](https://github.com/cmu-db/benchbase/wiki/Twitter) +- [Voter](https://github.com/cmu-db/benchbase/wiki/Voter) +- [Wikipedia](https://github.com/cmu-db/benchbase/wiki/Wikipedia) +- [YCSB](https://github.com/cmu-db/benchbase/wiki/YCSB) This framework is design to allow for easy extension. We provide stub code that a contributor can use to include a new benchmark, leveraging all the system features (logging, controlled speed, controlled mixture, etc.) @@ -104,7 +104,8 @@ benchmark, leveraging all the system features (logging, controlled speed, contro ## Usage Guide ### How to Build -Run the following command to build the distribution for a given database specified as the profile name (`-P`). The following profiles are currently supported: `postgres`, `mysql`, `mariadb`, `sqlite`, `cockroachdb`, `phoenix`, and `spanner`. + +Run the following command to build the distribution for a given database specified as the profile name (`-P`). The following profiles are currently supported: `postgres`, `mysql`, `mariadb`, `sqlite`, `cockroachdb`, `phoenix`, and `spanner`. ```bash ./mvnw clean package -P @@ -112,23 +113,27 @@ Run the following command to build the distribution for a given database specifi The following files will be placed in the `./target` folder: -* `benchbase-.tgz` -* `benchbase-.zip` +- `benchbase-.tgz` +- `benchbase-.zip` ### How to Run -Once you build and unpack the distribution, you can run `benchbase` just like any other executable jar. The following examples assume you are running from the root of the expanded `.zip` or `.tgz` distribution. If you attempt to run `benchbase` outside of the distribution structure you may encounter a variety of errors including `java.lang.NoClassDefFoundError`. + +Once you build and unpack the distribution, you can run `benchbase` just like any other executable jar. The following examples assume you are running from the root of the expanded `.zip` or `.tgz` distribution. If you attempt to run `benchbase` outside of the distribution structure you may encounter a variety of errors including `java.lang.NoClassDefFoundError`. To bring up help contents: + ```bash java -jar benchbase.jar -h ``` To execute the `tpcc` benchmark: + ```bash java -jar benchbase.jar -b tpcc -c config/postgres/sample_tpcc_config.xml --create=true --load=true --execute=true ``` For composite benchmarks like `chbenchmark`, which require multiple schemas to be created and loaded, you can provide a comma separated list: + ```bash java -jar benchbase.jar -b tpcc,chbenchmark -c config/postgres/sample_chbenchmark_config.xml --create=true --load=true --execute=true ``` @@ -168,16 +173,10 @@ mvn clean compile exec:java -P postgres -Dexec.args="-b tpcc -c config/postgres/ this is equivalent to the steps above but eliminates the need to first package and then extract the distribution. -### How to configure Database access - -The configuration files located in the `/config` folder define the username and password needed to connect to the databases. They can be adapted on a global level by editing the `*_config.xml` files of the corresponding database. +### How to configure Connections & Workloads -If there is already a built distribution, the config can also be adapted directly in the `/config` folder of the build. - -```xml -admin -password -``` +The configuration files are located in the `/config` folder and can be used to adapt the benchbase config to the user's system of choice. +A more detailed explanation can be found [here](/config/README.md). ### How to Enable Logging @@ -198,44 +197,44 @@ To modify the logging level you can update [`logging.properties`](src/main/resou ### How to use with Docker -- Build or pull a dev image to help building from source: +- Build or pull a dev image to help building from source: - ```sh - ./docker/benchbase/build-dev-image.sh - ./docker/benchbase/run-dev-image.sh - ``` + ```sh + ./docker/benchbase/build-dev-image.sh + ./docker/benchbase/run-dev-image.sh + ``` - or + or - ```sh - docker run -it --rm --pull \ - -v /path/to/benchbase-source:/benchbase \ - -v $HOME/.m2:/home/containeruser/.m2 \ - benchbase.azure.cr.io/benchbase-dev - ``` + ```sh + docker run -it --rm --pull \ + -v /path/to/benchbase-source:/benchbase \ + -v $HOME/.m2:/home/containeruser/.m2 \ + benchbase.azure.cr.io/benchbase-dev + ``` -- Build the full image: +- Build the full image: - ```sh - # build an image with all profiles - ./docker/benchbase/build-full-image.sh + ```sh + # build an image with all profiles + ./docker/benchbase/build-full-image.sh - # or if you only want to build some of them - BENCHBASE_PROFILES='postgres mysql' ./docker/benchbase/build-full-image.sh - ``` + # or if you only want to build some of them + BENCHBASE_PROFILES='postgres mysql' ./docker/benchbase/build-full-image.sh + ``` -- Run the image for a given profile: +- Run the image for a given profile: - ```sh - BENCHBASE_PROFILE='postgres' ./docker/benchbase/run-full-image.sh --help # or other benchbase args as before - ``` + ```sh + BENCHBASE_PROFILE='postgres' ./docker/benchbase/run-full-image.sh --help # or other benchbase args as before + ``` - or + or - ```sh - docker run -it --rm --env BENCHBASE_PROFILE='postgres' \ - -v results:/benchbase/results benchbase.azurecr.io/benchbase --help # or other benchbase args as before - ``` + ```sh + docker run -it --rm --env BENCHBASE_PROFILE='postgres' \ + -v results:/benchbase/results benchbase.azurecr.io/benchbase --help # or other benchbase args as before + ``` > See the [docker/benchbase/README.md](./docker/benchbase/) for further details. @@ -251,9 +250,9 @@ Please see the existing MySQL and PostgreSQL code for an example. We welcome all contributions! Please open a pull request. Common contributions may include: -- Adding support for a new DBMS. -- Adding more tests of existing benchmarks. -- Fixing any bugs or known issues. +- Adding support for a new DBMS. +- Adding more tests of existing benchmarks. +- Fixing any bugs or known issues. ## Known Issues @@ -267,31 +266,31 @@ The original OLTPBench code was largely written by the authors of the original p A significant portion of the modernization was contributed by [Tim Veil @ Cockroach Labs](https://github.com/timveil-cockroach), including but not limited to: -* Built with and for Java ~~11~~ 17. -* Migration from Ant to Maven. - * Reorganized project to fit Maven structure. - * Removed static `lib` directory and dependencies. - * Updated required dependencies and removed unused or unwanted dependencies. - * Moved all non `.java` files to standard Maven `resources` directory. - * Shipped with [Maven Wrapper](https://maven.apache.org/wrapper). -* Improved packaging and versioning. - * Moved to Calendar Versioning (https://calver.org/). - * Project is now distributed as a `.tgz` or `.zip` with an executable `.jar`. - * All code updated to read `resources` from inside `.jar` instead of directory. -* Moved from direct dependence on Log4J to SLF4J. -* Reorganized and renamed many files for clarity and consistency. -* Applied countless fixes based on "Static Analysis". - * JDK migrations (boxing, un-boxing, etc.). - * Implemented `try-with-resources` for all `java.lang.AutoCloseable` instances. - * Removed calls to `printStackTrace()` or `System.out.println` in favor of proper logging. -* Reformatted code and cleaned up imports. -* Removed all calls to `assert`. -* Removed various forms of dead code and stale configurations. -* Removed calls to `commit()` during `Loader` operations. -* Refactored `Worker` and `Loader` usage of `Connection` objects and cleaned up transaction handling. -* Introduced [Dependabot](https://dependabot.com/) to keep Maven dependencies up to date. -* Simplified output flags by removing most of them, generally leaving the reporting functionality enabled by default. -* Provided an alternate `Catalog` that can be populated directly from the configured Benchmark database. The old catalog was proxied through `HSQLDB` -- this remains an option for DBMSes that may have incomplete catalog support. +- Built with and for Java ~~11~~ 17. +- Migration from Ant to Maven. + - Reorganized project to fit Maven structure. + - Removed static `lib` directory and dependencies. + - Updated required dependencies and removed unused or unwanted dependencies. + - Moved all non `.java` files to standard Maven `resources` directory. + - Shipped with [Maven Wrapper](https://maven.apache.org/wrapper). +- Improved packaging and versioning. + - Moved to Calendar Versioning (https://calver.org/). + - Project is now distributed as a `.tgz` or `.zip` with an executable `.jar`. + - All code updated to read `resources` from inside `.jar` instead of directory. +- Moved from direct dependence on Log4J to SLF4J. +- Reorganized and renamed many files for clarity and consistency. +- Applied countless fixes based on "Static Analysis". + - JDK migrations (boxing, un-boxing, etc.). + - Implemented `try-with-resources` for all `java.lang.AutoCloseable` instances. + - Removed calls to `printStackTrace()` or `System.out.println` in favor of proper logging. +- Reformatted code and cleaned up imports. +- Removed all calls to `assert`. +- Removed various forms of dead code and stale configurations. +- Removed calls to `commit()` during `Loader` operations. +- Refactored `Worker` and `Loader` usage of `Connection` objects and cleaned up transaction handling. +- Introduced [Dependabot](https://dependabot.com/) to keep Maven dependencies up to date. +- Simplified output flags by removing most of them, generally leaving the reporting functionality enabled by default. +- Provided an alternate `Catalog` that can be populated directly from the configured Benchmark database. The old catalog was proxied through `HSQLDB` -- this remains an option for DBMSes that may have incomplete catalog support. ## Citing This Repository diff --git a/config/README.md b/config/README.md new file mode 100644 index 000000000..439bcc79a --- /dev/null +++ b/config/README.md @@ -0,0 +1,69 @@ +# Config + +The config files are duplicated in a seperate folder for each of the supported database systems. + +For example, the postgres/sibench config file has the following pieces: + +## Connection Details + +The connection details allow for the configuration of the connection to the database via JDBC. + +```xml + + POSTGRES + org.postgresql.Driver + jdbc:postgresql://localhost:5432/benchbase?sslmode=disable&ApplicationName=sibench&reWriteBatchedInserts=true + admin + password + TRANSACTION_SERIALIZABLE + 128 +``` + +## Workload + +- `scalefactor` allows to upscale the workload by the specified factor +- `time` allows to modify the runtime of the workload. It is given in **seconds** +- `weights` define the weight of each [transaction Type](#procedures). The weights are defined as **percentages** + +```xml + + 1 + + + 1 + + + + unlimited + 50,50 + + +``` + +## Procedures + +Each workload specifies certain procedures which can be removed by deleting the `transactionType` from the config. By default, all transaction types of the workload are listed in an unmodified config file. + +```xml + + + + MinRecord + + + UpdateRecord + + + + +``` + +## Workload Specific Configs + +### Templated + +The templated workload demands a path to a file that holds the templated queries. + +```xml +data/templated/example.xml +```