Install & run modes

1. Prerequisites
2. Build from source
3. Connecting to the lakehouse
4. Run modes
   1. 1. Embedded (single binary)
   2. 2. serve — a Node
   3. 3. gateway — the public Engine API
   4. 4. control-plane — the registry
5. Health & metrics
6. Next

---

Prerequisites

• Rust (stable) — the toolchain is pinned via mise.
• Docker + Compose — for the dependency stack (object storage + Iceberg catalog).
• A source of truth: an Iceberg REST catalog (e.g. Apache Polaris) + S3-compatible object storage. The Compose stack provides MinIO + Polaris locally.

For the fastest path that needs none of the build steps below, jump to Getting started (just stack).

Build from source

mise install            # install the pinned Rust toolchain
just setup              # add rustfmt + clippy
just build              # build the workspace (release: cargo build --release -p growlerdb-cli)
just check              # fmt + clippy + tests (the CI gate)

The single binary is growlerdb (target/release/growlerdb). One binary, four long-running roles selected by subcommand, plus the offline index/maintenance commands.

growlerdb --help

Connecting to the lakehouse

Every mode reads its Iceberg/object-store connection from the environment (defaults target the local Compose stack). See Configuration for the full list.

export GROWLERDB_CATALOG_URI=http://localhost:8181/api/catalog
export GROWLERDB_WAREHOUSE=growlerdb
export GROWLERDB_S3_ENDPOINT=http://localhost:9000
export GROWLERDB_CATALOG_CREDENTIAL='root:s3cr3t'
export GROWLERDB_S3_ACCESS_KEY=minioadmin
export GROWLERDB_S3_SECRET_KEY=minioadmin

Run modes

1. Embedded (single binary)

Index a table, then search it — no servers. Best for laptops, CI, demos, small corpora.

# Build the index from a source table (auto-maps the schema; --name defaults to the last segment).
growlerdb index growlerdb.docs --name docs

# Search it; --hydrate also fetches the authoritative rows from Iceberg.
growlerdb search docs 'title:iceberg' --limit 10 --hydrate

Maintenance commands operate on a local index:

Command	What it does
growlerdb sync <index>	Append fast-path: index files added since the last checkpoint.
growlerdb reconcile <index>	Compare against Iceberg’s current snapshot; fix drift.
growlerdb rebuild <index>	Hard reset: drop and rebuild from Iceberg (the backstop).
growlerdb backup <index>	Back up the shard (segments + locator/checkpoint + definition) to object storage.
growlerdb restore <index>	Restore the shard from a backup, or rebuild from Iceberg if none exists.
growlerdb refresh-replica <index>	Pull the latest sealed segments from the primary’s backup (incremental) for a read replica.

backup/restore read object-store credentials from GROWLERDB_S3_* and the bucket from GROWLERDB_BACKUP_BUCKET (see Configuration). After a restore the connector resumes the tail from the backed-up checkpoint (exactly-once).

2. serve — a Node

Host an already-built index over gRPC (Write + Search + Lookup + Suggest + Admin + System), and optionally the REST API + console. Register with a control plane so it’s cluster-visible.

growlerdb serve docs \
  --addr 0.0.0.0:50051 \
  --rest-addr 0.0.0.0:8080 \
  --metrics-addr 0.0.0.0:9102 \
  --register http://controlplane:50071 \
  --advertise-addr http://node:50051

3. gateway — the public Engine API

Terminate the Engine API (gRPC + REST) and route to one or more nodes. This is the address clients hit; it also serves the console UI and (optionally) the index-management, metrics, and OpenSearch surfaces.

growlerdb gateway \
  --node-addr http://node:50051 \
  --addr 0.0.0.0:50061 \
  --rest-addr 0.0.0.0:8080 \
  --metrics-addr 0.0.0.0:9103 \
  --control-plane http://controlplane:50071 \
  --prometheus http://lgtm:9090 \
  --ui-dir /usr/share/growlerdb/ui \
  --opensearch

Front a sharded cluster instead of a single node with --registry <registry.json> --index <name>. Enable authentication with --oidc-issuer <url> --oidc-audience <aud> (the gateway is open without it — see Configuration → Auth).

4. control-plane — the registry

The cluster-wide index registry (create / drop / list / ingestion status) over gRPC.

growlerdb control-plane --addr 0.0.0.0:50071 --metrics-addr 0.0.0.0:9101

Health & metrics

Any long-running mode given --metrics-addr exposes /healthz, /readyz, and Prometheus /metrics on that port. Use them for liveness/readiness gating.

curl -f localhost:9103/readyz

Next

• Configuration — flags, env, and the index-definition YAML.
• Reference — the query language and REST/gRPC API.
• Deployment — Compose and Kubernetes (Helm).