docs /extensions /databases

Database extensions

Database extensions register a DatabaseProvider under a provider key, replacing the built-in H2 and MySQL backends. PostgreSQL, MongoDB, and Redis each ship as a separate JAR and are selected through ./database.json.

Universe ships with two built-in database providers, H2 and MySQL. Three more are available as extensions: PostgreSQL, MongoDB, and Redis. Each registers a DatabaseProvider under its provider key during onLoad(). To switch backends, drop the matching JAR into ./extensions/ and set the provider key in ./database.json.

warning

Switching database backends does not migrate existing data. Universe starts with an empty database under the new provider, so export or re-create anything you need before changing the provider key.

Provider configuration

extension-db-postgres is a production-grade relational backend suited to multi-node clusters with concurrent writes. It uses jOOQ with the PostgreSQL dialect for SQL.

{
	"provider": "postgres",
	"host": "127.0.0.1",
	"port": 5432,
	"database": "universe",
	"username": "universe",
	"password": "changeme"
}

Field	Description
provider	Must be `"postgres"`.
host	Server hostname or IP.
port	Default `5432`.
database	Database name.
username	Database user.
password	Database password.

extension-db-mongodb is a document-oriented backend with BSON storage and schema flexibility. It supports both authenticated (SCRAM) and unauthenticated connections.

{
	"provider": "mongodb",
	"host": "127.0.0.1",
	"port": 27017,
	"database": "universe",
	"username": "",
	"password": ""
}

Field	Description
provider	Must be `"mongodb"`.
host	Server hostname or IP.
port	Default `27017`.
database	Database name.
username	SCRAM user. Leave empty for an unauthenticated connection.
password	User password. Leave empty for an unauthenticated connection.

extension-db-redis is an in-memory store for sub-millisecond lookups and ephemeral data. It uses the Lettuce client for non-blocking, reactive operations.

{
	"provider": "redis",
	"host": "127.0.0.1",
	"port": 6379,
	"username": "",
	"password": ""
}

Field	Description
provider	Must be `"redis"`.
host	Server hostname or IP.
port	Default `6379`.
username	ACL username for Redis 6+ (optional).
password	AUTH password (optional).
database	Ignored by the Redis provider.

Choosing a backend

PostgreSQL for clusters that need durable, concurrent relational writes. The default choice for production.
MongoDB when you prefer document storage and want to avoid managing a schema.
Redis for fast, ephemeral lookups where persistence guarantees matter less.

Extensions overview

How a provider JAR is discovered and registered at startup.

Database

The built-in H2 and MySQL providers and the database.json schema.

Building extensions

Implement DatabaseProvider for a backend not listed here.