Connect a database

What you need

• The database server's address and port (default 1433).
• The name of the database to read.
• A read-only username and password. If you don't have one yet, see below.
• The IANA time zone the database server itself runs in (for example America/New_York) — not necessarily the agent machine's own time zone.

Generating a read-only login

During guided setup, leaving the username blank offers to write a setup script for your DBA instead. The same thing, typed directly:

nia-agent sql readonly --login nia_agent --databases <your-database-name> --out nia-readonly-setup.sql

Use a comma-separated list for --databases if the agent will read more than one database on the same server. This writes a script for your DBA to review and run themselves — the agent never runs it. It creates one login with a placeholder password the DBA replaces, grants it read access to the listed database(s) plus the ability to see table and column definitions, and grants no write access of any kind — enforced automatically. Safe to run more than once.

Optional flags:

• --schema <name> — restrict to one schema instead of the whole database.
• --with-cancel-visibility true — one additional, still read-only, permission letting the agent confirm a stopped query actually stopped. Off by default.

Adding the connection

Through the guided setup (nia-agent setup), this is asked as a sequence of questions. Typed directly:

nia-agent connection add \
  --id <short-id> --label "<friendly name>" \
  --host <database-server-host> --port <port> --database <database-name> \
  --user nia_agent --password <the-password> \
  --source-timezone <IANA time zone, e.g. America/New_York>

The password is encrypted immediately and never stored in plain text. If your database only accepts unencrypted connections on your local network, add --encrypt false. Only use --allow-legacy-tls true if your DBA has confirmed the server cannot negotiate a modern TLS version.

Confirm it works: nia-agent connection test <short-id>. A failure here is almost always a network, host/port, or credentials problem.

Adding more databases later

Run nia-agent setup again and choose "add another database" from its menu, or run nia-agent connection add again by hand with a different --id.