beedb/README.md

112 lines
4.7 KiB
Markdown
Raw Normal View History

2022-04-04 20:25:01 +02:00
![BeeDB](logo.png)
BeeDB is a software project that teaches students the architecture and implementation of DataBase Management Systems.
This project is related to the Basic Module *Architecture & Implementation of DBMS*. The course is usually teached every summer term, see [dbis page of TU Dortmund](http://dbis.cs.tu-dortmund.de/cms/en/teaching/index.html) for more information.
**Attention: Please do not publish and share your solution with other students!**
## Dependencies
* `git`
* `cmake` (at least version `3.9`)
* `build-essential`
* `bison` and `flex`
## How to build
### Option (a): Build into current folder:
* `cmake .`
* `make`
### Option (b): Build into separate `build` folder:
* `mkdir build && cd build`
* `cmake ..`
* `make`
### Switch between `Release` and `Debug`modes
* Default build is in `Debug` mode.
* If you want to build in `Release` mode use:
* `cmake . -DCMAKE_BUILD_TYPE=Release`
* **or** set `CMAKE_BUILD_TYPE` in `CMakeLists.txt`.
## How to use
BeeDB uses a client/server model where the executable `beedb` starts the server and `beedb_client` runs a client.
### Server
Usage: beedb [options] db-file
Positional arguments:
db-file File the database is stored in. Default: bee.db
Optional arguments:
-h --help show this help message and exit
-p --port Port of the server
-l --load Load SQL file into database.
-q --query Execute Query.
-cmd --custom_command Execute custom command and exit right after.
-k --keep Keep server running after executing query, command or loading a file.
-c --client Start an additional client next to the server
--buffer-manager-frames Number of frames within the frame buffer.
--scan-page-limit Number of pages the SCAN operator can pin at a time.
--enable-index-scan Enable index scan and use whenever possible.
--enable-hash-join Enable hash join and use whenever possible.
--enable-predicate-push-down Enable predicate push down and use whenever possible.
--stats Print all execution statistics
### Client
Usage: beedb_client [options] host
Positional arguments:
host Name or IP of the beedb server
Optional arguments:
-h --help show this help message and exit
-p --port Port of the server
### Please note!
Just stopping the server by killing (or `Ctrl-C`) crashes the server; you may loose (unflushed) data.
To stop the server clean, use `:stop` command by a client.
## Configuration
Some configuration outside the console arguments is stored in the file `beedb.ini`.
* The number of pages stored as frames in the buffer manager (`buffer manager.frames`)
* The replacement strategy of frames in the buffer manager (`buffer manager.strategy`)
* The `k` parameter for `LRU-K` replacement strategy (`buffer manager.k`)
* The number of how many pages can be pinned by a scan at a time (`scan.page-limit`)
* Enable or disable usage of index scan (`optimizer.enable-index-scan`)
* Enable or disable usage of hash join (`optimizer.enable-hash-join`)
* Enable or disable predicate push down (`optimizer.enable-predicate-push-down`)
## Non-SQL Commands
Despite SQL commands, you can use the following special commands from the client.
* `:explain <query>`: prints the query plan, either as a table or a graph (a list of nodes and edges)
* `:get <option-name>`: prints either all or the secified option of the database configuration
* `:set <option-name> <numerical-value>`: changes the specified option. Only numerical values are valid
* `:show [tables,indices,columns]`: A quick way to show available tables, their columns or indices
* `:stop`: Stops the server (and flushes all data to the disk).
## Examples
##### Import and SQL file (containing `CREATE` and `INSERT`)
`./beedb -l movies.sql`
##### Run a single query and terminate
`./beedb -q "SELECT * FROM movie;"`
##### Run a query and open console afterwards
`./beedb -q "SELECT * FROM movie;" -c`
##### Start the BeeDB server only (connect clients later)
`./beedb`
##### Start the BeeDB server and open a client console
`./beedb -c`
#### Start a BeeDB client (you can start multiple ones)
`./beedb_client`
# For developers
* If you want to commit to the repository please `make git-hook` before commit.
# Credits
* Thanks to **p-ranav** for `argparse` (MIT license, [See on GitHub](https://github.com/p-ranav/argparse)).
* Thanks to **antirez** for `linenoise` (BSD license, [See on Github](https://github.com/antirez/linenoise)).
* Thanks to **nlohmann** and further contributors for `nlohmann_json` (MIT license, [See on GitHub](https://github.com/nlohmann/json)).