Upgrade from 1.x - GenesisDB Documentation

GenesisDB 2 is the open source successor of the 1.x releases and a drop-in replacement for GenesisDB 1.1.6 and earlier. Start it on an existing data directory and it migrates that directory, feed it a 1.x backup and it restores it, keep your existing clients and they keep working.

The migration is one-way: 1.x cannot open a migrated directory.

A backup is mandatory. As with every migration, a backup before upgrading is not a recommendation but a requirement. Stop 1.x and copy the complete data directory before GenesisDB 2 starts on it for the first time. Without that copy there is no way back to 1.x.

Steps

Stop the 1.x process and copy the complete data directory. This backup is mandatory, it is the only way back if anything goes wrong.
Set GENESISDB_AUTH_TOKEN to a value of at least 32 bytes (openssl rand -hex 32). This is the only required configuration change.
Set GENESISDB_HOST=0.0.0.0 if clients connect from other hosts. GenesisDB 2 binds to loopback by default. The container image already sets this.
Start GenesisDB 2 with the same GENESISDB_DATA_DIR. The first start migrates the directory and logs what it did.

What the first start migrates

Every step is crash safe and resumable. An interrupted start finishes the migration on the next start.

Pending write-ahead log. A batch that 1.x wrote to its WAL but not yet to the event log is replayed first.
Event logs. events/*.eventstore become events/*.gdb. Records are copied byte for byte and verified by checksum. Event IDs, timestamps and hashes do not change, and the audit passes on migrated data.
Indexes. Rebuilt from the event logs. The time is proportional to the store size.
Schemas. Moved into the 2.0 schema layout. Keywords outside the validated subset are dropped, so a migrated schema accepts and rejects exactly what 1.x did.

To migrate offline instead, run genesisdb convert --data-dir <dir> against the stopped directory. Add --dry-run to see the plan first. The backup is mandatory here as well.

Clients

The API of 1.x stays available unchanged under /api/v1. It answers with the same status, content type and body as 1.1.6, so existing clients keep working. Every v1 response carries Deprecation: true and a Link to its successor in /api/v2. New functionality is only added to /api/v2.

API v1 (1.x)	Successor in API v2
`GET /api/v1/status/ping`	`GET /api/v2/ping`
`GET /api/v1/status`	`GET /api/v2/status`
`GET /api/v1/status/audit`	`GET /api/v2/admin/audit`
`POST /api/v1/commit`	`POST /api/v2/commit`
`POST /api/v1/stream`	`POST /api/v2/fetch`
`POST /api/v1/observe`	`POST /api/v2/subscribe`
`POST /api/v1/q`, `POST /api/v1/query`	`POST /api/v2/query`
`GET /api/v1/subjects`	`GET /api/v2/subjects`
`GET /api/v1/types`	`GET /api/v2/types`
`GET /api/v1/schema/get`	`GET /api/v2/schemas`
`POST /api/v1/schema/register`	`POST /api/v2/schemas`
`GET /api/v1/backup/create`	`GET /api/v2/admin/backup`
`POST /api/v1/backup/restore`	`POST /api/v2/admin/restore`
`POST /api/v1/erase`	`POST /api/v2/admin/erase`
`POST /api/v1/index`	`POST /api/v2/admin/index`

The names of API v2 do not exist under /api/v1, and the names of API v1 do not exist under /api/v2. GET /api/v1/eventtypes and POST /api/v1/import of 1.x were removed, use GET /api/v1/types and POST /api/v1/backup/restore.

You can upgrade the server first and the clients later. The 2.0.0 SDKs use the new routes and are not meant for a 1.x server.

What changed

GENESISDB_AUTH_TOKEN must have at least 32 bytes. Optional GENESISDB_READ_TOKEN and GENESISDB_WRITE_TOKEN add read-only and read-write roles.
The binary binds to 127.0.0.1 unless GENESISDB_HOST says otherwise.
GDBQL compares typed and exactly: 1 and "1" are different values, large integers keep their digits. AND binds stronger than OR.
Reads return events in commit order, independent of event timestamps.
Erase replaces whole reference payloads with {}.
gRPC and license keys are gone. GENESISDB_GRPC_ENABLED, GENESISDB_GRPC_PORT and GENESISDB_LICENSE are ignored with a warning.