Need help with vanillacore?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

125 Stars 21 Forks Apache License 2.0 181 Commits 8 Opened issues


The core engine of VanillaDB

Services available


Need anything else?

Contributors list


Build Status Apache 2.0 License Maven Central

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.

Required Tools

You will need the following tools to compile and run this project:

  • Java Development Kit 1.7 (or newer)
  • Maven

Getting Started

This tutorial will teach you how to start up a database server and interact with it.

Compiling the source and package them to a jar

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

and in the
folder of the project.

Starting up a VanillaCore server

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.4.1.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).

Using SQL Interpreter

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.4.1.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.

System Configurations

VanillaCore provides some configurable settings. These settings can be found in properties file
which located in
. After you compile and package the classes using Maven, the properties file will be copied to
. When a VanillaCore server starts up, it will search the properties file in
under the same directory. Therefore, if you want to adjust the settings after packaging the classes, you have to modify the one in the

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} -classpath core-0.4.1.jar org.vanilladb.core.server.StartUp {DB Name}

Remember to replace

{path to}
to the path of the file.

Modifying Configurations

First, find an editor to open properties file
. Each line in the file is a key-value pair for a configuration. To modify a configuration, just update the value behind

Commonly Used Configurations

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):

To adjust the location of the database files (default: the home directory of the current user):

To adjust the number of the buffers which cache the blocks of the files in the memory (default: 1024):

To enable the periodically checkpointing (default: true):


You can find more available configurations and corresponding descriptions in

Supported Syntax

Please checkout our VanillaDB SQL document.

Architecture Tutorials

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.
  • Storage
  • 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.
  • Efficient query processing
    • Indexing
      • Hash and B-tree indexing, index locking, etc.
    • Materialization and sorting (TBA)
    • Effective buffer utilization (TBA)
    • Query optimization (TBA)

Linking via Maven



To contribute to VanillaCore, please see CONTRIBUTING.

Contact Information

If you have any question, you can either open an issue here or contact [email protected] directly.


Copyright 2016-2020 contributors

Licensed under the Apache License 2.0

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.