Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/universeclouddev/Universe/llms.txt

Use this file to discover all available pages before exploring further.

Universe persists API keys and other cluster state in a relational or document store selected through ./database.json. The file must sit in the same working directory as the JAR. All built-in providers use jOOQ for type-safe SQL without code generation, and H2 runs in MySQL compatibility mode so the same schema DDL works across both built-in providers.

​
Configuration File

Create or edit ./database.json: 
{
  "provider": "h2",
  "url": "universe.db",
  "host": "localhost",
  "port": 3306,
  "database": "universe",
  "username": "sa",
  "password": ""
}
All fields are present regardless of the active provider. Fields that do not apply to the chosen provider are silently ignored — the file acts as a self-documenting reference.

​
Field Reference

FieldTypeDefaultDescription
providerstring"h2"Database provider key. Built-ins: h2, mysql. Extension-provided: postgres, mongodb, redis.
urlstring"universe.db"H2 only. Database file name. The file is created under ./data/.
hoststring"localhost"MySQL / extension providers. Database server hostname.
portinteger3306MySQL / extension providers. Database server port.
databasestring"universe"MySQL / extension providers. Schema or database name to connect to.
usernamestring"sa"Database username.
passwordstring""Database password.

​
Provider Reference

H2 is an embedded, file-based database that requires zero external infrastructure. It is the default provider and the best choice for single-node or development setups.
{
  "provider": "h2",
  "url": "universe.db",
  "host": "localhost",
  "port": 3306,
  "database": "universe",
  "username": "sa",
  "password": ""
}
The database file is created at ./data/universe.db relative to the working directory. H2 operates in MySQL compatibility mode (MODE=MySQL) so schema migrations written for MySQL will work without modification.
No additional JAR or service is required. H2 is bundled with Universe.

​
SQL Schema

On startup Universe automatically creates the api_keys table if it does not already exist: 
CREATE TABLE IF NOT EXISTS api_keys (
    key_id     VARCHAR(64)  PRIMARY KEY,
    token      VARCHAR(256) NOT NULL UNIQUE,
    permission VARCHAR(16)  NOT NULL
);
This table is the only schema managed by the core. Extensions may create their own tables through the same DatabaseProvider connection.

​
Custom Providers via Extensions

You can register a custom database backend by implementing the DatabaseProvider interface from extensions/extension-api and dropping the JAR in ./extensions/.
1

Implement DatabaseProvider

Create a class that implements DatabaseProvider with the connection and CRUD logic for your backend.
2

Implement Extension and register

In your Extension.onLoad(), obtain the injected DatabaseRegistry and register your provider under a unique key:
class MongoExtension @Inject constructor(
    private val registry: DatabaseRegistry
) : Extension {
    override fun id() = "mongodb"
    override fun version() = "1.0.0"

    override fun onLoad() {
        registry.register("mongodb", MongoDatabaseProvider(config))
    }

    override fun onUnload() {}
    override fun onReload() {}
}
3

Set provider key in database.json

Set the provider field to the key you registered:
{
  "provider": "mongodb",
  "host": "db.example.com",
  "port": 27017,
  "database": "universe",
  "username": "universe",
  "password": "changeme"
}
Avoid depending on the :app module from any extension. Use only :api and :extensions:extension-api and register your provider through the injected registry in onLoad().

Build docs developers (and LLMs) love

Get started for freeTalk to us