VanillaCore is a single node, multi-threaded relational database engine that partially supports the SQL-92 standard and offers connectivity via JDBC, embedding, or (Java-based) stored procedures.
You will need the following tools to compile and run this project:
- Java Development Kit 1.7 (or newer)
- Maven
This tutorial will teach you how to start up a database server and interact with it.
This project is a maven project. You can compile the source and package the classes to a jar file via a single command using Maven:
(Note that this command also triggers testing phase, which will run all test cases in this project. You can skip testing phase using the next command.)
> mvn package
Running the test cases may take very long time (about 3 minutes in our case). If you want to skip the testing phase, use the this command instead:
> mvn package -Dmaven.test.skip=true
The jar file will be named as core-0.6.0.jar and in the target folder of the project.
To start up a VanillaCore server, use the following command:
(Please replace {DB Name} with your database name, which will be the name of the folder of your database files)
> java -classpath core-0.6.0.jar org.vanilladb.core.server.StartUp {DB Name}
If it works correctly, you should see database server ready like this:
Aug 09, 2016 3:27:55 PM org.vanilladb.core.server.StartUp main
INFO: database server ready
After starting up, VanillaCore creates a directory named as {DB Name} for the databases under your home directory (which is C:/Users/{Your Username} in Windows, /home/{Your Username} in Mac or most Linux distribution).
Let’s try to connect to your database server.
The server provides a JDBC interface, which you can connect to with any JDBC client. Or, you can use our simple interpreter to send the SQL commands to the server.
To start up a SQL interpreter, use the following command:
> java -classpath core-0.6.0.jar org.vanilladb.core.util.ConsoleSQLInterpreter
Now you should see a console prompt like:
SQL> _
After you enter the SQL console, you may start to give some SQL commands for interaction with the server. VanillaCore supports basic commands defined in SQL-92 standard. To see what exactly commands you can use, please check out VanillaDB SQL document.
VanillaCore provides some configurable settings. These settings can be found in properties file vanilladb.properties which located in src\main\resources\org\vanilladb\core. After you compile and package the classes using Maven, the properties file will be copied to target\properties\org\vanilladb\core. When a VanillaCore server starts up, it will search the properties file in properties\org\vanilladb\core under the same directory. Therefore, if you want to adjust the settings after packaging the classes, you have to modify the one in the target\properties\org\vanilladb\core.
We assume that the jar file and the properties files are always in the same directory. If they are not, VanillaCore will use the default values for all settings.
You can also put the properties file at other location. To make VanillaCore know where the file is, you need to specify the path as an argument of the JVM while starting up a server:
> java -Dorg.vanilladb.core.config.file={path to vanilladb.properties} -classpath core-0.6.0.jar org.vanilladb.core.server.StartUp {DB Name}
Remember to replace {path to vanilladb.properties} to the path of the file.
First, find an editor to open properties file vanilladb.properties. Each line in the file is a key-value pair for a configuration. To modify a configuration, just update the value behind =.
Here are some commonly used configurations:
VanillaCore stores records in files. To adjust the size of physical blocks used by the database (default: 4096 bytes):
org.vanilladb.core.storage.file.Page.BLOCK_SIZE=4096
To adjust the location of the database files (default: the home directory of the current user):
org.vanilladb.core.storage.file.FileMgr.DB_FILES_DIR=
To adjust the number of the buffers which cache the blocks of the files in the memory (default: 1024):
org.vanilladb.core.storage.buffer.BufferMgr.BUFFER_POOL_SIZE=1024
To enable the periodically checkpointing (default: true):
org.vanilladb.core.server.VanillaDb.DO_CHECKPOINT=true
You can find more available configurations and corresponding descriptions in vanilladb.properties.
Please checkout our VanillaDB SQL document.
We have a series of educational slides to make the people who are not familiar with database internal architecture understand how a database works. Here is the outline of the our slides:
- Background
- Why relational database systems? ER- and relational-models, transactions and logical schema design and normal forms, etc.
- Architecture overview and interfaces
- Client-server interfaces, embedding, storage interfaces, etc.
- Query engine
- Server, threads and JDBC
- Threads v.s. connections v.s. transactions, thread-local v.s. thread-safe components, etc.
- Query Processing
- SQL parsing and validation, planning, algebra, plan/scan trees, etc.
- Server, threads and JDBC
- Storage
- Data access and file management
- Block-level v.s. file-level access, O_DIRECT on Linux, etc.
- Memory management
- Buffering user data, write-ahead-logging (WAL), log caching, etc.
- Record and metadata management
- Physical schema design, efficient buffer utilization, etc.
- Data access and file management
- Transaction management
- Concurrency
- Strict Two-Phase Locking (S2PL), deadlock detection/avoidance, lock granularity, phantom, isolation levels, etc.
- Recovery
- Physical logging, transaction rollback, UNDO-only recovery, UNDO-REDO recovery, logical logging, physiological logging, ARIES, checkpointing, etc.
- Concurrency
- Efficient query processing
- Indexing
- Hash and B-tree indexing, index locking, etc.
- Materialization and sorting (TBA)
- Effective buffer utilization (TBA)
- Query optimization (TBA)
- Indexing
<dependency>
<groupId>org.vanilladb</groupId>
<artifactId>core</artifactId>
<version>0.6.0</version>
</dependency>To contribute to VanillaCore, please see CONTRIBUTING.
If you have any question, you can either open an issue here or contact vanilladb@datalab.cs.nthu.edu.tw directly.
Copyright 2016-2022 vanilladb.org contributors
Licensed under the Apache License 2.0