Database Installation

Install GQLDB on a Linux or macOS host by downloading the distribution, placing the license file, and starting the database service. The distribution is delivered as a native executable for the target platform, there is no container runtime required and no separate service stack to install.

System Requirements

Witness nodes in HA mode have far smaller resource needs (~50 MB RSS, tens of MB to a few GB disk depending on write rate), see Deployment Topologies for the full sizing matrix.

Quick Install (Community Edition)

The install script downloads the latest GQLDB Community server for your platform and installs it as the ultipa-gqldb command:

Bash
curl -fsSL https://download.ultipa.com/gqldb/install.sh | sh

After the script completes, verify the command is on your PATH:

Bash
ultipa-gqldb -version

On macOS the executable is flagged by Gatekeeper on first download; if the command above fails with a quarantine error, clear the attribute:

Bash
xattr -d com.apple.quarantine "$(command -v ultipa-gqldb)" 2>/dev/null

This installs the Community Edition of GQLDB, intended for evaluation, learning, and non-commercial use. For commercial deployments, obtain the appropriate licensed distribution from your Ultipa account team. See Commercial Install below.

Commercial Install

For production / commercial deployments, the licensed GQLDB distribution is delivered through your Ultipa account team rather than the public install script. Contact your account team to obtain:

• The signed GQLDB server distribution for your platform.
• The commercial license file matching your purchased capacity (database cap, HA membership, supported nodes).
• Any feature-specific entitlements your contract includes.

Once you have the distribution, the install steps are the same as Manual Install below.

License

A license file is optional. The database starts and runs without one, it falls back to the Free Tier limits below. To unlock higher capacity or HA, place a license file alongside the server executable (or anywhere readable) and pass its path with -license-file.

When you start without -license-file, you'll see a warning in the startup log:

Log
[license] WARN: no license file specified — running with free-tier limits (3 graphs, 2 cores). Use WithLicenseFile() to enable a paid license.

This is informational, not an error; the database is running. If you intend to stay on the Free Tier, you can ignore the warning.

NOTE

Edition vs Tier: the edition (Community vs Commercial) is the distribution you obtained; the tier (Free vs Paid) is the runtime mode, determined by whether -license-file points at a valid signed license. A Commercial distribution launched without a license still runs at Free Tier limits; a Community distribution given a valid license file runs at the licensed limits.

First Boot

The minimal launch command. The executable name depends on how you installed.

1. Community Edition: the script installs ultipa-gqldb as a command, so invoke it directly:

Bash
ultipa-gqldb -db ./my.gdb -rbac -admin-pass <strong-password> -port 60123

2. Direct Download / Commercial Distribution: the executable arrives with a versioned name (ultipa-gqldb-<version>-<platform>); launch it from its directory:

Bash
./ultipa-gqldb-1.x.y-linux-amd64 \
  -db ./my.gdb \
  -rbac \
  -admin-pass <strong-password> \
  -port 60123 \
  -license-file ./your.license

Both examples include -rbac (along with -admin-pass) so the database boots with authentication enabled. Without -rbac, the database starts with no auth and -admin-pass is silently ignored — fine for a throwaway local sandbox, not for anything else.

The -admin-pass value only takes effect on the first boot of a -db directory — that's when the admin user is created. On every later restart of the same -db, the persisted password is what's checked at login, so you don't have to pass -admin-pass again (and if you do, the value is ignored). Change the password through ALTER USER while logged in, or use -reset-admin-pass for offline recovery if you've forgotten it.

So a restart of an already-initialized -db is typically simpler — drop -admin-pass entirely:

Bash
ultipa-gqldb -db ./my.gdb -rbac -port 60123

The remaining examples in this page use ultipa-gqldb; substitute the versioned form if your install delivers one.

Important Flags

See All Flags

The list above covers the flags most operators need to know. For the complete set — including timeouts, log rotation, RBAC TTLs, compaction tuning, gRPC reflection, plugin loading, MCP mode, and any build-specific options — run:

Bash
ultipa-gqldb -help

For production, foreground it under your service manager (systemd, launchd, supervisord). For ad-hoc local testing, run it under nohup:

Bash
nohup ultipa-gqldb \
  -db ./my.gdb -admin-pass admin11 -port 60123 \
  -license-file ./your.license -rbac \
  > gqldb.log 2>&1 &

The > gqldb.log 2>&1 is shell redirection (not -log-file). It captures everything the process writes — stderr logs, stdout banners, panic traces — into a single flat file. Convenient for tail -f on a local sandbox. For production, prefer -log-file <dir> so the server's structured logs land in rotated files (governed by -log-max-size / -log-max-files), and let the service manager handle stderr/stdout separately.

Verifying the Install

Connect with the CLI or any driver and run:

GQL
RETURN db.version()

If the call returns a version string, the install is functional. To confirm the license:

GQL
RETURN db.license()

If db.license() returns "not configured" or similar, the -license-file flag wasn't picked up.

Stopping the Database

Send SIGTERM to the process. Under nohup / shell-launched setups, the simplest approach is:

Bash
pkill -f ultipa-gqldb

Under a service manager, use the service-manager's stop command (e.g., systemctl stop gqldb). The database flushes outstanding writes and exits cleanly on SIGTERM. SIGKILL is only safe in HA mode where another replica holds the durable state — on a single-node install, SIGKILL can lose the last SyncAsync window (typically ~100 ms of writes; see Backup & Restore for durability options).

Updating

The update procedure differs between editions:

1. Community Edition: re-run the install script. It's idempotent and pulls the latest Community release:

Bash
curl -fsSL https://download.ultipa.com/gqldb/install.sh | sh

2. Commercial Edition: obtain the new distribution from your account team and replace the existing executable in place.

In both cases: stop the running database, replace the server executable, and restart with the same flags. Storage and on-disk format are backward-compatible across minor versions; major-version upgrades occasionally require a lazy migration.

For HA clusters, perform rolling upgrades. Update followers one at a time, then step down the leader. See Deployment Topologies.

Where Things Live on Disk

Inside -db <path>:

The .gdb directory is the entire authoritative state. Backing it up offline (with the process stopped or after a FLUSH) is a valid disaster-recovery strategy alongside db.backup() — see Backup & Restore.