Background Accounts

Background accounts (added in v2.12.0) decide which ClickHouse account CH-UI uses when work runs with nobody in the loop: scheduled queries, model runs, pipeline sinks, governance sync, Cluster Health sampling, telemetry monitors, the performance regression monitor, weekly operations reports, SQL alerts and scheduled report delivery.

Before v2.12.0 every one of these borrowed the credentials of whichever person happened to be signed in to the connection. That meant jobs stopped when everyone signed out, and a job ran with the grants of a random human. Background accounts let an administrator give each worker its own ClickHouse user, keep the old behavior on purpose, or turn background execution off.

Configuring accounts is part of the community edition and needs the admin role. It does not unlock any licensed feature: a Pro worker such as governance or Cluster Health still needs a Pro license to run.

Modes

Each connection has one setting per worker. The modes are:

Mode	In the UI	What happens
service_account	Dedicated ClickHouse account	The worker signs in with a username and password you saved. Runs keep going after everyone signs out.
session	An active user session	The worker borrows the credentials of a signed-in session on the connection (the newest of up to 3 active sessions whose password decrypts; governance keeps the same user between runs, see below). Someone has to stay signed in.
disabled	Disabled	The worker gets no credentials, so background runs stop. It never borrows a session.

session is the default for every worker, so an upgrade keeps the old behavior until an administrator changes it. Choosing session or disabled deletes any saved account for that worker.

Workers

Worker	UI label	Grants to give the account
schedule	Scheduled queries	Only the operations the scheduled SQL needs
model	Models	SELECT on model sources; CREATE, INSERT, ALTER and DROP as needed on model targets
pipeline	Pipeline sink	INSERT on pipeline targets; CREATE TABLE only if the sink creates its destination
governance	Governance	Access to the system tables governance reads and the metadata you want collected
cluster_health	Cluster Health	SELECT on the system tables Cluster Health uses
telemetry.monitor	Telemetry monitors	SELECT on the configured logs and traces tables
performance	Performance regression monitor	SELECT on system.query_log
operations.report	Weekly operations reports	SELECT on system.query_log, system.parts and system.clusters
sql_alert	SQL threshold alerts	SELECT on the tables your SQL alerts read. Every run uses readonly=1
report	Scheduled report delivery	SELECT on the tables the reported saved queries and dashboard panels read. Every run uses readonly=1

The performance regression monitor, weekly operations reports, SQL alerts and scheduled reports refuse session mode. They only run unattended with a dedicated account, and the UI does not offer the session option for them. See Performance, Operations Reports, SQL alerts and Scheduled reports.

Configure an account

1. Create a ClickHouse user for the worker with only the grants in the table above.
2. Go to Admin → Connections and click Background accounts on the connection.
3. Pick the worker, choose Dedicated ClickHouse account under Run using, and enter the username and password.
4. Click Verify and save.

Saving verifies the account by running SELECT 1 through the connection with a 10 second timeout. The connection has to be online, otherwise the save is refused with 503 Connection must be online to verify this account. If verification fails, the previous setting stays in place.

SELECT 1 only proves the account can sign in. It does not prove the worker’s grants, so run a representative job after saving.

The password is encrypted with APP_SECRET_KEY before it is stored and is never returned by the API, not even in encrypted form. Enter it again every time you save. An empty password field saves an empty password on purpose.

A new or rotated account is picked up on the next run, with no restart. Work that already holds credentials finishes with them: a model run keeps its credentials for the whole run, and pipelines fetch credentials per batch.

API

Both routes need the admin role.

Method	Path	Purpose
GET	/api/connections/{id}/background-credentials	List every worker’s mode and username
PUT	/api/connections/{id}/background-credentials/{worker}	Set one worker’s mode

{ "mode": "service_account", "username": "chui_schedules", "password": "..." }

For session and disabled, send only { "mode": "session" } or { "mode": "disabled" }.

No silent fallback

• A disabled worker does not run in the background, and it does not fall back to a session.
• If a saved password cannot be decrypted (for example after APP_SECRET_KEY changed), the worker fails closed. It does not borrow someone else’s session.
• In session mode with nobody signed in, the worker has no credentials. Scheduled runs are recorded as errors. The other workers skip that run and say why: governance shows the reason as its sync error, SQL alerts and telemetry monitors show Not evaluated with the reason, and Cluster Health logs a warning. Each is logged once per change, not on every tick.
• Governance results depend on what the account can read, so in session mode governance keeps borrowing the ClickHouse user of its previous run while that user has a live session. Otherwise it picks admin sessions first, then by user name, instead of the newest session.
• A job never borrows a per-person SSO user: that account belongs to one person. In session mode such sessions are skipped, so on a connection where everyone signs in with per-person SSO, a worker needs a dedicated account to run. Shared SSO service accounts and password sessions can be borrowed.

Manual runs

Clicking a run button is not background work, so most manual runs use your own session:

• Schedules: Run now uses the caller’s ClickHouse account and still works when the schedule worker is disabled. It is only offered for schedules on the connection you are signed in to, so your password never goes to another connection’s server.
• Telemetry monitors: Run now uses your own credentials, also when disabled.
• SQL alerts: Test run and Run now use your own credentials, also when the sql_alert worker is disabled or not set up.
• Governance: a manual sync uses your session.
• Weekly operations reports: generating a report on demand uses your session.
• Scheduled reports: the exception. Send now and Preview run with the report account, never your session, so what you preview is exactly what recipients get. Without a dedicated report account both fail.
• Models: manual runs use the model worker’s setting. If the model worker is disabled, manual model runs are blocked too.

Shared jobs and delegation

Caution

CH-UI is a shared workspace. The admin and analyst roles apply to the whole instance, not to one connection. Anyone with those roles who can create or edit a schedule, model, pipeline, telemetry monitor or SQL alert can make it run with the configured background account’s grants, including jobs on other connections. The same holds for scheduled reports, which also send the result to the recipients the author picks. Picking a connection is not a tenant boundary. Do not give a background account broader grants than every admin and analyst should be able to use.

Viewers cannot create, edit, delete or run schedules, models, pipelines, telemetry monitors, SQL alerts or scheduled reports.

Audit trail

These events show up in the Audit Log:

Action	When
connection.background_account.updated	An admin saved a setting. Records the admin (SSO subject when present), the worker, the mode and the account name.
<worker>.credential_use	A worker picked up its dedicated account. At most once per worker and connection per hour, and again right after a rotation.
<worker>.credential_borrow	A worker in session mode borrowed a session. Records the session id, at most once per worker and connection per hour.

These record that credentials were acquired, not that the SQL succeeded. Check the job’s own results for that.

Revoking access

Choosing Disabled stops future runs but does not cancel work that already has credentials. For immediate revocation, also revoke the ClickHouse user’s grants or password and kill its running queries with your usual ClickHouse procedures.

Troubleshooting

If a worker stops, check in order: the connection is online, the worker’s mode, that APP_SECRET_KEY has not changed, and the account’s ClickHouse grants. The server’s debug logs record each credential use and every lookup failure.

Pointing a connection at a different ClickHouse server switches its dedicated accounts to Disabled and erases the saved user and password, since they belong to the old server. Set them up again for the new one. This covers a direct connection’s URL and, from v2.33.0, an agent that now reaches a different server. See Repointing a direct connection and Repointing an agent.

Restore and rollback

Test restores on an isolated host, not on production: stop the server, restore a consistent backup made with ch-ui backup, start it with the original APP_SECRET_KEY, then check that both session mode jobs and dedicated-account jobs run. Saved account passwords only decrypt with the key they were saved with. Database migrations run on every start and are safe to repeat, so restarting a restored database is fine. See Deployment for the backup itself.

v2.11.1 and older do not read these settings. An old binary goes back to borrowing sessions for every worker, even ones you set to Disabled. To roll back, stop the server, then restore the pre-upgrade database and configuration together with the old binary. Do not rely on a v2.12.0 Disabled setting to protect an older binary.