--- title: Tiger CLI reference | Tiger Data Docs description: Command reference for Tiger CLI, including every command, configuration parameter, and global flag for managing Tiger Cloud --- Tiger CLI is a command-line interface that you use to manage Tiger Cloud resources including VPCs, services, read replicas, and related infrastructure. Tiger CLI calls Tiger REST API to communicate with Tiger Cloud. To install CLI, configure authentication, and create your first service, see [Get started with Tiger CLI](/docs/get-started/quickstart/tiger-cli/index.md). This page is the reference for every CLI command and configuration parameter. For an overview of Tiger CLI and Tiger MCP, see [Tiger CLI and Tiger MCP](/docs/learn/tiger-cli-mcp/index.md). Tiger CLI (which bundles Tiger MCP) is open source. [File an issue in the repo](https://github.com/timescale/tiger-cli/issues/new) to report bugs or request features and help shape the product. Use the following commands to manage Tiger Cloud from the terminal. Every command supports `-h` for inline help, for example `tiger service create -h`. For the single-command version of common operations, see [common tasks](/docs/build/tiger-cli-mcp/common-tasks/index.md); for longer, multi-step workflows, see the [cookbook](/docs/build/tiger-cli-mcp/cookbook/index.md). Many commands have shorter aliases, listed with each command below. Command names, aliases, and flag names are case-insensitive, so `tiger SERVICE LIST --OUTPUT json` does the same thing as `tiger service list --output json`. Shorthand flags such as `-o`, and flag values such as `json`, remain case-sensitive. ## Authentication ### `tiger auth login` Create an authenticated connection to your Tiger Cloud account. By default, this opens a browser on the same machine to authorize. On a machine without a browser, pass `--headless` to authorize with a device code instead. For non-interactive login, pass credentials as flags. **Usage**: `tiger auth login [flags]` Terminal window ``` tiger auth login ``` You see something like: ``` Auth URL is: https://console.cloud.tigerdata.com/oauth/authorize?... Opening browser for authentication... Select a project: > 1. () 2. () Use ↑/↓ arrows or number keys to navigate, enter to select, q to quit ``` The project picker only appears if you have multiple projects and you did not pass `--project-id`. After you select one (or automatically, if you have only one): ``` Logged in to project Next steps: • Install the MCP server for your AI coding tool: tiger mcp install • List existing services: tiger service list • Create a new service: tiger service create • Protect services from writes: tiger config set read_only prod (or all, off) ``` The first time you log in interactively, Tiger CLI also asks `Which services should be protected from writes?` and stores your choice in the [`read_only` configuration option](#configuration-options). The question is asked once; to change the mode later, use `tiger config set read_only `. | Flag | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------- | | `--headless` | Authorize with a device code entered in a browser on any machine, instead of waiting for a redirect back to this one. | | `--project-id` | project to log in to. Skips the interactive picker. | | `--public-key` | Public key for non-interactive login. | | `--secret-key` | Secret key for non-interactive login. | The browser login redirects back to a `localhost` port on the machine running CLI, so it only works when the browser and CLI are on the same machine; opening the auth URL from another machine does not complete the login. When CLI runs somewhere without a browser, such as an SSH session, a container, or a remote development environment, pass `--headless` to use the device code flow instead: Terminal window ``` tiger auth login --headless ``` You see something like: ``` To authenticate, visit: https://console.cloud.tigerdata.com/activate and enter code: K7QP3XVR Waiting for authorization (this can take a few seconds after you enter the code)... ``` Open the URL in a browser on any machine, enter the code, and authorize Tiger CLI; the command then continues exactly like the browser login. You don't have to remember the flag: if the browser cannot be opened, `tiger auth login` falls back to the device code flow automatically. You can also set the `TIGER_PUBLIC_KEY` and `TIGER_SECRET_KEY` environment variables; the project is auto-detected from your credentials. See [Authentication parameters](#authentication-parameters) and [Client credentials](/docs/integrate/find-connection-details#create-client-credentials/index.md) for how to create a public/secret key pair. Pass `--project-id` to choose the project up front instead of picking it from the list. With a browser login, this skips the picker; with client credentials, the command fails if the project does not match the one your keys belong to. To change project after logging in, use [`tiger project use`](#tiger-project-use). Unless you log back in to the same project as last time, the default service (`service_id`) is cleared, because it belongs to the project you set it in. If that value came from `--service-id` or `TIGER_SERVICE_ID` rather than your config file, Tiger CLI warns you instead of clearing it. ### `tiger auth logout` Remove the credentials used to connect to Tiger Cloud. **Usage**: `tiger auth logout` Terminal window ``` tiger auth logout ``` You see: ``` Logged out and removed stored credentials ``` To sign a CLI login out remotely, for example on a machine you no longer control, revoke its session in [Tiger Console](/docs/deploy/tiger-cloud/tiger-cloud-aws/security/overview#active-sessions/index.md) instead. ### `tiger auth status` Show your current authentication status. What it lists depends on how you logged in: an OAuth login shows the authentication method and the user, and a client-credentials login shows the credential name, public key, project, and plan type. Alias: `whoami`. **Usage**: `tiger auth status [flags]` Terminal window ``` tiger auth status ``` You see something like: ``` ┌─────────────┬───────────────────────┐ │ PROPERTY │ VALUE │ ├─────────────┼───────────────────────┤ │ Status │ Logged in │ │ Auth Method │ OAuth │ │ User │ () │ └─────────────┴───────────────────────┘ ``` | Flag | Description | | -------------- | ------------------------------------------ | | `--output, -o` | Output format: `json`, `yaml`, or `table`. | ## Projects ### `tiger project list` List the projects you have access to. The active project, the one later commands act on, is marked in the `CURRENT` column. Alias: `ls`. **Usage**: `tiger project list [flags]` Terminal window ``` tiger project list ``` You see something like: ``` ┌──────────────┬─────────────────────────────────┬─────────┐ │ PROJECT ID │ NAME │ CURRENT │ ├──────────────┼─────────────────────────────────┼─────────┤ │ │ Tiger Project │ * │ │ │ YourCompany (Company wide) │ │ └──────────────┴─────────────────────────────────┴─────────┘ ``` To switch to another project, use [`tiger project use`](#tiger-project-use). | Flag | Description | | -------------- | ------------------------------------------ | | `--output, -o` | Output format: `json`, `yaml`, or `table`. | ### `tiger project use` Change the project that later commands act on. Alias: `switch`. **Usage**: `tiger project use ` Terminal window ``` tiger project use ``` You see: ``` Switched to project ``` If a default service was set, it is cleared first, because it belongs to the project you set it in. The message comes before the line above: ``` Cleared default service (config key service_id): it belonged to the previous project Switched to project ``` The `service_id` config key is always cleared. If `--service-id` or `TIGER_SERVICE_ID` is also set, that value takes precedence over the config key, so it survives the switch and still points at a service in the project you just left. Tiger CLI warns you rather than silently leaving it in place: ``` Warning: the default service from --service-id/TIGER_SERVICE_ID belongs to the previous project and is still in effect ``` If you name the project you are already on, nothing changes: ``` Already using project ``` If you name a project you cannot reach, the command exits with code `3`: ``` Project is not among your accessible projects Error: no access to the requested project ``` Switching requires a browser login, because a public/secret key pair belongs to a single project. With client credentials the command exits with code `4` instead. If your keys are stored: ``` Error: an API key is scoped to a single project. Run 'tiger auth login' without --public-key/--secret-key ``` If they come from the environment: ``` Error: cannot switch projects while TIGER_PUBLIC_KEY/TIGER_SECRET_KEY are set: an API key is scoped to a single project ``` To find the ID of the project you want, run [`tiger project list`](#tiger-project-list), look it up in [Tiger Console](/docs/integrate/find-connection-details#find-your-project-and-service-id/index.md), or read it out of any service's connection string. ## Version ### `tiger version` Show the installed Tiger CLI version. **Usage**: `tiger version [flags]` Terminal window ``` tiger version ``` You see something like: ``` ┌───────────────────┬──────────────────────────────────────────┐ │ Tiger CLI Version │ 0.27.0 │ │ Build Time │ 2026-10-27T14:54:58Z │ │ Git Commit │ 6109880bcd60650c76295f870a595bcf29b5545b │ │ Go Version │ go1.27.3 │ │ Platform │ darwin/arm64 │ └───────────────────┴──────────────────────────────────────────┘ ``` | Flag | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `--check` | Force a check for updates, regardless of the last check time. | | `--output, -o` | Output format: `table`, `json`, `yaml`, or `bare`. Defaults to your `output` [configuration option](#configuration-options). | ### `tiger upgrade` Download the latest published version of Tiger CLI and replace the running binary in place. The archive for your platform is verified against its SHA-256 checksum before it is installed. Alias: `update`. **Usage**: `tiger upgrade` Terminal window ``` tiger upgrade ``` If you installed Tiger CLI with the direct install script and a newer version is available, you see: ``` Upgrading Tiger CLI 0.26.0 → v0.27.0 Downloading https://cli.tigerdata.com/releases/v0.27.0/tiger-cli_Darwin_arm64.tar.gz Verifying checksum Installing new binary to /tiger Upgraded Tiger CLI to v0.27.0 ``` If you installed Tiger CLI with a package manager such as Homebrew, `apt`, or `yum`/`dnf`, this command refuses to run and points you to that package manager instead. ## Feedback ### `tiger feedback` Send feedback, a bug report, or a support request to the Tiger Data team. Pass the message as an argument, or omit it to read from stdin (with a prompt in an interactive terminal). **Usage**: `tiger feedback [message]` Terminal window ``` tiger feedback "I can't connect to my service after resuming it" echo "Great tool!" | tiger feedback ``` The message is sent with the email address of your account, so the team can follow up, and with the CLI version and operating system. The command opens no support case and returns no ticket to track; for anything that needs a tracked response, open a support request in [Tiger Console](https://console.cloud.tigerdata.com/dashboard/support) instead, and the command prints the link for your project. ## Configuration Manage Tiger CLI's own settings. `tiger config` has the alias `cfg`, so `tiger cfg list` is the same as `tiger config list`. For the full list of keys, see [Configuration options](#configuration-options). ### `tiger config list` Show the current configuration. Before Tiger CLI 0.25, the primary name of this command was `config show`; `show` and `ls` still work as aliases. **Usage**: `tiger config list [flags]` Terminal window ``` tiger config list ``` You see something like: ``` ┌──────────────────┬─────────┐ │ PROPERTY │ VALUE │ ├──────────────────┼─────────┤ │ analytics │ true │ │ color │ true │ │ docs_mcp │ true │ │ mcp_max_rows │ 100 │ │ output │ table │ │ password_storage │ keyring │ │ read_only │ off │ │ service_id │ │ │ version_check │ true │ └──────────────────┴─────────┘ ``` Before Tiger CLI 0.27, the list also showed the endpoint URLs (`api_url`, `console_url`, `docs_mcp_url`, `gateway_url`, and `releases_url`). They only matter when developing against other environments, so they are now hidden from the list and from shell completion; `tiger config set` still accepts them. | Flag | Description | | --------------- | -------------------------------------------- | | `--output, -o` | Output format: `json`, `yaml`, or `table`. | | `--no-defaults` | Do not show default values for unset fields. | | `--with-env` | Apply environment variable overrides. | ### `tiger config set` Set a configuration value. See [Configuration parameters](#configuration-parameters) for the available keys. **Usage**: `tiger config set ` Terminal window ``` tiger config set # for example tiger config set read_only prod ``` You see: ``` Set read_only = prod ``` ### `tiger config unset` Clear a configuration value. Aliases: `rm`, `delete`. **Usage**: `tiger config unset ` Terminal window ``` tiger config unset ``` You see: ``` Unset read_only ``` ### `tiger config reset` Reset the configuration to defaults, including your default service and output preferences. This does not log you out; your authentication credentials are unaffected. Alias: `clear`. **Usage**: `tiger config reset` Terminal window ``` tiger config reset ``` You see: ``` Configuration reset to defaults ``` ## Services Manage services from the terminal. `tiger service` has the aliases `services` and `svc`, so `tiger svc list` is the same as `tiger service list`. For the Tiger MCP-tool equivalent of each command, see the [Tiger MCP reference](/docs/reference/tiger-cloud/tiger-mcp/index.md); for a task-by-task comparison, see [common tasks](/docs/build/tiger-cli-mcp/common-tasks#manage-your-services/index.md). Every command that takes a service argument accepts the service's name as well as its ID, so `tiger service stop analytics` and `tiger service stop ` do the same thing. A name that matches more than one service is refused; pass the ID to disambiguate. The argument is written as `` below. Omitting it falls back to your default service, except for [`service delete`](#tiger-service-delete) and [`service rename`](#tiger-service-rename), which always need it. Two inputs still take only the ID: the configured default (the `--service-id` flag, the `TIGER_SERVICE_ID` environment variable, and the `service_id` config key), because a stored name would break every command at once if the service is renamed; and the confirmation prompt on `service delete`. Before Tiger CLI 0.26, these arguments accepted only the ID. ### `tiger service create` Create a new service in the current project. **Usage**: `tiger service create [flags]` Terminal window ``` tiger service create --name analytics --region us-east-1 ``` You see something like: ``` Creating service 'analytics'... Service ID: Password saved to system keyring Default service set to . Waiting for service to be ready (timeout: 30m0s)... Service is ready. Connect with: tiger db psql ``` Then the service's details, in the same format as [`service get`](#tiger-service-get). | Flag | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--name` | Service name (auto-generated if omitted). | | `--addons` | Addons to enable: `time-series` (TimescaleDB). Set to `none` for vanilla PostgreSQL. Before Tiger CLI 0.26, there was also a deprecated `ai` addon. | | `--region` | Region code. [Free services](/docs/get-started/quickstart/create-service#what-is-a-tiger-cloud-service/index.md) (shared CPU/memory) must use `us-east-1`. | | `--cpu` | CPU allocation in millicores. Set to `shared` for a free service. | | `--memory` | Memory allocation in gigabytes. Set to `shared` for a free service. | | `--replicas` | Number of high-availability replicas. | | `--environment` | Environment tag: `DEV` or `PROD` (default: `DEV`). | | `--no-wait` | Return without waiting for the operation to complete. | | `--wait-timeout` | Wait timeout (for example, `30m`, `1h30m`, `90s`). | | `--no-set-default` | Do not set this service as the default. | | `--with-password` | Include the password in the output. | | `--output, -o` | Output format: `json`, `yaml`, `env`, or `table`. | Allowed compute configurations: `shared`/`shared` (only in `us-east-1`), 0.5 CPU/2 GB, 1/4, 2/8, 4/16, 8/32, 16/64, 32/128. Specify `--cpu` and `--memory` together, or set one and the other is configured automatically. ### `tiger service list` List the services in the current project. Alias: `ls`. **Usage**: `tiger service list [flags]` Terminal window ``` tiger service list ``` You see something like: ``` ┌──────────────┬───────────┬────────┬─────────────┬───────────┬──────────────────┐ │ SERVICE ID │ NAME │ STATUS │ TYPE │ REGION │ CREATED │ ├──────────────┼───────────┼────────┼─────────────┼───────────┼──────────────────┤ │ │ analytics │ READY │ TIMESCALEDB │ us-east-1 │ 2026-08-11 09:00 │ └──────────────┴───────────┴────────┴─────────────┴───────────┴──────────────────┘ ``` | Flag | Description | | -------------- | ------------------------------------------ | | `--output, -o` | Output format: `json`, `yaml`, or `table`. | With no services, table output prints a message to stderr, while `-o json` and `-o yaml` print an empty list (`[]`), so scripts always get structured output. Before Tiger CLI 0.27, the JSON and YAML output was empty in this case. ### `tiger service get` Show detailed information about a service. Aliases: `describe`, `show`. **Usage**: `tiger service get [flags]` Terminal window ``` tiger service get ``` You see something like: ``` ┌───────────────────┬─────────────────────────────────────────────────────────────────────┐ │ PROPERTY │ VALUE │ ├───────────────────┼─────────────────────────────────────────────────────────────────────┤ │ Service ID │ │ │ Name │ analytics │ │ Status │ READY │ │ Type │ TIMESCALEDB │ │ Region │ us-east-1 │ │ Environment │ DEV │ │ CPU │ 0.5 cores (500m) │ │ Memory │ 2 GB │ │ Direct Endpoint │ ..tsdb.cloud.timescale.com: │ │ Created │ 2026-08-11 09:00:00 UTC │ │ Connection String │ postgresql://tsdbadmin@/tsdb?sslmode=require │ │ Console URL │ https://console.cloud.tigerdata.com/dashboard/services/ │ └───────────────────┴─────────────────────────────────────────────────────────────────────┘ ``` | Flag | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--with-password` | Include the password in the output. Only returns a value if the password was captured at creation or saved since with [`db save-password`](#tiger-db-save-password); Tiger CLI can't retrieve a forgotten password from the server. | | `--output, -o` | Output format: `json`, `yaml`, `env`, or `table`. | ### `tiger service fork` Fork an existing service into a new, independent copy. By default the fork is taken at the current database state; pass `--last-snapshot` or `--to-timestamp` to fork from an earlier point instead. See [Test a change safely on a fork](/docs/build/tiger-cli-mcp/cookbook#test-a-change-safely-on-a-fork/index.md) for a worked example. **Usage**: `tiger service fork [flags]` Terminal window ``` tiger service fork ``` You see something like: ``` Forking service '' at current state... Service ID: Password saved to system keyring Default service set to . Waiting for fork to be ready (timeout: 30m0s)... Forked service is ready. Connect with: tiger db psql ``` Then the fork's details, in the same format as [`service get`](#tiger-service-get). | Flag | Description | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `--last-snapshot` | Fork at the last existing snapshot (faster). | | `--to-timestamp` | Fork at a point in time (RFC3339). | | `--cpu`, `--memory` | Compute for the fork (inherits from the source if omitted). See [`service create`](#tiger-service-create) for allowed configurations. | | `--name` | Fork name (auto-generated from the source service's name if omitted). | | `--environment` | Environment tag: `DEV` or `PROD` (default: `DEV`). | | `--no-wait`, `--wait-timeout` | Wait behavior (default timeout: `30m`). | | `--no-set-default`, `--with-password`, `--output, -o` | Default-service and output options. | Before Tiger CLI 0.26, you had to choose exactly one timing option, and forking at the current state had its own flag, `--now`. The flag still works, but it is no longer needed: it names the default behavior. ### `tiger service resize` Change a service's CPU and memory. The service may be briefly unavailable during the resize. **Usage**: `tiger service resize [flags]` Terminal window ``` tiger service resize --cpu 4000 --memory 16 ``` You see something like: ``` Waiting for resize to complete (timeout: 10m0s)... Service resized to 4 CPU/16 GB. ``` | Flag | Description | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--cpu`, `--memory` | New allocation. CPU is in millicores, memory in gigabytes, so 4 CPU / 16 GB is `--cpu 4000 --memory 16`. See [`service create`](#tiger-service-create) for allowed configurations. You cannot resize to `shared`. | | `--no-wait`, `--wait-timeout` | Wait behavior (default timeout: `10m`). | ### `tiger service start` Start an inactive service. Alias: `resume`. **Usage**: `tiger service start [flags]` Terminal window ``` tiger service start ``` You see something like: ``` Waiting for service to start (timeout: 10m0s)... Service started. ``` | Flag | Description | | ----------------------------- | --------------------------------------- | | `--no-wait`, `--wait-timeout` | Wait behavior (default timeout: `10m`). | ### `tiger service stop` Stop an active service. After stopping, the service no longer accepts connections. Alias: `pause`. **Usage**: `tiger service stop [flags]` Terminal window ``` tiger service stop ``` You see something like: ``` Waiting for service to stop (timeout: 10m0s)... Service stopped. ``` | Flag | Description | | ----------------------------- | --------------------------------------- | | `--no-wait`, `--wait-timeout` | Wait behavior (default timeout: `10m`). | ### `tiger service update-password` Update the master password for a service. **Usage**: `tiger service update-password [flags]` Terminal window ``` tiger service update-password --auto-generate ``` You see something like: ``` Password saved to system keyring View it with: tiger service get --with-password Password updated for tsdbadmin ``` | Flag | Description | | ----------------- | --------------------------------------------------------------------------- | | `--new-password` | New password for the `tsdbadmin` user. | | `--auto-generate` | Auto-generate a secure password (mutually exclusive with `--new-password`). | ### `tiger service rename` Rename a service. Only the display name changes: the service ID, endpoints, and stored credentials are untouched, so existing connections and connection strings keep working. **Usage**: `tiger service rename ` Terminal window ``` tiger service rename analytics-prod ``` You see: ``` Renamed service 'analytics' () to 'analytics-prod'. ``` Both arguments are required; there is no default-service fallback, because a single argument would be ambiguous between the service to rename and the name to give it. ### `tiger service delete` Delete a service. This is irreversible and prompts you to type the service ID to confirm before proceeding. The command returns as soon as the API accepts the deletion. Alias: `rm`. **Usage**: `tiger service delete [flags]` Terminal window ``` tiger service delete --confirm ``` You see: ``` Service 'analytics' () deleted. ``` | Flag | Description | | ----------- | ------------------------------------------------------------------------- | | `--confirm` | Skip the confirmation prompt. AI agents must confirm with the user first. | Before Tiger CLI 0.25, this command also took `--no-wait` and `--wait-timeout`; they were removed because the API removes the service from view as soon as it accepts the deletion, so there is nothing to wait for. The [`service_delete`](/docs/reference/tiger-cloud/tiger-mcp#service_delete/index.md) Tiger MCP tool is the agent-side equivalent; deleting a service tagged `PROD` through it prompts you for confirmation through the MCP client. ### `tiger service logs` View the logs for a service. Alias: `log`. **Usage**: `tiger service logs [flags]` Terminal window ``` tiger service logs --tail 5 ``` You see something like: ``` 2026-08-13 07:07:50 UTC [158]: [6a79e2e5.9e-301] 0 @,app= [00000] LOG: checkpoint starting: time 2026-08-13 07:07:50 UTC [158]: [6a79e2e5.9e-302] 0 @,app= [00000] LOG: checkpoint complete: wrote 4 buffers (0.0%), wrote 0 SLRU buffers; 0 WAL file(s) added, 0 removed, 1 recycled; write=0.403 s, sync=0.003 s, total=0.412 s; sync files=3, longest=0.003 s, average=0.001 s; distance=16390 kB, estimate=29655 kB; lsn=0/CE001A80, redo lsn=0/CE001A28 2026-08-13 07:07:51 - wal_archive_command_pgbackrest - archiving pg_wal/0000000100000000000000CE 2026-08-13 07:29:22 UTC [307395]: [6a7d7252.4b0c3-1] 0 [unknown]@[unknown],app=[unknown] [08P01] LOG: SSL error: unexpected eof while reading 2026-08-13 07:29:22 UTC [307395]: [6a7d7252.4b0c3-2] 0 [unknown]@[unknown],app=[unknown] [08006] LOG: could not receive data from client: Connection reset by peer ``` Tiger CLI converts PostgreSQL log timestamps to your machine's time zone, so set `TZ` if you want a specific one (for example, `TZ=UTC tiger service logs `). The `wal_archive_command_pgbackrest` lines come from the backup agent rather than PostgreSQL, and are always in UTC. | Flag | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--tail` | Number of log entries to show (default: `100`). One entry can span several lines, for example a `FATAL` followed by its `DETAIL`, so the output can be longer than the number you ask for. | | `--since`, `--until` | Fetch logs within a time range (RFC3339, for example `2024-01-15T09:00:00Z`). | | `--node` | Specific node to fetch logs from (for services with HA replicas; `0` is valid). | | `--output, -o` | Output format: `json`, `yaml`, or `table`. | ## Metrics Query a service's time-series metrics for monitoring, debugging, and performance investigation. For the Tiger MCP-tool equivalents, see [metrics tools](/docs/reference/tiger-cloud/tiger-mcp#metrics-tools/index.md). For every metric you can query, see [Available metrics](#available-metrics). ### `tiger service metrics available` List the names of the metric series available for the service you specify, for monitoring, debugging, and performance investigation. Use these names with [`service metrics details`](#tiger-service-metrics-details) and [`service metrics series`](#tiger-service-metrics-series). For the full list with descriptions, see [Available metrics](#available-metrics). Before Tiger CLI 0.26, the metrics commands were experimental and hidden unless the `TIGER_EXPERIMENTAL` environment variable was set, and this command was named `metrics available-series`. **Usage**: `tiger service metrics available [flags]` Terminal window ``` tiger service metrics available ``` You see something like: ``` timescale_cloud_system_cpu_usage_millicores timescale_cloud_system_memory_usage_bytes pg_locks_count pg_stat_activity_count pg_stat_activity_max_tx_duration pg_stat_database_numbackends ... ``` | Flag | Description | | -------------- | ------------------------------------------ | | `--output, -o` | Output format: `json`, `yaml`, or `table`. | ### `tiger service metrics details` Show descriptive metadata for a metric: what it measures, its type, its default aggregation function, and the labels you can filter or group it by. **Usage**: `tiger service metrics details --metric [flags]` Terminal window ``` tiger service metrics details --metric pg_stat_activity_count ``` You see something like: ``` ┌─────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────┐ │ PROPERTY │ VALUE │ ├─────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────┤ │ Name │ pg_stat_activity_count │ │ Type │ GAUGE │ │ Default Aggregation │ MAX_TOTAL │ │ Description │ Number of connections in pg_stat_activity, grouped by state, connected role, and backend type. │ └─────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────┘ ┌──────────────┬─────────────────────────────────────────────────────┐ │ LABEL │ DESCRIPTION │ ├──────────────┼─────────────────────────────────────────────────────┤ │ datname │ undocumented │ │ state │ undocumented │ │ usename │ undocumented │ │ backend_type │ undocumented │ │ region │ Region the service runs in. │ │ role │ Instance role: primary, replica, or standby_leader. │ │ ordinal │ Per-pod ordinal within the service. │ └──────────────┴─────────────────────────────────────────────────────┘ ``` The `timescale_cloud_system_*` metrics have no richer metadata; for those, this command returns just the name: the table shows `undocumented` for the type, default aggregation, and description and lists no labels, and JSON output returns those fields as null or empty. | Flag | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------- | | `--metric` | The metric to describe. Use [`service metrics available`](#tiger-service-metrics-available) to discover valid names. | | `--output, -o` | Output format: `json`, `yaml`, or `table`. | ### `tiger service metrics series` Fetch time-series data for a metric. Each labeled series, for example one per replica, is returned independently with its full list of data points. **Usage**: `tiger service metrics series --metric [flags]` Terminal window ``` tiger service metrics series --metric timescale_cloud_system_cpu_usage_millicores ``` You see something like: ``` ┌──────────────────────────────┬──────────────────────┬─────────┐ │ SERIES │ TIME │ VALUE │ ├──────────────────────────────┼──────────────────────┼─────────┤ │ {ordinal="0",role="primary"} │ 2026-09-30T12:00:00Z │ 102.000 │ │ {ordinal="0",role="primary"} │ 2026-09-30T13:00:00Z │ 98.000 │ │ {ordinal="0",role="primary"} │ 2026-09-30T14:00:00Z │ 110.000 │ └──────────────────────────────┴──────────────────────┴─────────┘ ``` With no `--from` and `--to`, the command returns the last 24 hours bucketed into 1-hour intervals. Terminal window ``` # A specific hour, primary instance only tiger service metrics series --metric timescale_cloud_system_cpu_usage_millicores \ --from 2026-09-30T00:00:00Z --to 2026-09-30T01:00:00Z --role PRIMARY # Exclude a label value, one series per role tiger service metrics series --metric pg_stat_activity_count \ --filter state!=idle --group-by role ``` | Flag | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--metric` | The metric series to fetch. Use [`service metrics available`](#tiger-service-metrics-available) to discover valid names. | | `--from`, `--to` | Time window (RFC3339). `--to` cannot be in the future. Default: the last 24 hours. | | `--bucket-seconds` | Aggregation bucket size in seconds (minimum: `60`). Defaults to `3600` (1 hour) when `--from`/`--to` are also omitted; otherwise the server picks a size matched to the window. | | `--fn` | Aggregation function applied per bucket: `RATE`, `INCREASE`, `SUM`, `AVG`, `MIN`, `MAX`, `MIN_TOTAL`, `MAX_TOTAL`, `COUNT`, `P50`, `P90`, `P99`, or `LAST`. Omit to let the server pick the metric's default. Not accepted on the `timescale_cloud_system_*` metrics. See [Aggregation functions](#aggregation-functions) for what each one computes. | | `--role` | Restrict to one instance role: `PRIMARY` or `REPLICA`. Omit to aggregate datapoints across all nodes. For most queries applying `--role PRIMARY` could be more meaningful. | | `--filter` | Arbitrary label filter as `name=value` or `name!=value` (repeatable). `name!=value` also matches series missing the label entirely. | | `--group-by` | Label key to break the result into one series per distinct value (repeatable). Rejected on the same metrics that reject `--fn`. Omit to collapse into a single series. | | `--output, -o` | Output format: `json`, `yaml`, or `table`. | ## Database Connect to a service's database and manage roles from the terminal. See [Work with your data](/docs/build/tiger-cli-mcp/common-tasks#work-with-your-data/index.md) for how these commands compare to asking Tiger MCP, and [best practices](/docs/build/tiger-cli-mcp/agent-best-practices#restrict-agents-to-read-only/index.md) for connecting an agent as a read-only role. The `--pooled` flag on these commands, and the `pooled` parameter on Tiger MCP's database tools, need a connection pooler on the service. Without one, the command fails with `connection pooler not available for this service`. ### `tiger db psql` Connect to a service with `psql`. Pass extra `psql` flags after `--`, for example `tiger db psql -- --single-transaction`. Before Tiger CLI 0.25, the primary name of this command was `db connect`; `connect` still works as an alias. **Usage**: `tiger db psql [flags]` Terminal window ``` tiger db psql ``` You see something like: ``` psql (17.7 (Homebrew), server 18.4 (Ubuntu 18.4-1.pgdg22.04+1)) WARNING: psql major version 17, server major version 18. Some psql features might not work. SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: postgresql) Type "help" for help. tsdb=> ``` | Flag | Description | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--pooled` | Use connection pooling (default: `false`). | | `--role` | Database role (default: `tsdbadmin`). | | `--read-only` | Open the session in Tiger Cloud's immutable read-only mode, so writes and DDL are rejected by the server. The [`read_only` config option](#configuration-parameters) (or `TIGER_READ_ONLY`) forces the same behavior for every service (`all`) or for services tagged `PROD` (`prod`). | | `--no-replica-prompt` | Do not prompt to connect to a read replica. | ### `tiger db query` Run a SQL query against a service and print the results. Unlike [`db psql`](#tiger-db-psql), this runs the query directly and does not require a local `psql` installation. Pass a read replica set ID instead of a service ID to query that replica. Alias: `sql`. **Usage**: `tiger db query [service-id] [flags]` The query comes from `--command`, from the SQL file named by `--file`, or, if neither is given, from stdin: Terminal window ``` tiger db query -c "SELECT * FROM users LIMIT 5" tiger db query -f schema.sql echo "SELECT 1" | tiger db query ``` You see something like: ``` id | name | created_at ----|-------|------------------------ 1 | alice | 2026-01-01 00:00:00+00 2 | bob | 2026-01-02 00:00:00+00 (2 rows) ``` Row-returning statements print a `psql`-style table (or JSON/YAML with `--output`); other statements print their command tag, such as `INSERT 0 1`. Multi-statement queries (semicolon-separated) are supported, and the results of every row-returning statement are displayed. The statements run in an implicit transaction that commits on success and rolls back on error; a transaction opened with `BEGIN` must be committed explicitly or it rolls back when the connection closes. | Flag | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--command, -c` | SQL query to execute (mutually exclusive with `--file`). | | `--file, -f` | Path to a SQL file to execute (mutually exclusive with `--command`). | | `--role` | Database role (default: `tsdbadmin`). | | `--pooled` | Use connection pooling (default: `false`). | | `--read-only` | Open the session in Tiger Cloud's immutable read-only mode, so writes and DDL are rejected by the server. The [`read_only` config option](#configuration-parameters) (or `TIGER_READ_ONLY`) forces the same behavior for every service (`all`) or for services tagged `PROD` (`prod`). | | `--timeout` | Query timeout, for example `30s`, `5m` (default: `0`, no timeout). | | `--output, -o` | Output format: `table`, `json`, or `yaml`. | This command is the CLI equivalent of the [`db_query`](/docs/reference/tiger-cloud/tiger-mcp#db_query/index.md) Tiger MCP tool, with one difference: the Tiger MCP tool caps how many rows it returns to the agent, while the CLI command returns everything the query produced. ### `tiger db uri` Print the connection string for a service. Before Tiger CLI 0.25, the primary name of this command was `db connection-string`; the old name still works as an alias. **Usage**: `tiger db uri [flags]` Terminal window ``` tiger db uri ``` You see something like: ``` postgresql://tsdbadmin@/tsdb?sslmode=require ``` With `--read-only`, the connection string sets a session option that forces Tiger Cloud's immutable read-only mode: ``` postgresql://tsdbadmin@/tsdb?sslmode=require&options=-c%20tsdb_admin.read_only_connection%3Dtrue ``` | Flag | Description | | ----------------- | ----------------------------------------------------- | | `--pooled` | Use connection pooling (default: `false`). | | `--role` | Database role (default: `tsdbadmin`). | | `--with-password` | Include the password (default: `false`, less secure). | | `--read-only` | Emit a read-only connection string. | ### `tiger db create role` Create a database role. The `role` subcommand has the alias `user`, so `tiger db create user` is the same command. **Usage**: `tiger db create role [flags]` Terminal window ``` tiger db create role --name app_role --read-only ``` You see: ``` ✓ Role 'app_role' created successfully Read-only enforcement: enabled (permanent, role-based) ``` | Flag | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--name` (required) | The role to create. | | `--read-only` | Enforce permanent read-only for the role using `tsdb_admin.read_only_role`. This enforces read-only, it doesn't grant read access: the new role can log in and has `USAGE` on `public`, but no table privileges, so `SELECT` fails until you [grant it](/docs/deploy/tiger-cloud/tiger-cloud-aws/security/read-only-role#create-a-read-only-user/index.md). | | `--from` | Inherit grants from one or more roles, for example `--from app_role,readonly_role`. | | `--statement-timeout` | Statement timeout for the role, for example `30s`, `5m`. | | `--password` | Role password (falls back to `TIGER_NEW_PASSWORD`, otherwise auto-generated). | | `--output, -o` | Output format: `json`, `yaml`, or `table`. | ### `tiger db schema` Display the schema of a service database as readable text. **Usage**: `tiger db schema [flags]` Terminal window ``` tiger db schema ``` You see something like: ``` DATABASE: () SCHEMA: public TABLE: sensor_data -- HYPERTABLE (chunks=0, compression=enabled) time TIMESTAMP WITH TIME ZONE NOT NULL sensor_id TEXT value DOUBLE PRECISION INDEX sensor_data_time_idx ("time" DESC) ``` | Flag | Description | | --------------- | --------------------------------------------------------------------------------------------------------- | | `--schema` | Restrict output to a single schema. | | `--definitions` | Include full object definitions (view `SELECT`s, function and procedure bodies). | | `--comments` | Include object comments (`COMMENT ON` text). | | `--internal` | Include system schemas (`pg_*`, `information_schema`, TimescaleDB internals) and extension-owned objects. | | `--pooled` | Use connection pooling (default: `false`). | | `--role` | Database role (default: `tsdbadmin`). | ### `tiger db extensions list` List the PostgreSQL extensions installed in a service's database, with each extension's version, the schema it lives in, and its description. Use it to check what is available before you write SQL, for example whether `timescaledb_toolkit` is installed for [hyperfunctions](/docs/reference/toolkit/index.md). Pass a read replica set ID to list the extensions on that replica. The connection is opened in Tiger Cloud's immutable read-only mode. `extensions` has the alias `ext` and `list` has the alias `ls`, so `tiger db ext ls` is the same command. **Usage**: `tiger db extensions list [flags]` Terminal window ``` tiger db extensions list ``` You see something like: ``` ┌─────────────────────┬─────────┬────────────┬───────────────────────────────────────────────────────────────────────────────────────┐ │ NAME │ VERSION │ SCHEMA │ DESCRIPTION │ ├─────────────────────┼─────────┼────────────┼───────────────────────────────────────────────────────────────────────────────────────┤ │ pg_buffercache │ 1.6 │ public │ examine the shared buffer cache │ │ pg_stat_statements │ 1.12 │ public │ track planning and execution statistics of all SQL statements executed │ │ plpgsql │ 1.0 │ pg_catalog │ PL/pgSQL procedural language │ │ postgres_fdw │ 1.2 │ public │ foreign-data wrapper for remote PostgreSQL servers │ │ timescaledb │ 2.31.0 │ public │ Enables scalable inserts and complex queries for time-series data (Community Edition) │ │ timescaledb_toolkit │ 1.26.0 │ public │ Library of analytical hyperfunctions, time-series pipelining, and other SQL utilities │ └─────────────────────┴─────────┴────────────┴───────────────────────────────────────────────────────────────────────────────────────┘ ``` | Flag | Description | | -------------- | ------------------------------------------ | | `--role` | Database role (default: `tsdbadmin`). | | `--output, -o` | Output format: `json`, `yaml`, or `table`. | The [`db_extensions_list`](/docs/reference/tiger-cloud/tiger-mcp#db_extensions_list/index.md) Tiger MCP tool is the agent-side equivalent. ### `tiger db save-password` Save the password for a service to the keychain. **Usage**: `tiger db save-password [flags]` Terminal window ``` tiger db save-password --password= ``` You see: ``` Password saved for service 'analytics' (), role tsdbadmin ``` | Flag | Description | | ------------ | --------------------------------------------- | | `--role` | Database role (default: `tsdbadmin`). | | `--password` | Password value (or use `TIGER_NEW_PASSWORD`). | ### `tiger db ping` Test connectivity to a service. Before Tiger CLI 0.25, the primary name of this command was `db test-connection`; `test-connection` and `test` still work as aliases. **Usage**: `tiger db ping [flags]` Terminal window ``` tiger db ping ``` You see: ``` Connection successful ``` If the connection fails, the reason is printed twice, once as a message and once as an error: ``` Connection failed: failed to connect to `user=tsdbadmin database=tsdb`: :: failed SASL auth: FATAL: password authentication failed for user "tsdbadmin" (SQLSTATE 28P01) Error: failed to connect to `user=tsdbadmin database=tsdb`: :: failed SASL auth: FATAL: password authentication failed for user "tsdbadmin" (SQLSTATE 28P01) ``` Use the exit code in scripts: | Exit code | Meaning | | --------- | ----------------------------------------------------------------------------------------------------------------------------- | | `0` | The connection succeeded. | | `1` | Tiger CLI didn't run the check, because a flag or argument was invalid. | | `2` | The connection was attempted and failed: the server was unreachable, the attempt timed out, or the credentials were rejected. | | `3` | No attempt was made, because no service with that ID exists or no ID was given. | | Flag | Description | | --------------- | ------------------------------------------------- | | `--timeout, -t` | Connection timeout (default: `3s`, `0` for none). | | `--pooled` | Use connection pooling (default: `false`). | | `--role` | Database role (default: `tsdbadmin`). | ## MCP Install and manage Tiger MCP, the tool your AI agent uses to work with Tiger Cloud. See [Integrate Tiger Cloud with your AI agent](/docs/get-started/quickstart/mcp-cli/index.md) to set it up, and the [Tiger MCP reference](/docs/reference/tiger-cloud/tiger-mcp/index.md) for every tool it exposes. ### `tiger mcp install` Install and configure Tiger MCP for an AI agent. Supported clients: `claude-code`, `codex`, `copilot`, `cursor`, `devin`, `gemini`, `vscode`, `antigravity`, `kiro-cli`. If no client is given, you are prompted to choose. Alias: `add`. The `copilot` client configures the GitHub Copilot CLI, and the GitHub Copilot desktop app picks up the same configuration. The `antigravity` client writes to `~/.gemini/config/`, which Antigravity 2.0, the Antigravity IDE, and the Antigravity CLI all read. Before Tiger CLI 0.27, it wrote to `~/.gemini/antigravity/mcp_config.json`, which only the IDE reads. To give your agent the same skills Tiger MCP serves as local files it loads directly, see [`tiger skills install`](#tiger-skills-install). **Usage**: `tiger mcp install [client] [flags]` Terminal window ``` tiger mcp install claude-code ``` For sample output, see [Install and configure Tiger MCP](/docs/get-started/quickstart/mcp-cli#install-and-configure-tiger-mcp/index.md). | Flag | Description | | --------------- | ----------------------------------------------------------- | | `--no-backup` | Do not back up the client's existing config before writing. | | `--config-path` | Path to the client config file to update. | ### `tiger mcp list` List the available Tiger MCP tools, prompts, and resources. Alias: `ls`. **Usage**: `tiger mcp list [flags]` Terminal window ``` tiger mcp list ``` You see something like: ``` ┌────────┬────────────────────────────────────────┐ │ TYPE │ NAME │ ├────────┼────────────────────────────────────────┤ │ prompt │ design-postgis-tables │ │ prompt │ design-postgres-tables │ │ prompt │ find-hypertable-candidates │ │ prompt │ migrate-postgres-tables-to-hypertables │ │ prompt │ pgvector-semantic-search │ │ prompt │ postgres │ │ prompt │ postgres-database-migration │ │ prompt │ postgres-hybrid-text-search │ │ prompt │ schema-exploration │ │ prompt │ setup-timescaledb-hypertables │ │ prompt │ timescaledb-hyperfunctions │ │ tool │ db_extensions_list │ │ tool │ db_query │ │ tool │ db_schema │ │ tool │ feedback │ │ tool │ search_docs │ │ tool │ service_create │ │ tool │ service_delete │ │ tool │ service_fork │ │ tool │ service_get │ │ tool │ service_list │ │ tool │ service_logs │ │ tool │ service_metrics_available │ │ tool │ service_metrics_details │ │ tool │ service_metrics_series │ │ tool │ service_rename │ │ tool │ service_resize │ │ tool │ service_start │ │ tool │ service_stop │ │ tool │ service_update_password │ │ tool │ view_skill │ └────────┴────────────────────────────────────────┘ ``` | Flag | Description | | -------------- | ------------------------------------------ | | `--output, -o` | Output format: `json`, `yaml`, or `table`. | ### `tiger mcp get` Show detailed information about a Tiger MCP tool, prompt, or resource, including skills. Aliases: `describe`, `show`. **Usage**: `tiger mcp get [flags]` Terminal window ``` tiger mcp get service_create tiger mcp get setup-timescaledb-hypertables ``` For `service_create`, you see something like: ``` Create Database Service Tool name: service_create Description: Create a new database service in Tiger Cloud with specified type, compute resources, region, and HA options. The default type of service created depends on the user's plan: - Free plan: Creates a service with shared CPU/memory and the 'time-series' and 'ai' add-ons - Paid plans: Creates a service with 0.5 CPU / 2 GB memory and the 'time-series' add-on WARNING: Creates billable resources. Parameters: ... Output: ... ``` Full parameter and output details follow, matching the [Tiger MCP reference](/docs/reference/tiger-cloud/tiger-mcp/index.md). | Flag | Description | | -------------- | ------------------------------------------ | | `--output, -o` | Output format: `json`, `yaml`, or `table`. | ### `tiger mcp start` Start Tiger MCP. `tiger mcp start` is the same as `tiger mcp start stdio`. **Usage**: `tiger mcp start [transport] [flags]` Terminal window ``` tiger mcp start ``` The server starts listening for JSON-RPC requests on stdio (or HTTP, with the `http` transport) and logs its own activity to stderr, so the logs never corrupt the JSON-RPC stream on stdout: ``` 2026/08/27 19:09:33 INFO server run start 2026/08/27 19:09:33 INFO server connecting 2026/08/27 19:09:33 INFO server session connected session_id="" ``` | Transport | Description | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `stdio` | stdio transport (default). | | `http` | HTTP transport, with `--port` (default: `8080`) and `--host` (default: `localhost`). If the port is already in use, the server fails to start. | Before Tiger CLI 0.27, the `http` transport silently moved to the next free port when the requested one was busy, which left MCP clients configured for that port unable to connect. ## Skills Install the skills Tiger MCP serves, such as `setup-timescaledb-hypertables` and `design-postgres-tables`, as local agent skills. Coding agents that support skills then load them natively, without going through Tiger MCP. Skills come from the open source [pg-aiguide](https://github.com/timescale/pg-aiguide) project. ### `tiger skills install` Install agent skills for the current user. Alias: `add`. **Usage**: `tiger skills install [location...] [flags]` Terminal window ``` tiger skills install universal claude-code ``` You see something like: ``` Installed 11 skills: design-postgis-tables design-postgres-tables ... Installed to: /Users//.agents/skills /Users//.claude/skills Restart your coding agents to load the new skills. ``` Each argument selects an install location, either by name or by the name of a client that reads it: | Location | Directory | Read by | | ------------- | ------------------------- | ------------------------------------------------------------- | | `universal` | `~/.agents/skills` | Cursor, Devin, Codex, Gemini CLI, VS Code, GitHub Copilot CLI | | `claude-code` | `~/.claude/skills` | Claude Code | | `antigravity` | `~/.gemini/config/skills` | Google Antigravity | | `kiro-cli` | `~/.kiro/skills` | Kiro CLI | The client names accepted by [`tiger mcp install`](#tiger-mcp-install) work here too: a client that reads `~/.agents/skills`, such as `cursor`, selects `universal`. With no arguments, you choose locations from an interactive picker, which starts with the locations you installed to before checked (`universal` on a first install). Re-run the command to update the skills to the current upstream version; skills that are no longer available are removed. Each skill is copied into each location, not symlinked, and `npx skills` can also find, manage, and remove skills installed this way. Tiger CLI never replaces a skill it did not install unless you pass `--force`. | Flag | Description | | -------------- | ------------------------------------------------------------------------------------------------- | | `--skills-dir` | Install into this directory only, instead of a named location. Not remembered for later installs. | | `--force` | Replace existing skills that Tiger CLI did not install. | ## Shell completion Tiger CLI ships completions for bash, zsh, fish, and PowerShell. Installing with Homebrew sets up the bash, zsh, and fish completions for you; otherwise generate them with `tiger completion `. Completion covers command and flag names, most flag values, and most command arguments. That includes services and project IDs, so you can complete them instead of typing or pasting them. A service argument completes to the service's name, falling back to its ID when what you typed matches the ID instead; the `--service-id` flag completes only IDs, because that is all the flag accepts. Before Tiger CLI 0.26, service arguments completed only IDs. Aliases are not offered as suggestions, so `tiger service ` proposes `list` rather than `ls`, even though both work. ## Available metrics The [`tiger service metrics`](#tiger-service-metrics-available) commands and the Tiger MCP [metrics tools](/docs/reference/tiger-cloud/tiger-mcp#metrics-tools/index.md) serve the same metrics the [Tiger Cloud exporters](/docs/integrate/observability-alerting/exported-metrics/index.md) export, listed below. Run `tiger service metrics available` to see which of them are available for your service, and `tiger service metrics details` to inspect one metric's type, default aggregation, and labels. ### System metrics These metrics track the service's resource usage against its capacity: CPU, memory, disk space, and disk I/O. | Metric | Description | | --------------------------------------------- | -------------------------------------------------------------------- | | `timescale_cloud_system_cpu_total_millicores` | Total CPU capacity available to the service, in millicores. | | `timescale_cloud_system_cpu_usage_millicores` | Current CPU usage by the service, in millicores. | | `timescale_cloud_system_disk_io_read_bytes` | Total bytes read from disk. | | `timescale_cloud_system_disk_io_read_ops` | Total number of disk read operations. | | `timescale_cloud_system_disk_io_total_bytes` | Total bytes of all disk I/O (reads and writes combined). | | `timescale_cloud_system_disk_io_total_ops` | Total number of all disk I/O operations (reads and writes combined). | | `timescale_cloud_system_disk_io_write_bytes` | Total bytes written to disk. | | `timescale_cloud_system_disk_io_write_ops` | Total number of disk write operations. | | `timescale_cloud_system_disk_usage_bytes` | Current disk space used by the service, in bytes. | | `timescale_cloud_system_memory_total_bytes` | Total memory available to the service, in bytes. | | `timescale_cloud_system_memory_usage_bytes` | Current memory usage by the service, in bytes. | ### Lock metrics These metrics track current lock activity in the database, helping you detect lock contention that may be blocking queries. | Metric | Description | | ---------------- | ---------------- | | `pg_locks_count` | Number of locks. | ### Replication metrics These metrics track the status and lag of replication slots, helping you monitor whether replicas are keeping up with the primary. | Metric | Description | | -------------------------------------- | -------------------------------------- | | `pg_replication_slots_active` | Flag indicating if the slot is active. | | `pg_replication_slots_pg_wal_lsn_diff` | Replication lag in bytes. | ### PostgreSQL settings metrics These metrics expose the current values of PostgreSQL configuration parameters as numeric values, covering memory limits, planner costs, autovacuum tuning, WAL configuration, and more. | Metric | Description | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `pg_settings_allow_alter_system` | Allows running the ALTER SYSTEM command. | | `pg_settings_allow_in_place_tablespaces` | Allows tablespaces directly inside `pg_tblspc`, for testing. | | `pg_settings_allow_system_table_mods` | Allows modifications of the structure of system tables. | | `pg_settings_archive_timeout_seconds` | Sets the amount of time to wait before forcing a switch to the next WAL file. Units converted to seconds. | | `pg_settings_array_nulls` | Enables input of NULL elements in arrays. | | `pg_settings_authentication_timeout_seconds` | Sets the maximum allowed time to complete client authentication. Units converted to seconds. | | `pg_settings_auto_explain_log_analyze` | Use EXPLAIN ANALYZE for plan logging. | | `pg_settings_auto_explain_log_buffers` | Log buffers usage. | | `pg_settings_auto_explain_log_min_duration_seconds` | Sets the minimum execution time above which plans will be logged. Units converted to seconds. | | `pg_settings_auto_explain_log_nested_statements` | Log nested statements. | | `pg_settings_auto_explain_log_parameter_max_length_bytes` | Sets the maximum length of query parameter values to log. Units converted to bytes. | | `pg_settings_auto_explain_log_settings` | Log modified configuration parameters affecting query planning. | | `pg_settings_auto_explain_log_timing` | Collect timing data, not just row counts. | | `pg_settings_auto_explain_log_triggers` | Include trigger statistics in plans. | | `pg_settings_auto_explain_log_verbose` | Use EXPLAIN VERBOSE for plan logging. | | `pg_settings_auto_explain_log_wal` | Log WAL usage. | | `pg_settings_auto_explain_sample_rate` | Fraction of queries to process. | | `pg_settings_autovacuum` | Starts the autovacuum subprocess. | | `pg_settings_autovacuum_analyze_scale_factor` | Number of tuple inserts, updates, or deletes prior to analyze as a fraction of `reltuples`. | | `pg_settings_autovacuum_analyze_threshold` | Minimum number of tuple inserts, updates, or deletes prior to analyze. | | `pg_settings_autovacuum_freeze_max_age` | Age at which to autovacuum a table to prevent transaction ID wraparound. | | `pg_settings_autovacuum_max_workers` | Sets the maximum number of simultaneously running autovacuum worker processes. | | `pg_settings_autovacuum_multixact_freeze_max_age` | Multixact age at which to autovacuum a table to prevent multixact wraparound. | | `pg_settings_autovacuum_naptime_seconds` | Time to sleep between autovacuum runs. Units converted to seconds. | | `pg_settings_autovacuum_vacuum_cost_delay_seconds` | Vacuum cost delay in milliseconds, for autovacuum. Units converted to seconds. | | `pg_settings_autovacuum_vacuum_cost_limit` | Vacuum cost amount available before napping, for autovacuum. | | `pg_settings_autovacuum_vacuum_insert_scale_factor` | Number of tuple inserts prior to vacuum as a fraction of `reltuples`. | | `pg_settings_autovacuum_vacuum_insert_threshold` | Minimum number of tuple inserts prior to vacuum. | | `pg_settings_autovacuum_vacuum_max_threshold` | Maximum number of tuple updates or deletes prior to vacuum. | | `pg_settings_autovacuum_vacuum_scale_factor` | Number of tuple updates or deletes prior to vacuum as a fraction of `reltuples`. | | `pg_settings_autovacuum_vacuum_threshold` | Minimum number of tuple updates or deletes prior to vacuum. | | `pg_settings_autovacuum_work_mem_bytes` | Sets the maximum memory to be used by each autovacuum worker process. Units converted to bytes. | | `pg_settings_autovacuum_worker_slots` | Sets the number of backend slots to allocate for autovacuum workers. | | `pg_settings_backend_flush_after_bytes` | Number of pages after which previously performed writes are flushed to disk. Units converted to bytes. | | `pg_settings_bgwriter_delay_seconds` | Background writer sleep time between rounds. Units converted to seconds. | | `pg_settings_bgwriter_flush_after_bytes` | Number of pages after which previously performed writes are flushed to disk. Units converted to bytes. | | `pg_settings_bgwriter_lru_maxpages` | Background writer maximum number of LRU pages to flush per round. | | `pg_settings_bgwriter_lru_multiplier` | Multiple of the average buffer usage to free per round. | | `pg_settings_block_size` | Shows the size of a disk block. | | `pg_settings_bonjour` | Enables advertising the server via Bonjour. | | `pg_settings_check_function_bodies` | Check routine bodies during CREATE FUNCTION and CREATE PROCEDURE. | | `pg_settings_checkpoint_completion_target` | Time spent flushing dirty buffers during checkpoint, as fraction of checkpoint interval. | | `pg_settings_checkpoint_flush_after_bytes` | Number of pages after which previously performed writes are flushed to disk. Units converted to bytes. | | `pg_settings_checkpoint_timeout_seconds` | Sets the maximum time between automatic WAL checkpoints. Units converted to seconds. | | `pg_settings_checkpoint_warning_seconds` | Sets the maximum time before warning if checkpoints triggered by WAL volume happen too frequently. Units converted to seconds. | | `pg_settings_client_connection_check_interval_seconds` | Sets the time interval between checks for disconnection while running queries. Units converted to seconds. | | `pg_settings_commit_delay` | Sets the delay in microseconds between transaction commit and flushing WAL to disk. | | `pg_settings_commit_siblings` | Sets the minimum number of concurrent open transactions required before performing `commit_delay`. | | `pg_settings_commit_timestamp_buffers_bytes` | Sets the size of the dedicated buffer pool used for the commit timestamp cache. Units converted to bytes. | | `pg_settings_cpu_index_tuple_cost` | Sets the planner's estimate of the cost of processing each index entry during an index scan. | | `pg_settings_cpu_operator_cost` | Sets the planner's estimate of the cost of processing each operator or function call. | | `pg_settings_cpu_tuple_cost` | Sets the planner's estimate of the cost of processing each tuple (row). | | `pg_settings_cursor_tuple_fraction` | Sets the planner's estimate of the fraction of a cursor's rows that will be retrieved. | | `pg_settings_data_checksums` | Shows whether data checksums are turned on for this cluster. | | `pg_settings_data_directory_mode` | Shows the mode of the data directory. | | `pg_settings_data_sync_retry` | Whether to continue running after a failure to sync data files. | | `pg_settings_deadlock_timeout_seconds` | Sets the time to wait on a lock before checking for deadlock. Units converted to seconds. | | `pg_settings_debug_assertions` | Shows whether the running server has assertion checks enabled. | | `pg_settings_debug_discard_caches` | Aggressively flush system caches for debugging purposes. | | `pg_settings_debug_pretty_print` | Indents parse and plan tree displays. | | `pg_settings_debug_print_parse` | Logs each query's parse tree. | | `pg_settings_debug_print_plan` | Logs each query's execution plan. | | `pg_settings_debug_print_rewritten` | Logs each query's rewritten parse tree. | | `pg_settings_default_statistics_target` | Sets the default statistics target. | | `pg_settings_default_transaction_deferrable` | Sets the default deferrable status of new transactions. | | `pg_settings_default_transaction_read_only` | Sets the default read-only status of new transactions. | | `pg_settings_effective_cache_size_bytes` | Sets the planner's assumption about the total size of the data caches. Units converted to bytes. | | `pg_settings_effective_io_concurrency` | Number of simultaneous requests that can be handled efficiently by the disk subsystem. | | `pg_settings_enable_async_append` | Enables the planner's use of async append plans. | | `pg_settings_enable_bitmapscan` | Enables the planner's use of bitmap-scan plans. | | `pg_settings_enable_distinct_reordering` | Enables reordering of DISTINCT keys. | | `pg_settings_enable_gathermerge` | Enables the planner's use of gather merge plans. | | `pg_settings_enable_group_by_reordering` | Enables reordering of GROUP BY keys. | | `pg_settings_enable_hashagg` | Enables the planner's use of hashed aggregation plans. | | `pg_settings_enable_hashjoin` | Enables the planner's use of hash join plans. | | `pg_settings_enable_incremental_sort` | Enables the planner's use of incremental sort steps. | | `pg_settings_enable_indexonlyscan` | Enables the planner's use of index-only-scan plans. | | `pg_settings_enable_indexscan` | Enables the planner's use of index-scan plans. | | `pg_settings_enable_material` | Enables the planner's use of materialization. | | `pg_settings_enable_memoize` | Enables the planner's use of memoization. | | `pg_settings_enable_mergejoin` | Enables the planner's use of merge join plans. | | `pg_settings_enable_nestloop` | Enables the planner's use of nested-loop join plans. | | `pg_settings_enable_parallel_append` | Enables the planner's use of parallel append plans. | | `pg_settings_enable_parallel_hash` | Enables the planner's use of parallel hash plans. | | `pg_settings_enable_partition_pruning` | Enables plan-time and execution-time partition pruning. | | `pg_settings_enable_partitionwise_aggregate` | Enables partitionwise aggregation and grouping. | | `pg_settings_enable_partitionwise_join` | Enables partitionwise join. | | `pg_settings_enable_presorted_aggregate` | Enables the planner's ability to produce plans that provide presorted input for ORDER BY / DISTINCT aggregate functions. | | `pg_settings_enable_self_join_elimination` | Enables removal of unique self-joins. | | `pg_settings_enable_seqscan` | Enables the planner's use of sequential-scan plans. | | `pg_settings_enable_sort` | Enables the planner's use of explicit sort steps. | | `pg_settings_enable_tidscan` | Enables the planner's use of TID scan plans. | | `pg_settings_escape_string_warning` | Warn about backslash escapes in ordinary string literals. | | `pg_settings_event_triggers` | Enables event triggers. | | `pg_settings_exit_on_error` | Terminate session on any error. | | `pg_settings_extra_float_digits` | Sets the number of digits displayed for floating-point values. | | `pg_settings_extwlist_extname_from_filename` | Flag allowing a lookup of extension name in custom script filename. | | `pg_settings_from_collapse_limit` | Sets the FROM-list size beyond which subqueries are not collapsed. | | `pg_settings_fsync` | Forces synchronization of updates to disk. | | `pg_settings_full_page_writes` | Writes full pages to WAL when first modified after a checkpoint. | | `pg_settings_geqo` | Enables genetic query optimization. | | `pg_settings_geqo_effort` | GEQO: effort is used to set the default for other GEQO parameters. | | `pg_settings_geqo_generations` | GEQO: number of iterations of the algorithm. | | `pg_settings_geqo_pool_size` | GEQO: number of individuals in the population. | | `pg_settings_geqo_seed` | GEQO: seed for random path selection. | | `pg_settings_geqo_selection_bias` | GEQO: selective pressure within the population. | | `pg_settings_geqo_threshold` | Sets the threshold of FROM items beyond which GEQO is used. | | `pg_settings_gin_fuzzy_search_limit` | Sets the maximum allowed result for exact search by GIN. | | `pg_settings_gin_pending_list_limit_bytes` | Sets the maximum size of the pending list for GIN index. Units converted to bytes. | | `pg_settings_gss_accept_delegation` | Sets whether GSSAPI delegation should be accepted from the client. | | `pg_settings_hash_mem_multiplier` | Multiple of `work_mem` to use for hash tables. | | `pg_settings_hot_standby` | Allows connections and queries during recovery. | | `pg_settings_hot_standby_feedback` | Allows feedback from a hot standby to the primary that will avoid query conflicts. | | `pg_settings_huge_page_size_bytes` | The size of huge page that should be requested. Units converted to bytes. | | `pg_settings_idle_in_transaction_session_timeout_seconds` | Sets the maximum allowed idle time between queries, when in a transaction. Units converted to seconds. | | `pg_settings_idle_replication_slot_timeout_seconds` | Sets the duration a replication slot can remain idle before it is invalidated. Units converted to seconds. | | `pg_settings_idle_session_timeout_seconds` | Sets the maximum allowed idle time between queries, when not in a transaction. Units converted to seconds. | | `pg_settings_ignore_checksum_failure` | Continues processing after a checksum failure. | | `pg_settings_ignore_invalid_pages` | Continues recovery after an invalid pages failure. | | `pg_settings_ignore_system_indexes` | Disables reading from system indexes. | | `pg_settings_in_hot_standby` | Shows whether hot standby is currently active. | | `pg_settings_integer_datetimes` | Shows whether datetimes are integer based. | | `pg_settings_io_combine_limit_bytes` | Limit on the size of data reads and writes. Units converted to bytes. | | `pg_settings_io_max_combine_limit_bytes` | Server-wide limit that clamps `io_combine_limit`. Units converted to bytes. | | `pg_settings_io_max_concurrency` | Max number of IOs that one process can execute simultaneously. | | `pg_settings_io_workers` | Number of IO worker processes, for `io_method=worker`. | | `pg_settings_jit` | Allow JIT compilation. | | `pg_settings_jit_above_cost` | Perform JIT compilation if query is more expensive. | | `pg_settings_jit_debugging_support` | Register JIT-compiled functions with debugger. | | `pg_settings_jit_dump_bitcode` | Write out LLVM bitcode to facilitate JIT debugging. | | `pg_settings_jit_expressions` | Allow JIT compilation of expressions. | | `pg_settings_jit_inline_above_cost` | Perform JIT inlining if query is more expensive. | | `pg_settings_jit_optimize_above_cost` | Optimize JIT-compiled functions if query is more expensive. | | `pg_settings_jit_profiling_support` | Register JIT-compiled functions with perf profiler. | | `pg_settings_jit_tuple_deforming` | Allow JIT compilation of tuple deforming. | | `pg_settings_join_collapse_limit` | Sets the FROM-list size beyond which JOIN constructs are not flattened. | | `pg_settings_krb_caseins_users` | Sets whether Kerberos and GSSAPI user names should be treated as case-insensitive. | | `pg_settings_lo_compat_privileges` | Enables backward compatibility mode for privilege checks on large objects. | | `pg_settings_lock_timeout_seconds` | Sets the maximum allowed duration of any wait for a lock. Units converted to seconds. | | `pg_settings_log_autovacuum_min_duration_seconds` | Sets the minimum execution time above which autovacuum actions will be logged. Units converted to seconds. | | `pg_settings_log_checkpoints` | Logs each checkpoint. | | `pg_settings_log_disconnections` | Logs end of a session, including duration. | | `pg_settings_log_duration` | Logs the duration of each completed SQL statement. | | `pg_settings_log_executor_stats` | Writes executor performance statistics to the server log. | | `pg_settings_log_file_mode` | Sets the file permissions for log files. | | `pg_settings_log_hostname` | Logs the host name in the connection logs. | | `pg_settings_log_lock_failures` | Logs lock failures. | | `pg_settings_log_lock_waits` | Logs long lock waits. | | `pg_settings_log_min_duration_sample_seconds` | Sets the minimum execution time above which a sample of statements will be logged. Sampling is determined by `log_statement_sample_rate`. Units converted to seconds. | | `pg_settings_log_min_duration_statement_seconds` | Sets the minimum execution time above which all statements will be logged. Units converted to seconds. | | `pg_settings_log_parameter_max_length_bytes` | Sets the maximum length in bytes of data logged for bind parameter values when logging statements. Units converted to bytes. | | `pg_settings_log_parameter_max_length_on_error_bytes` | Sets the maximum length in bytes of data logged for bind parameter values when logging statements, on error. Units converted to bytes. | | `pg_settings_log_parser_stats` | Writes parser performance statistics to the server log. | | `pg_settings_log_planner_stats` | Writes planner performance statistics to the server log. | | `pg_settings_log_recovery_conflict_waits` | Logs standby recovery conflict waits. | | `pg_settings_log_replication_commands` | Logs each replication command. | | `pg_settings_log_rotation_age_seconds` | Sets the amount of time to wait before forcing log file rotation. Units converted to seconds. | | `pg_settings_log_rotation_size_bytes` | Sets the maximum size a log file can reach before being rotated. Units converted to bytes. | | `pg_settings_log_startup_progress_interval_seconds` | Time between progress updates for long-running startup operations. Units converted to seconds. | | `pg_settings_log_statement_sample_rate` | Fraction of statements exceeding `log_min_duration_sample` to be logged. | | `pg_settings_log_statement_stats` | Writes cumulative performance statistics to the server log. | | `pg_settings_log_temp_files_bytes` | Log the use of temporary files larger than this number of kilobytes. Units converted to bytes. | | `pg_settings_log_transaction_sample_rate` | Sets the fraction of transactions from which to log all statements. | | `pg_settings_log_truncate_on_rotation` | Truncate existing log files of same name during log rotation. | | `pg_settings_logging_collector` | Start a subprocess to capture stderr, csvlog and/or jsonlog into log files. | | `pg_settings_logical_decoding_work_mem_bytes` | Sets the maximum memory to be used for logical decoding. Units converted to bytes. | | `pg_settings_maintenance_io_concurrency` | A variant of `effective_io_concurrency` that is used for maintenance work. | | `pg_settings_maintenance_work_mem_bytes` | Sets the maximum memory to be used for maintenance operations. Units converted to bytes. | | `pg_settings_max_active_replication_origins` | Sets the maximum number of active replication origins. | | `pg_settings_max_connections` | Sets the maximum number of concurrent connections. | | `pg_settings_max_files_per_process` | Sets the maximum number of files each server process is allowed to open simultaneously. | | `pg_settings_max_function_args` | Shows the maximum number of function arguments. | | `pg_settings_max_identifier_length` | Shows the maximum identifier length. | | `pg_settings_max_index_keys` | Shows the maximum number of index keys. | | `pg_settings_max_locks_per_transaction` | Sets the maximum number of locks per transaction. | | `pg_settings_max_logical_replication_workers` | Maximum number of logical replication worker processes. | | `pg_settings_max_notify_queue_pages` | Sets the maximum number of allocated pages for NOTIFY / LISTEN queue. | | `pg_settings_max_parallel_apply_workers_per_subscription` | Maximum number of parallel apply workers per subscription. | | `pg_settings_max_parallel_maintenance_workers` | Sets the maximum number of parallel processes per maintenance operation. | | `pg_settings_max_parallel_workers` | Sets the maximum number of parallel workers that can be active at one time. | | `pg_settings_max_parallel_workers_per_gather` | Sets the maximum number of parallel processes per executor node. | | `pg_settings_max_pred_locks_per_page` | Sets the maximum number of predicate-locked tuples per page. | | `pg_settings_max_pred_locks_per_relation` | Sets the maximum number of predicate-locked pages and tuples per relation. | | `pg_settings_max_pred_locks_per_transaction` | Sets the maximum number of predicate locks per transaction. | | `pg_settings_max_prepared_transactions` | Sets the maximum number of simultaneously prepared transactions. | | `pg_settings_max_replication_slots` | Sets the maximum number of simultaneously defined replication slots. | | `pg_settings_max_slot_wal_keep_size_bytes` | Sets the maximum WAL size that can be reserved by replication slots. Units converted to bytes. | | `pg_settings_max_stack_depth_bytes` | Sets the maximum stack depth, in kilobytes. Units converted to bytes. | | `pg_settings_max_standby_archive_delay_seconds` | Sets the maximum delay before canceling queries when a hot standby server is processing archived WAL data. Units converted to seconds. | | `pg_settings_max_standby_streaming_delay_seconds` | Sets the maximum delay before canceling queries when a hot standby server is processing streamed WAL data. Units converted to seconds. | | `pg_settings_max_sync_workers_per_subscription` | Maximum number of table synchronization workers per subscription. | | `pg_settings_max_wal_senders` | Sets the maximum number of simultaneously running WAL sender processes. | | `pg_settings_max_wal_size_bytes` | Sets the WAL size that triggers a checkpoint. Units converted to bytes. | | `pg_settings_max_worker_processes` | Maximum number of concurrent worker processes. | | `pg_settings_md5_password_warnings` | Enables deprecation warnings for MD5 passwords. | | `pg_settings_mem_guard_block` | Block memory allocations in query executing processes if the usage is above limit. | | `pg_settings_mem_guard_enable_auth_hook` | The use the authentication hook to indicate if we should block a pid. | | `pg_settings_mem_guard_enable_explain` | Enable collection of data in explain plans. | | `pg_settings_mem_guard_limit_bytes` | The memory limit for all processes in the container. Units converted to bytes. | | `pg_settings_min_dynamic_shared_memory_bytes` | Amount of dynamic shared memory reserved at startup. Units converted to bytes. | | `pg_settings_min_parallel_index_scan_size_bytes` | Sets the minimum amount of index data for a parallel scan. Units converted to bytes. | | `pg_settings_min_parallel_table_scan_size_bytes` | Sets the minimum amount of table data for a parallel scan. Units converted to bytes. | | `pg_settings_min_wal_size_bytes` | Sets the minimum size to shrink the WAL to. Units converted to bytes. | | `pg_settings_multixact_member_buffers_bytes` | Sets the size of the dedicated buffer pool used for the MultiXact member cache. Units converted to bytes. | | `pg_settings_multixact_offset_buffers_bytes` | Sets the size of the dedicated buffer pool used for the MultiXact offset cache. Units converted to bytes. | | `pg_settings_notify_buffers_bytes` | Sets the size of the dedicated buffer pool used for the LISTEN/NOTIFY message cache. Units converted to bytes. | | `pg_settings_num_os_semaphores` | Shows the number of semaphores required for the server. | | `pg_settings_parallel_leader_participation` | Controls whether Gather and Gather Merge also run subplans. | | `pg_settings_parallel_setup_cost` | Sets the planner's estimate of the cost of starting up worker processes for parallel query. | | `pg_settings_parallel_tuple_cost` | Sets the planner's estimate of the cost of passing each tuple (row) from worker to leader backend. | | `pg_settings_pg_prewarm_autoprewarm` | Starts the autoprewarm worker. | | `pg_settings_pg_prewarm_autoprewarm_interval_seconds` | Sets the interval between dumps of shared buffers. Units converted to seconds. | | `pg_settings_pg_stat_statements_max` | Sets the maximum number of statements tracked by `pg_stat_statements`. | | `pg_settings_pg_stat_statements_save` | Save `pg_stat_statements` statistics across server shutdowns. | | `pg_settings_pg_stat_statements_track_planning` | Selects whether planning duration is tracked by `pg_stat_statements`. | | `pg_settings_pg_stat_statements_track_utility` | Selects whether utility commands are tracked by `pg_stat_statements`. | | `pg_settings_pgaudit_log_catalog` | Specifies that session logging should be enabled in the case where all relations in a statement are in `pg_catalog`. Disabling this setting will reduce noise in the log from tools like psql and PgAdmin that query the catalog heavily. | | `pg_settings_pgaudit_log_client` | Specifies whether audit messages should be visible to the client. This setting should generally be left disabled but may be useful for debugging or other purposes. | | `pg_settings_pgaudit_log_parameter` | Specifies that audit logging should include the parameters that were passed with the statement. When parameters are present they will be included in CSV format after the statement text. | | `pg_settings_pgaudit_log_parameter_max_size` | Specifies, in bytes, the maximum length of variable-length parameters to log. If 0 (the default), parameters are not checked for size. If set, when the size of the parameter is longer than the setting, the value in the audit log is replaced with a placeholder. Note that for character types, the length is in bytes for the parameter's encoding, not characters. | | `pg_settings_pgaudit_log_relation` | Specifies whether session audit logging should create a separate log entry for each relation referenced in a SELECT or DML statement. This is a useful shortcut for exhaustive logging without using object audit logging. | | `pg_settings_pgaudit_log_rows` | Specifies whether logging will include the rows retrieved or affected by a statement. | | `pg_settings_pgaudit_log_statement` | Specifies whether logging will include the statement text and parameters. Depending on requirements, the full statement text might not be required in the audit log. | | `pg_settings_pgaudit_log_statement_once` | Specifies whether logging will include the statement text and parameters with the first log entry for a statement/substatement combination or with every entry. Enabling this setting will result in less verbose logging but may make it more difficult to determine the statement that generated a log entry, though the statement/substatement pair along with the process id should suffice to identify the statement text logged with a previous entry. | | `pg_settings_port` | Sets the TCP port the server listens on. | | `pg_settings_post_auth_delay_seconds` | Sets the amount of time to wait after authentication on connection startup. Units converted to seconds. | | `pg_settings_pre_auth_delay_seconds` | Sets the amount of time to wait before authentication on connection startup. Units converted to seconds. | | `pg_settings_quote_all_identifiers` | When generating SQL fragments, quote all identifiers. | | `pg_settings_random_page_cost` | Sets the planner's estimate of the cost of a nonsequentially fetched disk page. | | `pg_settings_recovery_min_apply_delay_seconds` | Sets the minimum delay for applying changes during recovery. Units converted to seconds. | | `pg_settings_recovery_target_inclusive` | Sets whether to include or exclude transaction with recovery target. | | `pg_settings_recursive_worktable_factor` | Sets the planner's estimate of the average size of a recursive query's working table. | | `pg_settings_remove_temp_files_after_crash` | Remove temporary files after backend crash. | | `pg_settings_reserved_connections` | Sets the number of connection slots reserved for roles with privileges of `pg_use_reserved_connections`. | | `pg_settings_restart_after_crash` | Reinitialize server after backend crash. | | `pg_settings_row_security` | Enables row security. | | `pg_settings_scram_iterations` | Sets the iteration count for SCRAM secret generation. | | `pg_settings_segment_size_bytes` | Shows the number of pages per disk file. Units converted to bytes. | | `pg_settings_send_abort_for_crash` | Send SIGABRT not SIGQUIT to child processes after backend crash. | | `pg_settings_send_abort_for_kill` | Send SIGABRT not SIGKILL to stuck child processes. | | `pg_settings_seq_page_cost` | Sets the planner's estimate of the cost of a sequentially fetched disk page. | | `pg_settings_serializable_buffers_bytes` | Sets the size of the dedicated buffer pool used for the serializable transaction cache. Units converted to bytes. | | `pg_settings_server_version_num` | Shows the server version as an integer. | | `pg_settings_shared_buffers_bytes` | Sets the number of shared memory buffers used by the server. Units converted to bytes. | | `pg_settings_shared_memory_size_bytes` | Shows the size of the server's main shared memory area (rounded up to the nearest MB). Units converted to bytes. | | `pg_settings_shared_memory_size_in_huge_pages` | Shows the number of huge pages needed for the main shared memory area. | | `pg_settings_ssl` | Enables SSL connections. | | `pg_settings_ssl_passphrase_command_supports_reload` | Controls whether `ssl_passphrase_command` is called during server reload. | | `pg_settings_ssl_prefer_server_ciphers` | Give priority to server ciphersuite order. | | `pg_settings_standard_conforming_strings` | Causes '...' strings to treat backslashes literally. | | `pg_settings_statement_timeout_seconds` | Sets the maximum allowed duration of any statement. Units converted to seconds. | | `pg_settings_subtransaction_buffers_bytes` | Sets the size of the dedicated buffer pool used for the subtransaction cache. Units converted to bytes. | | `pg_settings_summarize_wal` | Starts the WAL summarizer process to enable incremental backup. | | `pg_settings_superuser_reserved_connections` | Sets the number of connection slots reserved for superusers. | | `pg_settings_sync_replication_slots` | Enables a physical standby to synchronize logical failover replication slots from the primary server. | | `pg_settings_synchronize_seqscans` | Enables synchronized sequential scans. | | `pg_settings_syslog_sequence_numbers` | Add sequence number to syslog messages to avoid duplicate suppression. | | `pg_settings_syslog_split_messages` | Split messages sent to syslog by lines and to fit into 1024 bytes. | | `pg_settings_tcp_keepalives_count` | Maximum number of TCP keepalive retransmits. | | `pg_settings_tcp_keepalives_idle_seconds` | Time between issuing TCP keepalives. Units converted to seconds. | | `pg_settings_tcp_keepalives_interval_seconds` | Time between TCP keepalive retransmits. Units converted to seconds. | | `pg_settings_tcp_user_timeout_seconds` | TCP user timeout. Units converted to seconds. | | `pg_settings_temp_buffers_bytes` | Sets the maximum number of temporary buffers used by each session. Units converted to bytes. | | `pg_settings_temp_file_limit_bytes` | Limits the total size of all temporary files used by each process. Units converted to bytes. | | `pg_settings_timescaledb_bgw_launcher_poll_time` | Launcher timeout value in milliseconds. | | `pg_settings_timescaledb_bgw_scheduler_restart_time_seconds` | Restart time for scheduler. Units converted to seconds. | | `pg_settings_timescaledb_disable_load` | Disable the loading of the actual extension. | | `pg_settings_timescaledb_lake_disable_load` | Disable the loading of the actual extension. | | `pg_settings_timescaledb_max_background_workers` | Maximum background worker processes allocated to TimescaleDB | | `pg_settings_timescaledb_osm_disable_load` | Disable the loading of the actual extension. | | `pg_settings_trace_connection_negotiation` | Logs details of pre-authentication connection handshake. | | `pg_settings_trace_notify` | Generates debugging output for LISTEN and NOTIFY. | | `pg_settings_trace_sort` | Emit information about resource usage in sorting. | | `pg_settings_track_activities` | Collects information about executing commands. | | `pg_settings_track_activity_query_size_bytes` | Sets the size reserved for `pg_stat_activity`.query, in bytes. Units converted to bytes. | | `pg_settings_track_commit_timestamp` | Collects transaction commit time. | | `pg_settings_track_cost_delay_timing` | Collects timing statistics for cost-based vacuum delay. | | `pg_settings_track_counts` | Collects statistics on database activity. | | `pg_settings_track_io_timing` | Collects timing statistics for database I/O activity. | | `pg_settings_track_wal_io_timing` | Collects timing statistics for WAL I/O activity. | | `pg_settings_transaction_buffers_bytes` | Sets the size of the dedicated buffer pool used for the transaction status cache. Units converted to bytes. | | `pg_settings_transaction_deferrable` | Whether to defer a read-only serializable transaction until it can be executed with no possible serialization failures. | | `pg_settings_transaction_read_only` | Sets the current transaction's read-only status. | | `pg_settings_transaction_timeout_seconds` | Sets the maximum allowed duration of any transaction within a session (not a prepared transaction). Units converted to seconds. | | `pg_settings_transform_null_equals` | Treats "expr=NULL" as "expr IS NULL". | | `pg_settings_ts_stat_statements_enable_auth_hook` | Selects whether the auth hook is intercepted by ts\_stat\_statements. | | `pg_settings_ts_stat_statements_enable_log_hook` | Selects whether the log hook is intercepted by ts\_stat\_statements. | | `pg_settings_ts_stat_statements_enable_mem_guard_stats` | Enable reading memory stats from mem\_guard. | | `pg_settings_ts_stat_statements_enable_regression_debug` | Enable debug messages for regression tests. | | `pg_settings_ts_stat_statements_enable_system_stats` | Enable system stat collections. | | `pg_settings_ts_stat_statements_explain_bound` | When tracking, capture an explain plan for queries running longer than this many milliseconds. | | `pg_settings_ts_stat_statements_track_planning` | Selects whether planning duration is tracked by ts\_stat\_statements. | | `pg_settings_ts_stat_statements_track_utility` | Selects whether utility commands are tracked by ts\_stat\_statements. | | `pg_settings_tsdb_admin_read_only_connection` | Enable immutable read-only mode for this connection. | | `pg_settings_tsdb_admin_read_only_role` | Enable immutable read-only mode for this role. | | `pg_settings_unix_socket_permissions` | Sets the access permissions of the Unix-domain socket. | | `pg_settings_update_process_title` | Updates the process title to show the active SQL command. | | `pg_settings_vacuum_buffer_usage_limit_bytes` | Sets the buffer pool size for VACUUM, ANALYZE, and autovacuum. Units converted to bytes. | | `pg_settings_vacuum_cost_delay_seconds` | Vacuum cost delay in milliseconds. Units converted to seconds. | | `pg_settings_vacuum_cost_limit` | Vacuum cost amount available before napping. | | `pg_settings_vacuum_cost_page_dirty` | Vacuum cost for a page dirtied by vacuum. | | `pg_settings_vacuum_cost_page_hit` | Vacuum cost for a page found in the buffer cache. | | `pg_settings_vacuum_cost_page_miss` | Vacuum cost for a page not found in the buffer cache. | | `pg_settings_vacuum_failsafe_age` | Age at which VACUUM should trigger failsafe to avoid a wraparound outage. | | `pg_settings_vacuum_freeze_min_age` | Minimum age at which VACUUM should freeze a table row. | | `pg_settings_vacuum_freeze_table_age` | Age at which VACUUM should scan whole table to freeze tuples. | | `pg_settings_vacuum_max_eager_freeze_failure_rate` | Fraction of pages in a relation vacuum can scan and fail to freeze before disabling eager scanning. | | `pg_settings_vacuum_multixact_failsafe_age` | Multixact age at which VACUUM should trigger failsafe to avoid a wraparound outage. | | `pg_settings_vacuum_multixact_freeze_min_age` | Minimum age at which VACUUM should freeze a MultiXactId in a table row. | | `pg_settings_vacuum_multixact_freeze_table_age` | Multixact age at which VACUUM should scan whole table to freeze tuples. | | `pg_settings_vacuum_truncate` | Enables vacuum to truncate empty pages at the end of the table. | | `pg_settings_wal_block_size` | Shows the block size in the write ahead log. | | `pg_settings_wal_buffers_bytes` | Sets the number of disk-page buffers in shared memory for WAL. Units converted to bytes. | | `pg_settings_wal_decode_buffer_size_bytes` | Buffer size for reading ahead in the WAL during recovery. Units converted to bytes. | | `pg_settings_wal_init_zero` | Writes zeroes to new WAL files before first use. | | `pg_settings_wal_keep_size_bytes` | Sets the size of WAL files held for standby servers. Units converted to bytes. | | `pg_settings_wal_log_hints` | Writes full pages to WAL when first modified after a checkpoint, even for a non-critical modification. | | `pg_settings_wal_receiver_create_temp_slot` | Sets whether a WAL receiver should create a temporary replication slot if no permanent slot is configured. | | `pg_settings_wal_receiver_status_interval_seconds` | Sets the maximum interval between WAL receiver status reports to the sending server. Units converted to seconds. | | `pg_settings_wal_receiver_timeout_seconds` | Sets the maximum wait time to receive data from the sending server. Units converted to seconds. | | `pg_settings_wal_recycle` | Recycles WAL files by renaming them. | | `pg_settings_wal_retrieve_retry_interval_seconds` | Sets the time to wait before retrying to retrieve WAL after a failed attempt. Units converted to seconds. | | `pg_settings_wal_segment_size_bytes` | Shows the size of write ahead log segments. Units converted to bytes. | | `pg_settings_wal_sender_timeout_seconds` | Sets the maximum time to wait for WAL replication. Units converted to seconds. | | `pg_settings_wal_skip_threshold_bytes` | Minimum size of new file to fsync instead of writing WAL. Units converted to bytes. | | `pg_settings_wal_summary_keep_time_seconds` | Time for which WAL summary files should be kept. Units converted to seconds. | | `pg_settings_wal_writer_delay_seconds` | Time between WAL flushes performed in the WAL writer. Units converted to seconds. | | `pg_settings_wal_writer_flush_after_bytes` | Amount of WAL written out by WAL writer that triggers a flush. Units converted to bytes. | | `pg_settings_work_mem_bytes` | Sets the maximum memory to be used for query workspaces. Units converted to bytes. | | `pg_settings_zero_damaged_pages` | Continues processing past damaged page headers. | ### PostgreSQL statistics metrics These metrics come from PostgreSQL's internal statistics collector and include connection counts, transaction throughput, buffer usage, replication state, and database-level I/O. Note Metrics in the `pg_stat_database_*` family, along with `pg_stat_activity_count` and `pg_locks_count`, are emitted per database and carry a `datname` label. Your service's application data lives in the `tsdb` database, so filter on `datname="tsdb"` to see your own workload. | Metric | Description | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pg_stat_activity_count` | Number of connections in this state. | | `pg_stat_activity_max_tx_duration` | Max duration in seconds any active transaction has been running. | | `pg_stat_archiver_archived_count_total` | Number of WAL files that have been successfully archived. | | `pg_stat_archiver_failed_count_total` | Number of failed attempts for archiving WAL files. | | `pg_stat_archiver_last_archive_age` | Time in seconds since last WAL segment was successfully archived. | | `pg_stat_bgwriter_buffers_alloc_total` | Number of buffers allocated. | | `pg_stat_bgwriter_buffers_clean_total` | Number of buffers written by the background writer. | | `pg_stat_bgwriter_maxwritten_clean_total` | Number of times the background writer stopped a cleaning scan because it had written too many buffers. | | `pg_stat_bgwriter_stats_reset_total` | Time at which these statistics were last reset. | | `pg_stat_database_active_time` | Unknown metric from `pg_stat_database`. | | `pg_stat_database_blk_read_time_total` | Time spent reading data file blocks by backends in this database, in milliseconds. | | `pg_stat_database_blk_write_time_total` | Time spent writing data file blocks by backends in this database, in milliseconds. | | `pg_stat_database_blks_hit_total` | Number of times disk blocks were found already in the buffer cache, so that a read was not necessary (this only includes hits in the PostgreSQL buffer cache, not the operating system's file system cache). | | `pg_stat_database_blks_read_total` | Number of disk blocks read in this database. | | `pg_stat_database_checksum_failures` | Unknown metric from `pg_stat_database`. | | `pg_stat_database_checksum_last_failure` | Unknown metric from `pg_stat_database`. | | `pg_stat_database_conflicts_confl_active_logicalslot` | Unknown metric from `pg_stat_database_conflicts`. | | `pg_stat_database_conflicts_confl_bufferpin_total` | Number of queries in this database that have been canceled due to pinned buffers. | | `pg_stat_database_conflicts_confl_deadlock_total` | Number of queries in this database that have been canceled due to deadlocks. | | `pg_stat_database_conflicts_confl_lock_total` | Number of queries in this database that have been canceled due to lock timeouts. | | `pg_stat_database_conflicts_confl_snapshot_total` | Number of queries in this database that have been canceled due to old snapshots. | | `pg_stat_database_conflicts_confl_tablespace_total` | Number of queries in this database that have been canceled due to dropped tablespaces. | | `pg_stat_database_conflicts_total` | Number of queries canceled due to conflicts with recovery in this database. (Conflicts occur only on standby servers; see `pg_stat_database_conflicts` for details.) | | `pg_stat_database_deadlocks_total` | Number of deadlocks detected in this database. | | `pg_stat_database_idle_in_transaction_time` | Unknown metric from `pg_stat_database`. | | `pg_stat_database_numbackends` | Number of backends currently connected to this database. This is the only column in this view that returns a value reflecting current state; all other columns return the accumulated values since the last reset. | | `pg_stat_database_parallel_workers_launched` | Unknown metric from `pg_stat_database`. | | `pg_stat_database_parallel_workers_to_launch` | Unknown metric from `pg_stat_database`. | | `pg_stat_database_session_time` | Unknown metric from `pg_stat_database`. | | `pg_stat_database_sessions` | Unknown metric from `pg_stat_database`. | | `pg_stat_database_sessions_abandoned` | Unknown metric from `pg_stat_database`. | | `pg_stat_database_sessions_fatal` | Unknown metric from `pg_stat_database`. | | `pg_stat_database_sessions_killed` | Unknown metric from `pg_stat_database`. | | `pg_stat_database_stats_reset_total` | Time at which these statistics were last reset. | | `pg_stat_database_temp_bytes_total` | Total amount of data written to temporary files by queries in this database. All temporary files are counted, regardless of why the temporary file was created, and regardless of the `log_temp_files` setting. | | `pg_stat_database_temp_files_total` | Number of temporary files created by queries in this database. All temporary files are counted, regardless of why the temporary file was created (e.g., sorting or hashing), and regardless of the `log_temp_files` setting. | | `pg_stat_database_tup_deleted_total` | Number of rows deleted by queries in this database. | | `pg_stat_database_tup_fetched_total` | Number of rows fetched by queries in this database. | | `pg_stat_database_tup_inserted_total` | Number of rows inserted by queries in this database. | | `pg_stat_database_tup_returned_total` | Number of rows returned by queries in this database. | | `pg_stat_database_tup_updated_total` | Number of rows updated by queries in this database. | | `pg_stat_database_xact_commit_total` | Number of transactions in this database that have been committed. | | `pg_stat_database_xact_rollback_total` | Number of transactions in this database that have been rolled back. | | `pg_stat_replication_pg_current_wal_lsn_bytes` | WAL position in bytes. | | `pg_stat_replication_pg_wal_lsn_diff` | Lag in bytes between primary and replica. | | `pg_stat_replication_reply_time` | Timestamp of the last reply message received from the standby server. | | `pg_static` | Version string as reported by PostgreSQL. | | `pg_up` | Whether the last scrape of metrics from PostgreSQL was able to connect to the server (1 for yes, 0 for no). | ## Aggregation functions `--fn` (CLI) and `fn` (Tiger MCP) pick how the raw samples in each bucket collapse into one value, and, when a query matches more than one labeled series (for example every replica, or every database), how those series combine. Each metric has its own sensible default, and it varies by metric: check it with [`service metrics details`](#tiger-service-metrics-details) (**Default Aggregation**) rather than assuming one. Omit `--fn`/`fn` to use that default. | Function | What it computes | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `LAST` | The last raw value in the bucket, summed across every matching series. Also the fallback when a metric declares no default of its own. Summing is why an unfiltered query against a service with replicas silently adds the primary's last value to every replica's, so narrow with `--role`/`role` or `--filter`/`filters` first. | | `SUM` | Total of all raw samples in the bucket, across every matching series. | | `AVG` | Average of all raw samples in the bucket, across every matching series (a weighted average, not an average of each series' own average). | | `COUNT` | Number of raw samples that landed in the bucket, across every matching series. | | `MIN`, `MAX` | The single most extreme raw value seen anywhere among the matching series, not the peak of their total. | | `MIN_TOTAL`, `MAX_TOTAL` | Sum every matching series together first, then take the minimum or maximum of *that combined series* across the bucket. The right choice for "did combined usage ever spike" (for example total connections across every database). Roughly Prometheus' `min_over_time(sum(...))` / `max_over_time(sum(...))`, rather than `min()`/`max()` alone. | | `RATE`, `INCREASE` | Per-second rate, or total increase, over the bucket, for ever-increasing counters (for example `pg_stat_database_xact_commit_total`). Counter-reset aware and interpolated at the bucket boundaries, matching Prometheus' `rate()`/`increase()`. | | `P50`, `P90`, `P99` | Approximate percentile of the raw samples in the bucket, computed from a sketch rather than Prometheus-style histogram buckets (closer to `quantile_over_time()` than `histogram_quantile()`). | ## Configuration parameters By default, Tiger CLI stores your configuration in `~/.config/tiger/config.yaml`. Change the config directory with the `--config-dir` flag or the `TIGER_CONFIG_DIR` environment variable. ### Configuration options Set these with `tiger config set `: | Key | Default | Description | | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `analytics` | `true` | Enable or disable usage analytics | | `color` | `true` | Enable or disable colored output | | `docs_mcp` | `true` | Enable or disable the Tiger Data documentation MCP proxy | | `mcp_max_rows` | `100` | Set the maximum number of rows returned by the `db_query` Tiger MCP tool | | `output` | `table` | Set the output format to `json`, `yaml`, or `table` | | `password_storage` | `keyring` | Set the password storage method. Options are `keyring`, `pgpass`, or `none` | | `read_only` | `off` | Which services to protect from writes: `all` protects every service, `prod` protects only services tagged `PROD`, and `off` protects none. For a protected service, mutating `tiger service` commands and the matching Tiger MCP tools (`create`, `fork`, `start`, `stop`, `resize`, `update-password`, and `delete`), plus `db create role`, are refused, and the database sessions opened by `db psql`, `db query`, `db uri`, and the `db_query` Tiger MCP tool run in Tiger Cloud's immutable read-only mode, so writes and DDL are rejected by the server. Read commands and tools are unaffected. A read replica set is judged on its own environment tag, not its primary's. The legacy boolean values still work: `true` means `all` and `false` means `off` | | `service_id` | - | Set the default service to manage | | `version_check` | `true` | Enable or disable checking for a new version of Tiger CLI on startup | You can also set these configuration options as environment variables. Environment variables: - Take precedence over configuration parameters values. - Are in upper case and use the `TIGER_` prefix. For example, `TIGER_ANALYTICS` ### Global flags These flags are available on all commands and take precedence over both environment variables and configuration file values: | Flag | Default | Description | | -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ | | `--analytics` | `true` | Enable or disable usage analytics | | `--color` | `true` | Enable or disable colored output | | `--config-dir` | `~/.config/tiger` | Set the directory that holds `config.yaml` | | `--help`, `-h` | - | Print help about the current command. For example, `tiger service --help` | | `--password-storage` | `keyring` | Set the password storage method. Options are `keyring`, `pgpass`, or `none` | | `--service-id` | - | Set the default service to manage | | `--version-check` | `true` | Enable or disable checking for a new version of Tiger CLI on startup. To disable the check, pass `--version-check=false` | In Tiger CLI 0.24, `--version-check` replaced the `--skip-update-check` flag; the old flag still works as a hidden alias for backwards compatibility. ### Authentication parameters You can authenticate using client credentials instead of interactive browser login. Client credentials are a public key and secret key pair that you create in the Tiger Cloud Console. [Learn how to create client credentials](/docs/integrate/find-connection-details#create-client-credentials/index.md). Once you have your credentials, either set them as environment variables, then log in: Terminal window ``` TIGER_PUBLIC_KEY= TIGER_SECRET_KEY= \ tiger auth login ``` Or pass them to the `login` command: Terminal window ``` tiger auth login --public-key= --secret-key= ``` The project is auto-detected from your credentials.