CockroachDB Workload Export Tool

A command-line tool that exports workload data from a CockroachDB cluster into a portable zip file for analysis and troubleshooting.

What It Does

The workload-exporter creates a complete snapshot of your cluster's workload characteristics, including:

Statement and transaction statistics - Query performance and execution patterns
Contention events - Lock contention and blocking queries
Cluster metadata - Version, configuration, and node topology
Database schemas - Table structures and definitions
Zone configurations - Replication and placement settings
Table indexes - Index definitions and descriptor IDs

This data can be analyzed locally or shared with Cockroach Labs support for troubleshooting.

Installation

Download Pre-Built Binary

Download the latest release for your platform from the Releases Page, or use the commands below.

Set the version variable first, then run the command for your platform:

VERSION=v1.11.0  # replace with the desired release tag

macOS (Apple Silicon)

curl -L "https://github.com/cockroachlabs/workload-exporter/releases/download/${VERSION}/workload-exporter-${VERSION}-darwin-arm64.tar.gz" | tar xz
mv "workload-exporter-${VERSION}-darwin-arm64" workload-exporter

macOS (Intel)

curl -L "https://github.com/cockroachlabs/workload-exporter/releases/download/${VERSION}/workload-exporter-${VERSION}-darwin-amd64.tar.gz" | tar xz
mv "workload-exporter-${VERSION}-darwin-amd64" workload-exporter

Linux (amd64)

curl -L "https://github.com/cockroachlabs/workload-exporter/releases/download/${VERSION}/workload-exporter-${VERSION}-linux-amd64.tar.gz" | tar xz
mv "workload-exporter-${VERSION}-linux-amd64" workload-exporter

Linux (arm64)

curl -L "https://github.com/cockroachlabs/workload-exporter/releases/download/${VERSION}/workload-exporter-${VERSION}-linux-arm64.tar.gz" | tar xz
mv "workload-exporter-${VERSION}-linux-arm64" workload-exporter

Windows

Download workload-exporter-${VERSION}-windows-amd64.zip from the releases page and extract it.

Verify Installation

./workload-exporter version

Updating

Update to the latest release in-place:

./workload-exporter update

Check if a newer version is available without installing:

./workload-exporter update --check

Quick Start

Basic Export

Export the last 2 hours of workload data (default):

./workload-exporter export \
  --url "postgresql://user:password@host:26257/?sslmode=verify-full"

This creates workload-export.zip in the current directory.

Export Specific Time Range

Export data for a specific time period:

./workload-exporter export \
  --url "postgresql://user:password@host:26257/?sslmode=verify-full" \
  -s "2025-04-18T13:00:00Z" \
  -e "2025-04-18T20:00:00Z" \
  -o "incident-export.zip"

Connecting to a Cluster

The connection flags are intentionally compatible with cockroach sql. If you already know how to connect with cockroach sql, the same flags and environment variables work here.

Using a Connection URL

./workload-exporter export --url "postgresql://user:password@host:26257/defaultdb?sslmode=verify-full"

The COCKROACH_URL environment variable is also supported:

export COCKROACH_URL="postgresql://user:password@host:26257/defaultdb?sslmode=verify-full"
./workload-exporter export

Using Discrete Flags

Individual connection flags can be used instead of a URL:

./workload-exporter export \
  --host my-cluster.example.com \
  --port 26257 \
  --user myuser \
  --database mydb \
  --certs-dir /path/to/certs

For insecure clusters:

./workload-exporter export --host localhost --insecure

Environment Variables

Each discrete flag has a corresponding COCKROACH_* environment variable, matching cockroach sql conventions:

Flag	Environment Variable	Default
`--url`	`COCKROACH_URL`	—
`--user`	`COCKROACH_USER`	`root`
`--password`	`COCKROACH_PASSWORD`	—
`--database`	`COCKROACH_DATABASE`	—
`--insecure`	`COCKROACH_INSECURE`	`false`
`--certs-dir`	`COCKROACH_CERTS_DIR`	`~/.cockroach-certs`

Note: Prefer COCKROACH_PASSWORD over --password in scripts — flag values are visible in the process list.

Connection Priority

When multiple connection options are provided, the following priority applies:

--url flag
COCKROACH_URL environment variable
Discrete flags (--host, --port, --user, --database, --insecure, --certs-dir) with COCKROACH_* env var fallbacks

TLS Behavior (discrete flags)

When connecting via discrete flags without --insecure, the tool checks --certs-dir (default ~/.cockroach-certs) for certificate files and selects the appropriate SSL mode:

Certs found	SSL mode
`ca.crt` + `client.<user>.crt` + `client.<user>.key`	`verify-full` with all certs
`ca.crt` only	`verify-full` with root cert
None	`require`

Command Options

Flags:
      --url string              Connection URL (env: COCKROACH_URL)
      --host string             Database host (default "localhost")
      --port int                Database port (default 26257)
  -u, --user string             Database user (default "root") (env: COCKROACH_USER)
      --password string         Database password (env: COCKROACH_PASSWORD)
  -d, --database string         Database name (env: COCKROACH_DATABASE)
      --insecure                Connect without TLS (env: COCKROACH_INSECURE)
      --certs-dir string        Path to certificate directory (default "~/.cockroach-certs") (env: COCKROACH_CERTS_DIR)
  -o, --output-file string      Output zip file (default: "workload-export.zip")
  -s, --start string            Start time in RFC3339 format (default: 2 hours ago)
  -e, --end string              End time in RFC3339 format (default: 1 hour from now)
      --debug                   Enable debug logging

Deprecated: The -c / --connection-url flag is deprecated. Use --url instead.

What Data is Collected

The export creates a zip file containing the following files:

Metadata

metadata.json - Cluster version, ID, name, organization, export configuration, whether the cluster is a virtual cluster, and Active Session History availability and settings (ash)
- ⚠️ Note: Connection string password is automatically redacted

Statistics (CSV format, time-filtered)

crdb_internal.statement_statistics.csv - SQL statement execution stats
crdb_internal.transaction_statistics.csv - Transaction execution stats
crdb_internal.transaction_contention_events.csv - Lock contention events
crdb_internal.gossip_nodes.csv - Node information and topology
crdb_internal.node_cpu_mem.csv - Per-node vCPU count and total memory (derived from kv_node_status)
crdb_internal.table_indexes.csv - Table and index descriptor IDs across all databases
crdb_internal.index_usage_statistics.csv - Index usage counters across all databases
system.table_statistics.csv - Optimizer table statistics (column-level stats used by the query planner)

Statistics files only include data within the specified time range

Active Session History (CockroachDB 26.2+, CSV format, time-filtered)

Active Session History (ASH) samples what active sessions are doing and what each sample was waiting on. It is exported only when the cluster provides it — the exporter probes for the ASH views rather than assuming a version, and clusters without ASH are skipped with a log message.

information_schema.crdb_persisted_active_session_history.csv - Persisted ASH samples (CockroachDB 26.3+), retained for obs.ash.compaction.retention_period (7 days by default)
information_schema.crdb_cluster_active_session_history.csv - Cluster-wide in-memory ASH samples (CockroachDB 26.2+), including recent samples not yet flushed to the persisted table

metadata.json records what was found under the ash key: available, the obs.ash.* settings (enabled, enrichment_enabled, sample_interval, retention_period, response_limit, buffer_size), views (the ASH views the cluster exposes) and exported_views (the subset that produced a CSV). A setting the exporter could not read is recorded as null rather than false, so "sampling was off" is never confused with "could not tell". A view listed in views but not in exported_views exists in the cluster but could not be read, and has no file in the export.

Notes:

ASH sampling is off by default in 26.2 (obs.ash.enabled) and on by default in 26.3. When it is off, the exported files contain only a header row and the exporter logs a warning.
Statement text in ASH is a fingerprint, with literals replaced by _, the same form used in crdb_internal.statement_statistics.
Per-execution columns (user, plan_gist, canary_stats, txn_id, session_id) require enrichment, which is 26.3+ only — 26.2 has no obs.ash.enrichment.enabled setting and the columns are always NULL there. Enrichment is off by default in 26.3 (so the columns are NULL unless it was explicitly enabled) and on by default in 26.4.
ASH is sampled every second per active session, so a wide time range on a busy cluster can produce a large export. Narrow --start/--end if export size is a concern.
Unlike the SQL statistics tables, whose time range is widened to whole-hour boundaries to match the aggregation interval, ASH is exported for exactly the requested --start/--end.
On clusters without persisted ASH (26.2), historical time ranges may export nothing. The in-memory cluster view is served by a fan-out that returns each node's newest obs.ash.response_limit samples (10,000 by default) before the time-range filter is applied, so it cannot reach further back than those samples span — minutes on a quiet cluster, seconds on a busy one. A range ending outside that horizon produces a header-only CSV rather than an error; the exporter warns when it detects this. Clusters on 26.3+ are unaffected, because the persisted view filters normally.

Schema Information

[database_name].schema.txt - CREATE statements for all tables in each database
- One file per user database (system databases excluded)

Configuration

zone_configurations.txt - All zone configuration SQL statements
crdb_internal.cluster_settings.csv - All cluster settings and their current values
system.settings.csv - Cluster settings that have been changed from defaults, including timestamps of when they changed
⚠️ Sensitive settings (credentials, keys, PEM data) are automatically redacted to <redacted> in both files

In virtualized clusters, settings are exported for each virtual cluster separately:

crdb_internal.cluster_settings.csv / system.settings.csv — application virtual cluster
crdb_internal.cluster_settings.system.csv / system.settings.system.csv — system virtual cluster

Inspecting the Export

The export is a standard zip file that you can inspect before sharing:

# List all files in the export
unzip -l workload-export.zip

# Extract to a directory
unzip workload-export.zip -d export-contents

# View the metadata
cat export-contents/metadata.json | jq .

# Preview statistics (first 10 lines)
head export-contents/crdb_internal.statement_statistics.csv

# Check what schemas were exported
ls export-contents/*.schema.txt

All data is in plain text format (JSON, CSV, SQL) and can be reviewed before sharing with Cockroach Labs or others.

Privacy and Security

Passwords are redacted - Connection string passwords are automatically removed from metadata
Sensitive settings are redacted - Cluster settings containing credentials, keys, or PEM data (e.g. enterprise.license, cluster.secret, LDAP/OIDC/JWT config) are exported as <redacted>
No query parameters - Statement statistics include query fingerprints, not actual parameter values
Schema only - Table schemas are exported, but no actual table data is included
Read-only - The tool only reads data and makes no modifications to your cluster
Local export - All data is written to a local zip file under your control
Verified updates - workload-exporter update verifies the SHA256 checksum of the downloaded binary against the checksums published with each GitHub release before installing

Requirements

CockroachDB version: 24.1 or later
Network access to the CockroachDB cluster
User permissions:
- Read access to crdb_internal tables
- Read access to system settings
- Read access to user databases (for schema export)
- Recommended: Admin role for simplest setup

Virtual Cluster Support

Virtualized CockroachDB clusters (those with a system virtual cluster and one or more application virtual clusters) are supported. Connect using the URL for the application virtual cluster (typically named main) — the tool automatically detects the virtualized deployment and opens a second connection to the system virtual cluster to retrieve cluster-wide data such as node topology.

Note: The user account must have access to both the system virtual cluster and the application virtual cluster. If your user exists only in the application virtual cluster, system-level data (such as gossip_nodes) will be unavailable.

Grant Permissions

For simplest setup, grant admin role:

GRANT admin TO your_user;

For more restrictive permissions, see docs/TROUBLESHOOTING.md.

Common Use Cases

Troubleshooting Performance Issues

# Export data from when the issue occurred
./workload-exporter export \
  --url "postgresql://user:password@host:26257/?sslmode=verify-full" \
  -s "2025-04-18T14:00:00Z" \
  -e "2025-04-18T16:00:00Z" \
  -o "performance-issue.zip"

Daily Workload Snapshot

# Export the last 24 hours
./workload-exporter export \
  --url "postgresql://user:password@host:26257/?sslmode=verify-full" \
  -s "$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)" \
  -e "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -o "daily-$(date +%Y%m%d).zip"

Pre-Migration Baseline

# Capture workload before a migration
./workload-exporter export \
  --url "postgresql://user:password@host:26257/?sslmode=verify-full" \
  -o "pre-migration-baseline.zip"

Getting Help

Troubleshooting

See docs/TROUBLESHOOTING.md for solutions to common issues:

Connection problems
Permission errors
Time format issues
Empty exports

Enable Debug Logging

For detailed information about what the tool is doing:

./workload-exporter export --url "postgresql://user:password@host:26257/?sslmode=verify-full" --debug

Support

Issues: GitHub Issues
Cockroach Labs Support: Share the generated zip file with your support ticket

Additional Documentation

Version Compatibility - Supported CockroachDB versions and version-specific behavior
Troubleshooting Guide - Solutions to common issues
Development Guide - Building from source and contributing
Library Usage - Using workload-exporter as a Go library
Testing Guide - Running tests and integration tests

License

MIT License

Note: This tool is designed for CockroachDB clusters. For CockroachDB 26.1+, the tool automatically handles the required allow_unsafe_internals setting.

Name		Name	Last commit message	Last commit date
.claude/rules		.claude/rules
.github		.github
cmd		cmd
docs		docs
internal/update		internal/update
pkg		pkg
.gitignore		.gitignore
.golangci.yml		.golangci.yml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Latest commit

History

Folders and files

Repository files navigation