Skip to content
An easy to use library for flat-file databases.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
gradle/wrapper 1.0.0 Mar 21, 2019
src Add isNumeric check Apr 8, 2019
LICENSE Initial commit Mar 16, 2019
build.gradle 1.0.0 Mar 21, 2019
gradlew Intial commit Mar 16, 2019
gradlew.bat Intial commit Mar 16, 2019
settings.gradle Intial commit Mar 16, 2019


An easy to use library for flat-file databases.


  • Create tables using Java classes.
  • Auto-update tables when new fields are added in the Java class.
  • Easily connect to your database file.


Java 8+


FlatDB comes with H2 Driver. You can exclude it in your build tool if you wish to use a different driver.

Getting Started

Add FlatDB as dependency.


repositories {
  maven { url '' }
dependencies {
  compile 'com.github.cyr1en:flatdb:LATEST_VERSION'



Using FlatDB

Creating a Table

Let's first create a table that we will pass down to the DatabaseBuilder.

@Table(nameOverride = "table")
public class TestTable {
  @Column(autoIncrement = true) int id;
  @Column(primaryKey = true) UUID uuid;
  @Column String name;
  @Column String lastName;

The class above will get translated to:

id uuid name lastname

Connecting to Database

Now let's configure our connection to the database using the DatabaseBuilder class. Here, we're setting the path in which the database is located. If the database file doesn't exist, it will be generated. We're also setting the prefix of the tables to be "test_". Lastly, we now add the table that we created above.

DatabaseBuilder builder = new DatabaseBuilder()
        .setPath(System.getProperty("user.dir") + "/testDb/flatDB")
try {
  Database db =;
} catch (SQLException e) {

After that, it's pretty much a generic JDBC experience. Except the Database#executeQuery() function returns an Optional.

To do a query

Optional<ResutlSet> result = db.executeQuery("SELECT * FROM 'test_table' WHERE name = 'someName'");
result.ifPresent(rs -> System.out.println("Hey I'm present"));

Additional Configurations

Defining Custom Type Maps.

FlatDB automatically converts the data types of a field into an SQL type equivalent. However, by default, FlatDB doesn't have all the data types mapped. To solve this, we can define our own type conversions in the TypeMap class where we need to provide a java class, and an SQLTypePair(Types.SOME_TYPE, "default value").

Using DatabaseBuilder
DatabaseBuilder builder = new DatabaseBuilder();
builder.addCustomType(UUID.class, SQLTypePair.of(Types.VARCHAR, "null"));
Using TypeMap
//The last parameter indicates if we should override the definition for UUID.class
TypeMap.addCustomType(UUID.class, SQLTypePair.of(Types.VARCHAR, "null"), true);

To see more examples: Click here

Process Tables in Runtime

In cases where new classes are loaded in runtime, and additional tables need to be processed. The TableProcessor class allows us to do so.

Database database; //assuming database is already initialized.
TableProcessor tableProcessor = new TableProcessor(database);


DBTablePrinter by hturon is embedded in FlatDB to allow users to easily print their ResultSets. See DBTablePrinter in this project.

You can’t perform that action at this time.