Skip to content

Docs: README update to help new users #370

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Docs: README update to help new users #370

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3c3607d
Update README.md
ETHenzlere Oct 1, 2023
5739de6
Merge branch 'cmu-db:main' into docs/documentation-update
ETHenzlere Oct 3, 2023
44fac74
Split Prerequisites into two sections
ETHenzlere Oct 3, 2023
f6a9465
Merge branch 'main' into docs/documentation-update
bpkroth Oct 9, 2023
1605b46
Merge branch 'main' into docs/documentation-update
apavlo Oct 19, 2023
5da6c30
PR comments + Formatting
ETHenzlere Oct 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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,
Expand Down Expand Up @@ -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
<username>admin</username>
<password>password</password>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO, these are the obvious ones and somewhat self explanatory.

We should probably have additional docs on what the other fields in those configs do and how to adjust them.

For instance, it's possible to run on a select set of queries, or multiple workload phases with a single config, but that isn't super obviously documented IMO.

Copy link
Contributor Author

@ETHenzlere ETHenzlere Oct 3, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can see that they look obvious to experienced users but they are needed for a quick-start of benchbase so I'd like to keep them here if possible :)

Do you think it would be beneficial to add a new .README file to the config folder and explain the advanced things there? - Or move everything related to config there and add a quick navigation link to the new .README file in the github README?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My point about those two parameters being obvious is that they're self explanatory once you know where to look, but the part about where the configs are may not be.

I would suggest that the Getting Started text get rewritten as something slightly more high-level like "adjusting the connection details in the config file" which includes basic commentary about both the JDBC URL and the credentials.

A separate ConfigDetails.md might be warranted that the main README.md links to for additional details, especially with external links to JDBC driver details.

I don't think the entire ConfigDetails.md is necessary for you to write here, but if you could start a stub of it with the above, then I think one of the benchbase experts can take up the rest from there.

Make sense?

```

### How to Enable Logging

To enable logging, e.g., for the PostgreSQL JDBC driver, add the following JVM property when starting...
Expand Down