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 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 Debugmodes

• 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).
• Thanks to antirez for linenoise (BSD license, See on Github).
• Thanks to nlohmann and further contributors for nlohmann_json (MIT license, See on GitHub).