CentralDatabase

CentralDatabase is a lightweight asynchronous SQL execution framework for Paper / Bukkit plugins.

It provides a safe, thread-aware API for database operations using HikariCP connection pooling and structured query results — ensuring that database work never blocks the main server thread.

Designed for plugin developers building scalable Minecraft plugin ecosystems.

---

Features

• Async-first SQL execution
• No main-thread blocking
• HikariCP connection pooling
• Structured query result objects
• Typed row access helpers
• Clear error classification
• Execution time tracking

---

Supported Query Types

| Operation | Method | |-----------|--------| | SELECT | selectAsync() | | INSERT | insertAsync() | | UPDATE | updateAsync() | | DELETE | deleteAsync() |

All queries return a CompletableFuture containing a result object.

---

Example SQL table:

CREATE TABLE players (
    player_uuid CHAR(36) PRIMARY KEY,
    username VARCHAR(16),
    coins INT,
    created_at TIMESTAMP
);

Example SELECT Query

queryRunner.selectAsync(
"SELECT player_uuid, username, coins FROM players WHERE coins > ?",
100
).thenAccept(result -> {

    if (result.isSuccess()) {

        for (Row row : result.rows()) {

            UUID uuid = row.asUUID("player_uuid");
            String username = row.asString("username");
            Integer coins = row.asInt("coins");

            System.out.println(username + " has " + coins + " coins");
        }

    } else {
        System.out.println("Query failed: " + result.code());
    }

});

Example INSERT Query

queryRunner.insertAsync(
    "INSERT INTO players (player_uuid, username, coins) VALUES (?, ?, ?)",
    playerUUID,
    username,
    0
);

Example UPDATE Query

queryRunner.updateAsync(
"UPDATE players SET coins = coins + ? WHERE player_uuid = ?",
50,
playerUUID
);

Example DELETE Query

queryRunner.deleteAsync(
    "DELETE FROM players WHERE player_uuid = ?",
    playerUUID
);

Accessing Row Data

The Row class provides safe typed accessors.

Row row = result.firstRow();

UUID uuid = row.asUUID("player_uuid");
String name = row.asString("username");
Integer coins = row.asInt("coins");

Initialization

Example setup inside a plugin:

DatabaseConfigLoader loader = DatabaseConfigLoader.fromPlugin(this);

QueryRunner runner = new QueryRunner(loader);

runner.configureHikari();
runner.initializeHikari();
runner.initializeThreadPool();

Shutdown

Always shut down the query runner during plugin disable.

---

Philosophy

CentralDatabase is designed to be:

• simple
• predictable
• safe
• It avoids heavy ORM layers and instead focuses on fast, asynchronous SQL execution with a minimal API.

---

Dependency

CentralDatabase is distributed via JitPack.

Maven

Add the JitPack repository:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

Add the dependency:

<dependency>
    <groupId>com.github.devspexx</groupId>
    <artifactId>CentralDatabase</artifactId>
    <version>844216ff97</version> - latest build
</dependency>

Gradle Add the repository:

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.devspexx:CentralDatabase:VERSION'
}