YugabyteDB System Tables
YugabyteDB adds the following system tables to the PostgreSQL catalog:pg_yb_catalog_version
Tracks the catalog version for each database to maintain consistency across distributed nodes.| Column | Type | Description |
|---|---|---|
db_oid | oid | OID of the database (primary key) |
current_version | int64 | Current version of the catalog |
last_breaking_version | int64 | Last version that invalidated ongoing transactions |
pg_yb_tablegroup
Stores information about tablegroups, which allow co-locating multiple tables for improved performance.| Column | Type | Description |
|---|---|---|
oid | oid | Tablegroup OID (primary key) |
grpname | name | Tablegroup name |
grpowner | oid | OID of the tablegroup owner |
grptablespace | oid | Tablespace OID for the tablegroup |
grpacl | aclitem[] | Access permissions |
grpoptions | text[] | Per-tablegroup options |
pg_yb_profile
Defines authentication profiles for role-based password policies.| Column | Type | Description |
|---|---|---|
oid | oid | Profile OID (primary key) |
prfname | name | Profile name (unique) |
prfmaxfailedloginattempts | int32 | Maximum failed login attempts allowed |
prfpasswordlocktime | int32 | Account lock duration in seconds |
pg_yb_role_profile
Links roles to profiles and tracks their authentication status.| Column | Type | Description |
|---|---|---|
oid | oid | Record OID (primary key) |
rolprfrole | oid | OID of the role |
rolprfprofile | oid | OID of the profile |
rolprfstatus | char | Status: ‘o’ (OPEN) or ‘l’ (LOCKED) |
rolprffailedloginattempts | int32 | Number of failed login attempts |
rolprflockeduntil | timestamptz | Lock expiration timestamp (nullable) |
pg_yb_migration
Tracks the history of catalog migrations applied to the database.| Column | Type | Description |
|---|---|---|
major | int32 | Major version of the migration |
minor | int32 | Minor version (for backported changes) |
name | name | Migration name or “baseline” for initdb |
time_applied | int64 | Timestamp in milliseconds (nullable) |
pg_yb_logical_client_version
Tracks logical replication client versions for each database.| Column | Type | Description |
|---|---|---|
db_oid | oid | OID of the database (primary key) |
current_version | int64 | Current version of the logical client |
pg_yb_invalidation_messages
Stores catalog invalidation messages for distributed cache coherency.| Column | Type | Description |
|---|---|---|
db_oid | oid | OID of the database |
current_version | int64 | Catalog version for this message |
message_time | int64 | Unix epoch timestamp in seconds |
messages | bytea | Serialized invalidation messages |
db_oid, current_version)
Example Query:
YugabyteDB System Views
YugabyteDB provides additional system views for monitoring and diagnostics:yb_terminated_queries
Shows queries that have been terminated by the system.| Column | Type | Description |
|---|---|---|
databasename | name | Database name |
backend_pid | int | Backend process ID |
query_id | bigint | Query identifier |
query_text | text | SQL query text |
termination_reason | text | Reason for termination |
query_start_time | timestamptz | Query start timestamp |
query_end_time | timestamptz | Query end timestamp |
yb_active_session_history
Provides active session history for performance analysis. Example Query:yb_local_tablets
Shows tablets hosted on the local tserver node. Example Query:yb_tablet_metadata
Provides metadata about tablets including their location and hash ranges.| Column | Type | Description |
|---|---|---|
tablet_id | text | Unique tablet identifier |
oid | oid | Table OID (nullable for system tables) |
db_name | text | Database/namespace name |
relname | text | Relation/table name |
start_hash_code | text | Start of hash range |
end_hash_code | text | End of hash range |
leader | text | Leader replica location |
replicas | text | All replica locations |
yb_wait_event_desc
Describes all wait events available in the system. Example Query:yb_query_diagnostics_status
Shows the status of query diagnostics collection. Example Query:yb_servers_metrics
Provides metrics for all tserver nodes in the cluster. Example Query:yb_pg_stat_plans
Tracks execution statistics for query plans (similar to pg_stat_statements).| Column | Type | Description |
|---|---|---|
dbid | oid | Database OID |
userid | oid | User OID |
queryid | bigint | Query identifier |
planid | bigint | Plan identifier |
first_used | timestamptz | First execution time |
last_used | timestamptz | Last execution time |
hints | text | Optimizer hints used |
calls | bigint | Number of executions |
avg_exec_time | float8 | Average execution time |
max_exec_time | float8 | Maximum execution time |
max_exec_time_params | text | Parameters for slowest execution |
avg_est_cost | float8 | Average estimated cost |
plan | text | Query plan text |
yb_pg_stat_plans_insights
Provides insights into query plan performance for optimization. Example Query:Monitoring Queries
Check Catalog Version Consistency
Monitor Locked Accounts
Tablet Distribution Analysis
Recent Catalog Changes
YugabyteDB System Functions
The following functions interact with YugabyteDB system tables:yb_reset_analyze_statistics
Resets table statistics to trigger re-analysis.yb_is_database_colocated
Checks if the current database uses colocation.yb_query_diagnostics
Enables query diagnostics collection for a specific query ID.yb_cancel_query_diagnostics
Cancels active query diagnostics collection.See Also
- PostgreSQL System Catalogs - Standard PostgreSQL catalog tables
- YCQL System Tables - Cassandra-compatible system tables
- Monitoring - Cluster monitoring and observability

