Installing dbtrail EE

dbtrail-ee is the commercial dbtrail distribution: the full open-source core plus offline license validation and the enterprise features. This guide takes you from nothing to a running, licensed install.

There are two binaries:

Both accept every OSS command and flag unchanged; the enterprise pieces are additive and turn on from the license.

Already on the open-source core? Jump to Upgrading from the open-source core. Running the web UI is covered in Running the console.

Install a delivered binary

You received one or more release archives (from a signed download link) and a .lic license file.

1. Install the binaries

The CLI and the web console ship as separate archives. Extract the ones you need and put the binaries on your PATH:

tar xzf dbtrail-ee_<version>_linux_amd64.tar.gz          # dbtrail-ee (CLI)
tar xzf dbtrail-console-ee_<version>_linux_amd64.tar.gz  # dbtrail-console-ee (web console)
sudo install -m 0755 dbtrail-ee dbtrail-console-ee /usr/local/bin/
dbtrail-ee --version          # should print <version>+ee

The CLI archive alone covers capture / query / recover; the console archive is only needed for the web UI.

2. Install the license

The binary looks for the license in this order:

1. $DBTRAIL_LICENSE, an explicit path. It is authoritative: if the variable is set, dbtrail uses that file (or fails) and the search stops. It never falls through to the paths below, so a typo can't silently activate a different license.
2. /etc/dbtrail/license.lic, the standard system location;
3. ./dbtrail.lic, the working directory (a development convenience).

If $DBTRAIL_LICENSE is unset, the first readable, verifiable file among (2)–(3) wins. Licensing has the exact semantics.

sudo install -D -m 0644 acme.lic /etc/dbtrail/license.lic

3. Verify the license

dbtrail-ee license

It prints the customer, the status (valid / grace / expired / …), the features: line (what you can use), and the expiry / updates dates. The exit code is 0 when the license is enabled, 1 otherwise. Full field and status reference: Licensing.

4. Run it

dbtrail-ee needs a MySQL 8.0+ instance for the index: the same index store the OSS core uses (bundled or bring-your-own). It is a drop-in for the OSS bintrail, so the quickstart applies verbatim, for example capture + index in one daemon:

dbtrail-ee up \
  --source-dsn 'user:pass@tcp(db:3306)/' \
  --index-dsn  'user:pass@tcp(index:3306)/bintrail_index'

For the web console (with the Forensics view when licensed), see Running the console below.

Upgrading from the open-source core

Already running the open-source bintrail? Moving to dbtrail-ee is a binary swap, not a data migration. dbtrail-ee embeds the OSS core and uses the same index schema: there is no per-edition datastore, so your entire indexed history stays exactly where it is and is queryable and recoverable from the first second.

The move:

1. Install dbtrail-ee / dbtrail-console-ee alongside (or over) the OSS bintrail binaries (step 1).
2. Point them at your existing --index-dsn (and --source-dsn), unchanged. Swap bintrail → dbtrail-ee and bintrail-console → dbtrail-console-ee in your service unit. Running the OSS docker compose stack instead? Don't edit it at all: apply the Docker Compose override.
3. Drop in the license (step 2) and verify with dbtrail-ee license.

That is the whole upgrade: no export/import, no re-index, no data downtime. Without a license the EE binaries still run as the full OSS core, so you can swap the binary first and add the license later.

Two things worth knowing:

• Schema changes are forward-only and additive. If your index predates a newer core column (e.g. connection_id, query_text), the EE binary's schema check adds it on first run (idempotent), and historical rows simply carry NULL for the new column. Nothing is rewritten or lost.
• Enterprise features start capturing from now. They do not backfill. The clearest case is Forensics: its session-identity ledger (session_history, created automatically by the poller; pre-existing connection_cache snapshots are migrated into it and the old table is dropped) only records sessions seen while dbtrail-ee is running. Your historical events remain fully present, and who-changed still attributes them wherever a durable record covers them: an audit log, or the captured query_text. The live tiers (performance_schema and the connection-identity cache alike) only see sessions while they are connected, so they cannot reach back before the upgrade, but no history is lost, only that one form of attribution is forward-looking. See Forensics.

Rolling back is just as safe: point the OSS bintrail binaries back at the same index. The schema only ever grew, so the core reads it unchanged; the EE-only session_history table is simply an unused orphan.

Docker Compose

The OSS quickstart is docker compose up -d on the public core's docker-compose.yml. Every EE release publishes drop-in EE images for that stack:

Both are public on GHCR: no docker login needed. That is deliberate, not an oversight: without a license the EE images run as the plain OSS core, so the .lic file, not image access, is what gates the enterprise features (the same model Grafana Enterprise uses). Both are multi-arch (amd64 + arm64) and carry bintrail / bintrail-console compatibility symlinks, so every command the OSS compose stack itself runs (its command: blocks, the exec … user set-password snippets) works verbatim. Known exclusions: the EE CLI image does not ship bintrail-mcp (the EE MCP path is the console's /mcp endpoint) or bintrail-pg.

Upgrading a running OSS compose stack: the compose translation of the binary swap above. The OSS docker-compose.yml is never edited; instead you add an override file next to it. Save this as docker-compose.ee.yml:

services:

  # Reuses the console-ee image (already pulled for the main service);
  # the step only needs a shell + od, exactly like the OSS index-init.
  index-init:
    image: ghcr.io/nethalo/dbtrail-console-ee:${DBTRAIL_EE_TAG:-latest}

  # The watch daemon: stream + web console + control plane. The license is
  # mounted at the standard system path the binary probes
  # (/etc/dbtrail/license.lic). This is what turns on the Forensics view,
  # RBAC, and SSO when the license grants them.
  bintrail:
    image: ghcr.io/nethalo/dbtrail-console-ee:${DBTRAIL_EE_TAG:-latest}
    volumes:
      - ${DBTRAIL_LICENSE_FILE:-./dbtrail.lic}:/etc/dbtrail/license.lic:ro

  # Opt-in `flashback` profile: the time-travel SQL terminal. The EE CLI
  # image ships the `bintrail` symlink, so the OSS service command runs
  # unchanged. The license rides along so any licensed CLI surface (above
  # all the AUDIT sink) is active here too; otherwise `docker compose exec
  # shim ...` would be an unaudited hole.
  shim:
    image: ghcr.io/nethalo/dbtrail-ee:${DBTRAIL_EE_TAG:-latest}
    volumes:
      - ${DBTRAIL_LICENSE_FILE:-./dbtrail.lic}:/etc/dbtrail/license.lic:ro

  # Opt-in `baseline` profile: the dump→Parquet converter. The OSS
  # `command: ["baseline", ...]` appends to this image's dbtrail-ee
  # entrypoint. (baseline-dump stays on the upstream mydumper image.)
  baseline:
    image: ghcr.io/nethalo/dbtrail-ee:${DBTRAIL_EE_TAG:-latest}
    volumes:
      - ${DBTRAIL_LICENSE_FILE:-./dbtrail.lic}:/etc/dbtrail/license.lic:ro

Then:

cp acme.lic ./dbtrail.lic               # next to the compose files (MUST exist
                                        # before `up`: a missing bind source
                                        # becomes an empty directory and the
                                        # stack silently runs as plain OSS)
chmod 0644 ./dbtrail.lic                # the container user is uid 999, and an
                                        # unreadable license degrades just as
                                        # silently as a missing one
docker compose -f docker-compose.yml -f docker-compose.ee.yml pull
docker compose -f docker-compose.yml -f docker-compose.ee.yml up -d
docker compose exec bintrail dbtrail-console-ee license   # → status: valid

Same index volumes, same data, no export/import: identical guarantees to the binary upgrade, including the two forward-only notes there (additive schema, forensics captures from now). Pin a version with DBTRAIL_EE_TAG in .env; override the license path with DBTRAIL_LICENSE_FILE.

Rollback: run up -d again without the second -f: the stack recreates on the OSS images against the untouched index volumes.

Running the console

dbtrail-console-ee is the OSS bintrail-console with the licensed console features layered on. Two modes:

• serve: a read-only web UI over an existing index (events, recover, status, time-travel).
• watch: the live daemon that runs stream, console and control plane in one process ("+ Add server" in the UI starts monitoring a source).

# read-only over an existing index
dbtrail-console-ee serve --index-dsn '...' --listen 127.0.0.1:8090

# full daemon: capture + console + control plane
dbtrail-console-ee watch --index-dsn '...' --console-listen 127.0.0.1:8090

Authentication (inherited from the OSS console, console docs): a loopback first run prompts you to set a password; a non-loopback bind requires a credential: a --token, a configured password, or --allow-setup (the intended path for a container bound to 0.0.0.0 behind a proxy). Without one it refuses to start. dbtrail-console-ee license prints the same license status as the CLI and honors the same exit-code contract (0 when enterprise features are enabled, 1 otherwise), so dbtrail-console-ee license || alert works from cron even where the CLI binary isn't installed.

The enterprise pieces appear only when the license grants them:

• Forensics view (forensics): the "who changed this?" tab in the browser, plus the connection-identity poller that runs under watch and the control-plane monitor to populate the attribution cache. See Forensics.
• SSO (sso): an OIDC "Continue with …" login, configured via DBTRAIL_SSO_* environment variables. Unlicensed, the button never appears and the console uses built-in token/password auth.
• RBAC (rbac), per-user roles and data profiles enforced server-side in the console: a multi-user local store (dbtrail-console-ee user add …) and SSO claim→role mapping (DBTRAIL_SSO_ROLE_*). Unlicensed, the console behaves exactly like the OSS build. See RBAC.

Where to go next

• Licensing: the license lifecycle (grace, updates window, schema compatibility, renewals).
• Enterprise features: what each feature gates and how activation works.
• Forensics · Audit trail · RBAC: the feature guides.
• The quickstart and the OSS install guide: the core mechanics dbtrail-ee inherits.