Database

Universe keeps two kinds of state. Live instance state, which instance is ONLINE, on which Wrapper, on which port, lives in Hazelcast distributed maps and is rebuilt as the cluster runs. Durable state that must survive a full cluster restart, such as API keys, lives in a relational database described by ./database.json. The file is generated on first run with the bundled backend, so a default install already has a working database with nothing to provision.

What persists where

State	Store	Why
Running instances (InstanceInfo)	Hazelcast IMap	Shared live across members; reconciled by the cluster, not the DB.
Instance configurations	Files in ./configuration/ + Hazelcast map	Authored on disk, loaded into the cluster at startup.
API keys (api_keys table)	Database	Must outlive any single node and a full restart.

database.json

database.json sits in the same working directory as the JAR and is read at startup. The provider field selects the backend; the remaining fields are connection details, and any field a given provider does not use is ignored.

Field	Type	Default	Description
provider	string	h2	Backend selector: h2, mysql, postgres, mongodb, redis.
url	string	universe.db	H2 only. Database filename, created under ./data/.
host	string	localhost	Server hostname for networked backends.
port	int	3306	Server port. Override per backend (PostgreSQL defaults to 5432).
database	string	universe	Schema or database name on the server.
username	string	sa	Connection user.
password	string	""	Connection password.

Backends

H2, the default

H2 is an embedded, file-based store bundled in the core JAR. It runs in MySQL-compatible mode and needs no external server: the database is a file under ./data/ named by url. This is the right choice for a single-machine deployment or a first run.

{
	"provider": "h2",
	"url": "universe.db",
	"host": "localhost",
	"port": 3306,
	"database": "universe",
	"username": "sa",
	"password": ""
}

MySQL, built in

MySQL support ships in the core JAR through the bundled MariaDB driver. Point host and port at your server and supply credentials. Use this when more than one node needs the same durable records and you already run MySQL.

{
	"provider": "mysql",
	"host": "db.example.com",
	"port": 3306,
	"database": "universe",
	"username": "universe",
	"password": "changeme"
}

PostgreSQL, MongoDB, and Redis via extensions

PostgreSQL, MongoDB, and Redis are not in the core JAR. Drop the matching database extension into ./extensions/, then set provider to postgres, mongodb, or redis. The extension registers the backend at load time, so it must be present before startup.

{
	"provider": "postgres",
	"host": "db.example.com",
	"port": 5432,
	"database": "universe",
	"username": "universe",
	"password": "changeme"
}

When you need more than H2

Stay on the bundled H2 backend unless one of these applies:

• Several Masters or tools must read the same durable records and you want one shared store rather than a file per node.
• You already operate a managed MySQL or PostgreSQL instance and prefer your existing backups and access controls.
• An extension you run expects a specific backend (for example a Redis-backed cache or a MongoDB document store).

Related