Onboard a tenant

This page walks an administrator through the complete golden path: from signing in to the admin console through handing a BI user a ready-to-paste connection string. Each playbook covers the console steps, the equivalent qod CLI command, and how to confirm success.

Sign in

Goal: Open the admin console and authenticate in the correct realm.

Prerequisites:

• The manager is running and reachable at http://<host>:20900.
• You have either superuser credentials (a qodstate_user row with tenant IS NULL) or tenant-scoped credentials.

Steps (UI):

1. Open http://<host>:20900/ui/ in a browser.
2. Enter your username and password.
3. Leave Tenant ID blank to log in as a system superuser. Fill it in (for example, acme) to log in as a tenant-scoped user.
4. Click Sign in.

CLI equivalent:

qod login --url http://localhost:20900 --username admin

qod login prompts for the password (never a command-line flag), mints a session, and stores it in the active profile - every subsequent qod command reuses it. CI scripts can set QOD_API_KEY instead of logging in.

Verify: The top-right pill shows the signed-in user and their role. In no-auth dev mode the pill reads anonymous / no-auth.

Related:

• Admin UI guide - Signing in section
• Authentication

---

Create a tenant

Goal: Register a new isolated tenant namespace in the control plane.

Prerequisites:

• Signed in as a system superuser.

Steps (UI):

1. Open the tenant switcher at the top of the sidebar and choose New tenant (or Manage tenants..., then + New tenant).
2. Enter a Display name (for example, Acme Corporation). A Tenant ID is suggested from it; edit it if needed (for example, acme). The tenant ID is the routing slug used in connection strings and in admin UI URLs.
3. Pick the tenant's auth provider (db needs no extra config).
4. Click Create.

The form does not have a dedicated screenshot; it is a dialog on the tenant list page (/ui/tenants).

Manifest (YAML)

This is a fragment of the full config manifest; see Manage by manifest to assemble and apply it.

tenants:
  - name: acme
    displayName: Acme Corporation

CLI equivalent:

qod tenant create acme

Metastore settings (database name, schema) are configured per tenant-db, not on the tenant itself - see Add a database below.

Verify: The new tenant appears in the tenant list and in the sidebar's tenant switcher immediately after creation.

Related:

• Tenants and databases
• Tenancy model

---

Add a database

Goal: Attach a database (tenant-db) to the tenant so pools have a catalog to connect to.

Prerequisites:

• The tenant exists (see Create a tenant).
• Signed in as a superuser or as the tenant's admin.
• For ducklake kind (the default): the Postgres metastore is reachable and dataPath points to writable object storage.

Steps (UI):

1. Pick the tenant in the sidebar's tenant switcher.
2. Open Tenant > Databases in the sidebar.
3. Click New database.
4. Fill in:
   • Name - a short identifier for this database (for example, main).
   • Kind - ducklake is the default for production multi-node persistence; duckdb-file for a local file; memory for federation-only workloads.
   • Data path - the object-store URI (for ducklake) or file path (for duckdb-file); leave blank for memory.
   • Default schema - the schema presented to clients when none is specified.
5. Click Create.

Manifest (YAML)

tenants:
  - name: acme
    tenantDbs:
      - name: fed
        kind: memory
        defaultDatabase: fedpg
        defaultSchema: public

CLI equivalent:

The example below creates an in-memory database. Replace --kind memory with --kind ducklake (the default) and supply --data-path for a production tenant-db.

qod database create --tenant acme --name fed --kind memory \
  --default-database fedpg --default-schema public

Verify: The database appears on the Databases page with its kind and default schema displayed.

Related:

• Tenants and databases
• Catalogs

---

Create and size a pool

Goal: Spin up a pool of Quack nodes bound to a database so clients can connect.

Prerequisites:

• The tenant and at least one database exist.
• Signed in as a superuser or the tenant's admin.

Steps (UI):

1. Pick the tenant in the sidebar's tenant switcher.
2. Open Tenant > Pools in the sidebar.
3. Click New pool.
4. Fill in:
   • Pool name - a short identifier (for example, bi).
   • Database - select the database this pool should serve.
   • Role distribution - set the counts for Write-only, Read-only, and Dual nodes. The total becomes the pool size.
   • Create disabled (optional) - check this to register the pool without immediately spawning nodes.
5. Click Create.

Manifest (YAML)

tenants:
  - name: acme
    pools:
      - name: bi
        tenantDb: acme_tpch
        roleDistribution: { writeonly: 1, readonly: 1, dual: 1 }

CLI equivalent:

# Create a pool (1 WriteOnly + 1 ReadOnly + 1 Dual = 3 nodes)
qod pool create --tenant acme --db acme_tpch --pool bi --size 3 \
  --writeonly 1 --readonly 1 --dual 1

Verify: The pool row appears on the Pools page and the node count starts incrementing as nodes come up. You can watch the progress on the Dashboard.

Related:

• Pools and cohorts
• Routing

---

Confirm nodes are live

Goal: Verify that every expected node is healthy and accepting traffic before handing off the connection string.

Prerequisites:

• The pool was created and nodes have had time to initialize (usually a few seconds on a local deployment).

Steps (UI):

1. Click Dashboard in the sidebar, with the tenant picked in the tenant switcher (or All tenants).
2. Locate the pool's rows in the node table.
3. Check that each node shows healthy = true and that the in-flight and total-served counters are updating.

CLI equivalent:

# Live node table (used by the UI)
qod --json pool list | jq -r '.pools[].nodes[] |
  "\(.nodeId) role=\(.role) healthy=\(.healthy) served=\(.totalServed) p50=\(.p50Ms) p95=\(.p95Ms) p99=\(.p99Ms)"'

Verify: The number of healthy rows for the pool matches the role distribution you configured (write-only + read-only + dual = total size).

Related:

• Observability
• Resilience and draining

---

Hand off a connection string

Goal: Give the BI user or developer a ready-to-paste connection string for their tool.

Prerequisites:

• The pool is live and at least one node is healthy (see Confirm nodes are live).
• The end user has credentials for the tenant (see Access control for how to create user accounts and grants).

Steps (UI):

1. Pick the tenant in the sidebar's tenant switcher.
2. Open Tenant > Pools, then click the pool name to open its detail page.
3. Click the Connections tab.
4. Copy the JDBC, ODBC, or ADBC connection string that matches the client tool.

CLI equivalent: There is no CLI equivalent for this step. The Connections tab is a UI convenience that assembles the string from the pool's host, port, tenant, and pool name. The underlying parameters are available from qod --json pool list.

Verify: The BI user connects successfully. For client-specific setup steps, see the client guides listed below.

Related:

• Connecting clients
• Power BI
• Tableau