DataProvider

Build plugins and services, not database plumbing.

DataProvider is shared infrastructure for plugin developers on Velocity and Bukkit/Paper.
It gives you one clean API for MySQL, MongoDB, Redis, and Redis messaging so your plugin code can stay focused on gameplay and business logic.

Why Use DataProvider?

• Faster development: stop rewriting connection, pooling, and lifecycle code in every plugin.
• Consistent developer experience: same registration and access flow across multiple backends.
• Safer multi-plugin setup: caller-scoped access rules prevent cross-plugin misuse.
• Cleaner codebase: typed APIs reduce casting and repetitive boilerplate.
• Better runtime behavior: connection reuse and lifecycle cleanup are handled centrally.

Features

• Following data backends are implemented: MYSQL, MONGODB, REDIS, REDIS_MESSAGING
• Platform support: Velocity + Bukkit/Paper
• Optional Hibernate ORM support for relational workflows (nl.hauntedmc.dataprovider.api.orm.ORMContext)

Requirements

• Java 25
• The currently pinned Paper and Velocity runtime builds (see the root pom.xml)
• MySQL, MongoDB, and/or Redis for the backends you enable

Quick Start

Resolve the API from your platform runtime:

Velocity:

DataProviderAPI api = proxyServer.getPluginManager()
        .getPlugin("dataprovider")
        .flatMap(container -> container.getInstance()
                .filter(DataProviderApiSupplier.class::isInstance)
                .map(DataProviderApiSupplier.class::cast)
                .map(DataProviderApiSupplier::dataProviderApi))
        .orElseThrow(() -> new IllegalStateException("DataProvider is unavailable."))
        .forPlugin(this); // bind once during this plugin's initialization

Bukkit/Paper:

RegisteredServiceProvider<DataProviderAPI> registration =
        Bukkit.getServicesManager().getRegistration(DataProviderAPI.class);
if (registration == null) {
    return;
}
DataProviderAPI api = registration.getProvider().forPlugin(this); // bind once during onEnable

RelationalDatabaseProvider mysql = (RelationalDatabaseProvider) api.registerDatabaseOrThrow(
        DatabaseType.MYSQL, "default"
);

api.unregisterDatabase(DatabaseType.MYSQL, "default");

If you maintain multiple plugins, this gives your team one standard integration model instead of backend-specific code per project.

Admin Commands

• /dataprovider help shows command usage.
• /dataprovider status [summary|connections] [unhealthy] [plugin <name>] [type <databaseType>] shows local state plus cached remote health and its age; it never blocks on remote checks.
• /dataprovider config prints current runtime config state (orm.schema_mode + backend enablement).
• /dataprovider reload validates and atomically reloads config.yml plus every databases/*.yml file.

Permissions:

• dataprovider.command.status
• dataprovider.command.config
• dataprovider.command.reload

Install DataProvider (Server)

1. Build or download the bundled platform jar for your server: dataprovider-platform-paper-*-bundled.jar or dataprovider-platform-velocity-*-bundled.jar.
2. Put it in your server plugins/ directory.
3. Start once to generate default configuration.
4. Configure plugins/DataProvider/config.yml and plugins/DataProvider/databases/*.yml.

Add It to Your Plugin Project

Use the API artifact in plugins that consume DataProvider. Platform bundles provide it at runtime.

• dataprovider-api: public integration contracts, including the ORM context contract and factory; use this for all consumers.
• dataprovider-core: internal registry, configuration, storage-driver, and ORM implementation details.
• dataprovider-platform-paper / dataprovider-platform-velocity: server plugin distributions.

Repository:

• https://maven.pkg.github.com/HauntedMC/DataProvider

Maven:

<repository>
  <id>github</id>
  <url>https://maven.pkg.github.com/HauntedMC/DataProvider</url>
</repository>

<dependency>
  <groupId>nl.hauntedmc.dataprovider</groupId>
  <artifactId>dataprovider-api</artifactId>
  <version>3.0.9</version>
  <scope>provided</scope>
</dependency>

Gradle (Groovy):

compileOnly "nl.hauntedmc.dataprovider:dataprovider-api:3.0.9"

GitHub Packages authentication details are in the docs.

Build

./mvnw -q -DskipTests compile
./mvnw -q test
./mvnw -B -ntp -Pintegration-tests verify
./mvnw -B -ntp -Pplatform-acceptance verify

The Maven Wrapper pins the build-tool version. The platform-acceptance command requires Docker and boots the bundled Paper and Velocity jars against MySQL, MongoDB, Redis, and Redis messaging. See Testing and CI for the full test matrix and diagnostics.

Build outputs:

• dataprovider-platform-paper/target/dataprovider-platform-paper-*-bundled.jar
• dataprovider-platform-velocity/target/dataprovider-platform-velocity-*-bundled.jar

Repository Layout

• dataprovider-api: stable, platform-neutral contracts, data-access types, and ORM integration surface.
• dataprovider-core: registry, configuration, storage drivers, and ORM implementation.
• dataprovider-platform-common: shared lifecycle, command, and logging adapters.
• dataprovider-platform-paper / dataprovider-platform-velocity: thin platform bootstraps and distributable bundles.

Documentation

• Documentation index
• Architecture
• Usage guide
• Configuration
• Development
• Testing and CI
• Release process
• Examples

Community and Governance

• Contributing
• Code of Conduct
• Security Policy
• Support

License

This project is licensed under the GNU Affero General Public License v3.0.