DB Console Overview

The DB Console provides details about your cluster and database configuration, and helps you optimize cluster performance.

Authorized CockroachDB Advanced cluster users can visit the DB Console at a URL provisioned for the cluster.Refer to: Network Authorization for CockroachDB Cloud Clusters — DB Console

Authentication

The DB Console supports username/password login and single sign-on (SSO) for CockroachDB self-hosted and CockroachDB Advanced clusters. The DB Console sign-on page can also be used to provision authentication tokens for SQL client access. Refer to:

DB Console areas

Overview

The Overview page provides a cluster overview and node list and map.

Cluster Overview has essential metrics about the cluster and nodes, including liveness status, replication status, uptime, and hardware usage.
Node List has a list of cluster metrics at the locality and node levels.
Node Map displays a geographical configuration of your cluster and metrics at the locality and node levels, visualized on a map.

Metrics

The Metrics page provides dashboards for all types of CockroachDB metrics.

Overview dashboard has metrics about SQL performance, replication, and storage.
Hardware dashboard has metrics about CPU usage, disk throughput, network traffic, storage capacity, and memory.
Runtime dashboard has metrics about node count, CPU time, and memory usage.
SQL dashboard has metrics about SQL connections, byte traffic, queries, transactions, and service latency.
Storage dashboard has metrics about storage capacity and file descriptors.
Replication dashboard has metrics about how data is replicated across the cluster, e.g., range status, replicas per store, etc.
Distributed dashboard has metrics about distribution tasks across the cluster, including RPCs and transactions.
Queues dashboard has metrics about the health and performance of various queueing systems in CockroachDB, including the garbage collection and Raft log queues.
Slow requests dashboard has metrics about important cluster tasks that take longer than expected to complete, including Raft proposals and lease acquisitions.
Changefeeds dashboard has metrics about the changefeeds created across your cluster.
Overload dashboard has metrics about the performance of the parts of your cluster relevant to the cluster’s admission control system.
TTL dashboard has metrics about the progress and performance of batch deleting expired data using Row-Level TTL from your cluster.
Physical Cluster Replication dashboard has metrics about the physical cluster replication streams between a primary and standby cluster.

Databases

The Databases page shows details about the system and user databases in the cluster.

SQL Activity

The SQL Activity page summarizes SQL activity in your cluster.

Statements shows frequently executed and high-latency SQL statements with the option to collect statement diagnostics.
Transactions shows details about transactions running on the cluster.
Sessions shows details about open sessions in the cluster.

Insights

The Insights page exposes problematic health signals and enables you to quickly find optimization opportunities to maximize database efficiency. The Insights page contains workload-level and schema-level insights.

Network Latency

The Network Latency page shows latencies and lost connections between all nodes in your cluster.

Jobs

The Jobs page shows details of jobs running in the cluster.

Advanced Debug

The Advanced Debug page provides advanced monitoring and troubleshooting reports. These include details about data distribution, the state of specific queues, and slow query metrics. These details are largely intended for use by CockroachDB developers. To access the Advanced Debug page, the user must be a member of the admin role or must have the VIEWDEBUG system privilege defined.

DB Console access

You can access the DB Console from every node at http://<host:<http-port, or http://<host:8080 by default.

If you included the --http-addr flag when starting nodes, use the IP address or hostname and port specified by that flag.
If you didn’t include the --http-addr flag when starting nodes, use the IP address or hostname specified by the --listen-addr flag and port 8080.
If you are running a secure cluster, use https instead of http.

For guidance on accessing the DB Console in the context of cluster deployment, see Start a Local Cluster and Manual Deployment.

Accessing the DB Console for a secure cluster requires login information (i.e., username and password). This login information is stored in a system table that is replicated like other data in the cluster. If a majority of the nodes with the replicas of the system table data go down, users will be locked out of the DB Console.

Proxy DB Console

If your CockroachDB cluster is behind a load balancer, you may wish to proxy your DB Console connection to a different node in the cluster from the node you first connect to. This is useful in deployments where a third-party load balancer otherwise determines which CockroachDB node you connect to in DB Console, or where web management access is limited to a subset of CockroachDB instances in a cluster. You can accomplish this using one of these methods:

Once connected to DB Console, use the Web server dropdown menu from the Advanced Debug page to select a different node to proxy to.
Use the remote_node_id parameter in your DB Console URL to proxy directly to a specific node. For example, use http://<host:<http-port/?remote_node_id=2 to proxy directly to node 2.

DB Console security considerations

Access to DB Console is a function of cluster security and the privileges of the accessing user.

Cluster security

On insecure clusters, all areas of the DB Console are accessible to all users. On secure clusters, for each user who should have access to the DB Console, you must create a user with a password and optionally GRANT the user system-level privileges or membership to the admin role.

Role-based security

All users have access to data over which they have privileges (e.g., jobs and list of sessions), and data that does not require privileges (e.g., cluster health, node status, metrics). The following areas display information from privileged HTTP endpoints that require the user to have the admin role or the specified system-level privileges.

DB Console area	System-level privilege	Privileged information
Statements	`VIEWACTIVITY` or `VIEWACTIVITYREDACTED`	SQL statements
Transactions	`VIEWACTIVITY` or `VIEWACTIVITYREDACTED`	Transactions
Sessions	`VIEWACTIVITY` or `VIEWACTIVITYREDACTED`	Sessions
Insights	`VIEWACTIVITY` or `VIEWACTIVITYREDACTED`	Insights
Top Ranges	`VIEWCLUSTERMETADATA`	Ranges
Jobs	`VIEWJOB`	Jobs
Schedules	`VIEWJOB`	Schedules
Events	`VIEWEVENTLOG` or `VIEWCLUSTERMETADATA`	Cluster events
Advanced Debug	`VIEWDEBUG`	Debugging and profiling endpoints
Advanced Debug > Problem Ranges	`VIEWCLUSTERMETADATA`	Ranges
Advanced Debug > Data Distribution and Zone Configs	`VIEWCLUSTERMETADATA`	Ranges
Advanced Debug > Cluster Settings	`VIEWCLUSTERSETTING` or `MODIFYCLUSTERSETTING`	Cluster Settings

Example: Create a read-only DB Console user

To create a non-admin user with broad read-only visibility across the DB Console — including statements, jobs, schedules, and cluster events — grant a combination of system-level privileges:

CREATE USER monitoring_user WITH PASSWORD '<password>';
GRANT SYSTEM VIEWACTIVITYREDACTED TO monitoring_user;
GRANT SYSTEM VIEWJOB TO monitoring_user;
GRANT SYSTEM VIEWEVENTLOG TO monitoring_user;
GRANT SYSTEM VIEWCLUSTERSETTING TO monitoring_user;

This grants read-only access to the Statements, Transactions, Sessions, Insights, Jobs, Schedules, Events, and Cluster Settings areas of the DB Console without granting the admin role. Adjust the privileges to match the level of access required.

DB Console timezone configuration

To view timestamps in your preferred timezone in the DB Console, use the ui.default_timezone cluster setting. This setting supports all valid timezone identifiers, such as America/New_York and Asia/Tokyo.

SET CLUSTER SETTING ui.default_timezone = 'America/New_York';

If no value is set, the DB Console displays timestamps in UTC.

The ui.display_timezone cluster setting is now deprecated and will be removed in a future release. Avoid using ui.display_timezone. Use ui.default_timezone instead for full support and forward compatibility.

DB Console troubleshooting

The DB Console stores temporary data in a time-series database in order to generate the various metrics graphs. If your cluster is comprised of a large number of nodes where individual nodes have very limited memory available (e.g., under 8 GiB), this underlying time-series database may not have enough memory available per-node to serve these requests quickly. If the DB Console experiences issues rendering these metrics graphs, consider increasing the value of the --max-tsdb-memory flag.

Diagnostics reporting

By default, the DB Console shares anonymous usage details with Cockroach Labs. For information about the details shared and how to opt-out of reporting, see Diagnostics Reporting.

License expiration message

If you have set a license, a license expiration message is displayed at the top-right of the DB Console. While the license is valid, the message will read License expires in X days, where X is the number of days. If the license is no longer valid, the message will read License expired X days ago. Hovering over either message displays a tooltip with the expiration date of the license.

Get Started

CockroachDB and AI

Feature Overview

Data Resilience

Connect to an Application

Self-Hosted Deployments

Schema Design

Reads and Writes

Stream Data

Cross-Cluster Replication

Multi-Region Capabilities

Optimize Performance

Integrate

Authentication

DB Console areas

Overview

Metrics

Databases

SQL Activity

Insights

Network Latency

Jobs

Advanced Debug

DB Console access

Proxy DB Console

DB Console security considerations

Cluster security

Role-based security

Example: Create a read-only DB Console user

DB Console timezone configuration

DB Console troubleshooting

Diagnostics reporting

License expiration message

See also

​Authentication

​DB Console areas

​Overview

​Metrics

​Databases

​SQL Activity

​Insights

​Network Latency

​Jobs

​Advanced Debug

​DB Console access

​Proxy DB Console

​DB Console security considerations

​Cluster security

​Role-based security

​Example: Create a read-only DB Console user

​DB Console timezone configuration

​DB Console troubleshooting

​Diagnostics reporting

​License expiration message

​See also

Authentication

DB Console areas

Overview

Metrics

Databases

SQL Activity

Insights

Network Latency

Jobs

Advanced Debug

DB Console access

Proxy DB Console

DB Console security considerations

Cluster security

Role-based security

Example: Create a read-only DB Console user

DB Console timezone configuration

DB Console troubleshooting

Diagnostics reporting

License expiration message

See also