--- title: "yb-admin" url: "https://docs.yugabyte.com/stable/admin/yb-admin/" --- # yb-admin Use the yb-admin command line tool for advanced administration of YugabyteDB clusters. The yb-admin utility, located in the `bin` directory of YugabyteDB home, provides a command line interface for administering clusters. It invokes the [yb-master](/stable/reference/configuration/yb-master/ "yb-master") and [yb-tserver](/stable/reference/configuration/yb-tserver/ "yb-tserver") servers to perform the necessary administration. Using YugabyteDB Anywhere or YugabyteDB Aeon? yb-admin is intended to be used to administer manually created and managed universes only. If you are using [YugabyteDB Anywhere](/stable/yugabyte-platform/ "YugabyteDB Anywhere") or [YugabyteDB Aeon](/stable/yugabyte-cloud/ "YugabyteDB Aeon"), administer your universes using the respective UI, or, to use automation, use the respective API or CLI. For more information, refer to [YugabyteDB Anywhere automation](/stable/yugabyte-platform/anywhere-automation/ "YugabyteDB Anywhere automation") and [YugabyteDB Aeon automation](/stable/yugabyte-cloud/managed-automation/ "YugabyteDB Aeon automation"). **If you perform tasks on a YugabyteDB Anywhere-managed universe using yb-admin, the changes may not be reflected in YugabyteDB Anywhere.** If you are unsure whether a particular functionality in yb-admin is available in YugabyteDB Anywhere, contact [Yugabyte Support](https://support.yugabyte.com/hc/en-us/requests/new?ticket_form_id=360001955891 "Yugabyte Support"). ## Syntax To use yb-admin from the YugabyteDB home directory, run `./bin/yb-admin` using the following syntax. ```sh yb-admin \ [ --master_addresses ] \ [ --init_master_addrs ] \ [ --timeout_ms ] \ [ --certs_dir_name ] \ [ --flagfile ] \ [ command_flags ] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - `init_master_addrs`: Allows specifying a single YB-Master address from which the rest of the YB-Masters are discovered. - `timeout_ms`: The RPC timeout, in milliseconds. Default 60000. A value of 0 means don't wait; -1 means wait indefinitely. - `certs_dir_name`: The directory with certificates to use for secure server connections. Default is `""`. To connect to a cluster with TLS enabled, you must include the `-certs_dir_name` flag with the directory location where the root certificate is located. - `flagfile`: The path to a file containing flags to pass to yb-admin. Use this flag with the YB-Master's `server.conf` configuration file to automatically pick up `master_addresses` and `certs_dir_name`, avoiding manual flag entry. For example: ```sh ./bin/yb-admin --flagfile master/conf/server.conf list_all_masters ``` Available in v2026.1.1.0 and later. - **command**: The operation to be performed. See [Commands](#commands "Commands") for syntax details and examples. - **command\_flags**: Configuration flags that can be applied to the command. ### Online help To display the online help, run `yb-admin --help` from the YugabyteDB home directory. ```sh ./bin/yb-admin --help ``` ## Commands - [Universe and cluster](#universe-and-cluster-commands "Universe and cluster") - [Table](#table-commands "Table") - [Backup and snapshot](#backup-and-snapshot-commands "Backup and snapshot") - [Deployment topology](#deployment-topology-commands "Deployment topology") - [Multi-zone and multi-region](#multi-zone-and-multi-region-deployment-commands "Multi-zone and multi-region") - [Read replica](#read-replica-deployment-commands "Read replica") - [Security](#security-commands "Security") - [Encryption at rest](#encryption-at-rest-commands "Encryption at rest") - [Change data capture (CDC)](#change-data-capture-cdc-commands "Change data capture (CDC)") - [xCluster replication](#xcluster-replication-commands "xCluster replication") - [Decommissioning](#decommissioning-commands "Decommissioning") - [Cluster balancing](#cluster-balancing-commands "Cluster balancing") - [Upgrade](#upgrade "Upgrade") * * * ### Universe and cluster commands #### get\_universe\_config Gets the configuration for the universe. **Syntax** ```sh yb-admin \ --master_addresses \ get_universe_config ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. #### change\_config Changes the configuration of a tablet. **Syntax** ```sh yb-admin \ --master_addresses \ change_config \ [ ADD_SERVER | REMOVE_SERVER ] \ \ [ PRE_VOTER | PRE_OBSERVER ] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *tablet-id*: The identifier (ID) of the tablet. - ADD\_SERVER | REMOVE\_SERVER: Subcommand to add or remove the server. - *peer-uuid*: The UUID of the tablet server hosting the peer tablet. - PRE\_VOTER | PRE\_OBSERVER: Role of the new peer joining the quorum. Required when using the ADD\_SERVER subcommand. **Notes:** If you need to take a node down temporarily, but intend to bring it back up, you should not need to use the REMOVE\_SERVER subcommand. - If the node is down for less than 15 minutes, it will catch up through RPC calls when it comes back online. - If the node is offline longer than 15 minutes, then it will go through Remote Bootstrap, where the current leader will forward all relevant files to catch up. If you do not intend to bring a node back up (perhaps you brought it down for maintenance, but discovered that the disk is bad), then you want to decommission the node (using the REMOVE\_SERVER subcommand) and then add in a new node (using the ADD\_SERVER subcommand). #### change\_master\_config Changes the master configuration. **Syntax** ```sh yb-admin \ --master_addresses \ change_master_config \ [ ADD_SERVER|REMOVE_SERVER ] \ \ [] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - ADD\_SERVER | REMOVE\_SERVER: Adds or removes a new YB-Master server. After adding or removing a node, verify the status of the YB-Master server on the YB-Master UI page ([http://node-ip:7000](http://node-ip:7000 "http://node-ip:7000")) or run the yb-admin [dump\_masters\_state](#dump-masters-state "dump_masters_state") command. - *ip-addr*: The IP address of the server node. - *port*: The port of the server node. - *uuid*: The UUID for the server that is being added/removed. #### list\_tablet\_servers **Syntax** ```sh yb-admin \ --master_addresses \ list_tablet_servers ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *tablet-id*: The identifier (ID) of the tablet. #### list\_tablets Lists all tablets and their replica locations for a particular table. Use this to find out who the LEADER of a tablet is. **Syntax** ```sh yb-admin \ --master_addresses \ list_tablets . [] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *keyspace-type*: Type of the keyspace, ysql or ycql. - *keyspace-name*: The namespace, or name of the database or keyspace. - *table*: The name of the table. - *max-tablets*: The maximum number of tables to be returned. Default is `10`. Set to `0` to return all tablets. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ list_tablets ysql.db_name table_name 0 ``` ```output Tablet UUID Range Leader cea3aaac2f10460a880b0b4a2a4b652a partition_key_start: "" partition_key_end: "\177\377" 127.0.0.1:9100 e509cf8eedba410ba3b60c7e9138d479 partition_key_start: "\177\377" partition_key_end: "" ``` #### list\_all\_tablet\_servers Lists all tablet servers. **Syntax** ```sh yb-admin \ --master_addresses \ list_all_tablet_servers ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. #### list\_all\_masters Displays a list of all YB-Master servers in a table listing the master UUID, RPC host and port, state (`ALIVE` or `DEAD`), and role (`LEADER`, `FOLLOWER`, or `UNKNOWN_ROLE`). **Syntax** ```sh yb-admin \ --master_addresses \ list_all_masters ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. **Example** ```sh ./bin/yb-admin \ --master_addresses node7:7100,node8:7100,node9:7100 \ list_all_masters ``` ```output Master UUID RPC Host/Port State Role ... node8:7100 ALIVE FOLLOWER ... node9:7100 ALIVE FOLLOWER ... node7:7100 ALIVE LEADER ``` #### list\_replica\_type\_counts Prints a list of replica types and counts for the specified table. **Syntax** ```sh yb-admin \ --master_addresses \ list_replica_type_counts ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *keyspace*: The name of the database or keyspace. - *table-name*: The name of the table. #### dump\_masters\_state Prints the status of the YB-Master servers. **Syntax** ```sh yb-admin \ --master_addresses \ dump_masters_state ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. #### list\_tablet\_server\_log\_locations List the locations of the tablet server logs. **Syntax** ```sh yb-admin \ --master_addresses \ list_tablet_server_log_locations ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. #### list\_tablets\_for\_tablet\_server Lists all tablets for the specified tablet server (YB-TServer). **Syntax** ```sh yb-admin \ --master_addresses \ list_tablets_for_tablet_server ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *ts-uuid*: The UUID of the tablet server (YB-TServer). #### split\_tablet Splits the specified hash-sharded tablet and computes the split point as the middle of tablet's sharding range. ```sh yb-admin \ --master_addresses \ split_tablet ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *tablet-id-to-split*: The identifier of the tablet to split. For more information on tablet splitting, see: - [Tablet splitting](/stable/architecture/docdb-sharding/tablet-splitting "Tablet splitting") — Architecture overview - [Automatic Re-sharding of Data with Tablet Splitting](https://github.com/yugabyte/yugabyte-db/blob/master/architecture/design/docdb-automatic-tablet-splitting.md "Automatic Re-sharding of Data with Tablet Splitting") — Architecture design document in the GitHub repository. #### master\_leader\_stepdown Forces the master leader to step down. The specified YB-Master node will take its place as leader. Note - Use this command only if recommended by Yugabyte support. - There is a possibility of downtime. **Syntax** ```sh yb-admin \ --master_addresses \ master_leader_stepdown [ ] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *new-leader-id*: (Optional) The identifier (ID) of the new YB-Master leader. If not specified, the new leader is automatically elected. #### ysql\_catalog\_version Prints the current YSQL schema catalog version. **Syntax** ```sh yb-admin \ --master_addresses \ ysql_catalog_version ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ ysql_catalog_version ``` The version output displays: ```output Version:1 ``` * * * ### Table commands #### list\_tables Prints a list of all tables. Optionally, include the database type, table ID, and the table type. **Syntax** ```sh yb-admin \ --master_addresses \ list_tables \ [ include_db_type ] [ include_table_id ] [ include_table_type ] ``` ```sh yb-admin \ --master_addresses list_tables ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - `include_db_type`: (Optional) Add this flag to include the database type for each table. - `include_table_id`: (Optional) Add this flag to include the unique UUID associated with the table. - `include_table_type`: (Optional) Add this flag to include the table type for each table. Returns tables in the following format, depending on the flags used: ```output .. ``` - *db-type*: The type of database. Valid values are `ysql`, `ycql`, and `unknown`. - *namespace*: The name of the database (for YSQL) or keyspace (for YCQL). - *table-name*: The name of the table. - *table-id*: The UUID of the table. - *table-type*: The type of table. Valid values are `catalog`, `table`, `index`, and `other`. Tip To display a list of tables and their UUID (`table_id`) values, open the **YB-Master UI** (`:7000/`) and click **Tables** in the navigation bar. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ list_tables ``` ```output ... yugabyte.pg_range template1.pg_attrdef template0.pg_attrdef_adrelid_adnum_index template1.pg_conversion system_platform.pg_opfamily postgres.pg_opfamily_am_name_nsp_index system_schema.functions template0.pg_statistic system.local template1.pg_inherits_parent_index template1.pg_amproc system_platform.pg_rewrite yugabyte.pg_ts_config_cfgname_index template1.pg_trigger_tgconstraint_index template1.pg_class template1.pg_largeobject system_platform.sql_parts template1.pg_inherits ... ``` #### compact\_table Triggers manual compaction on a table. **Syntax 1: Using table name** ```sh yb-admin \ --master_addresses \ compact_table .
[] [ADD_INDEXES] [ADD_VECTOR_INDEXES] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *db-type*: The type of database. Valid values are `ysql` and `ycql`. - *namespace*: The name of the database (for YSQL) or keyspace (for YCQL). - *table*: The name of the table to compact. - *timeout-in-seconds*: Specifies duration (in seconds) yb-admin waits for compaction to end. Default is `20`. - ADD\_INDEXES: Indicates to compact the secondary indexes associated with the table. YCQL only. - ADD\_VECTOR\_INDEXES: Indicates to compact the [vector indexes](/stable/additional-features/pg-extensions/extension-pgvector/#vector-indexing "vector indexes") (pgvector) associated with the table. **Example** ```sh ./bin/yb-admin \ --master_addresses $MASTER_RPC_ADDRS \ compact_table ysql.yugabyte table_name ``` ```output Compacted [yugabyte.table_name] tables. ``` **Syntax 2: Using table ID** ```sh yb-admin \ --master_addresses \ compact_table tableid. [] [ADD_INDEXES] [ADD_VECTOR_INDEXES] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *table-id*: The unique UUID associated with the table. - *timeout-in-seconds*: Specifies duration (in seconds) yb-admin waits for compaction to end. Default is `20`. - ADD\_INDEXES: Indicates to compact the secondary indexes associated with the table. YCQL only. - ADD\_VECTOR\_INDEXES: Indicates to compact the [vector indexes](/stable/additional-features/pg-extensions/extension-pgvector/#vector-indexing "vector indexes") (pgvector) associated with the table. **Example** ```sh ./bin/yb-admin \ --master_addresses $MASTER_RPC_ADDRS \ compact_table tableid.000033eb000030008000000000004002 ``` ```output Compacted [000033eb000030008000000000004002] tables. ``` #### compact\_table\_by\_id Triggers manual compaction on a table by table ID (without resolving namespace and table name). **Syntax** ```sh yb-admin \ --master_addresses \ compact_table_by_id [] [ADD_INDEXES] [ADD_VECTOR_INDEXES] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *table-id*: The unique UUID associated with the table. - *timeout-in-seconds*: Specifies duration (in seconds) yb-admin waits for compaction to end. Default is `20`. - ADD\_INDEXES: Indicates to compact the secondary indexes associated with the table. YCQL only. - ADD\_VECTOR\_INDEXES: Indicates to compact the [vector indexes](/stable/additional-features/pg-extensions/extension-pgvector/ "vector indexes") (pgvector) associated with the table. **Example** ```sh ./bin/yb-admin \ --master_addresses $MASTER_RPC_ADDRS \ compact_table_by_id 000033eb000030008000000000004002 ADD_VECTOR_INDEXES ``` ```output Compacted [000033eb000030008000000000004002] tables. ``` #### compaction\_status Show the status of full compaction on a table. ```sh yb-admin \ --master_addresses \ compaction_status .
[show_tablets] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *db-type*: The type of database. Valid values are `ysql` and `ycql`. - *namespace*: The name of the database (for YSQL) or keyspace (for YCQL). - *table*: The name of the table to show the full compaction status. - `show_tablets`: Show the compactions status of individual tablets. **Example** ```sh ./bin/yb-admin \ --master_addresses $MASTER_RPC_ADDRS \ compaction_status ysql.yugabyte table_name show_tablets ``` ```output tserver uuid: 1b9486461cdd48f59eb46b33992cd73a tablet id | full compaction state | last full compaction completion time 93c6933407e24adf8b3f12c11499673a IDLE 2025-06-03 15:36:22.395586 9c1cddfe33ec440cbcd70770563c62ca IDLE 2025-06-03 15:36:22.743703 b739745bba254330805c259459c61a7e IDLE 2025-06-03 15:36:23.416460 9d0155aa77b3441e8e8c78cc433b995c IDLE 2025-06-03 15:36:23.504400 2b9f283301d14be2add2c3f2a0016531 IDLE 2025-06-03 15:36:23.892202 eff101a879f348778ed599cb79498c44 IDLE 2025-06-03 15:36:24.706769 tserver uuid: c0505f1d31774a3d88fae26ce14cde10 tablet id | full compaction state | last full compaction completion time 93c6933407e24adf8b3f12c11499673a IDLE 2025-06-03 15:36:22.769900 9c1cddfe33ec440cbcd70770563c62ca IDLE 2025-06-03 15:36:23.142609 b739745bba254330805c259459c61a7e IDLE 2025-06-03 15:36:23.871247 9d0155aa77b3441e8e8c78cc433b995c IDLE 2025-06-03 15:36:23.877126 2b9f283301d14be2add2c3f2a0016531 IDLE 2025-06-03 15:36:24.294265 eff101a879f348778ed599cb79498c44 IDLE 2025-06-03 15:36:25.107964 tserver uuid: f7b5e6fc38974cbabc330d944d564974 tablet id | full compaction state | last full compaction completion time 93c6933407e24adf8b3f12c11499673a IDLE 2025-06-03 15:36:22.415413 9c1cddfe33ec440cbcd70770563c62ca IDLE 2025-06-03 15:36:22.793145 b739745bba254330805c259459c61a7e IDLE 2025-06-03 15:36:23.473077 9d0155aa77b3441e8e8c78cc433b995c IDLE 2025-06-03 15:36:23.475270 2b9f283301d14be2add2c3f2a0016531 IDLE 2025-06-03 15:36:23.888733 eff101a879f348778ed599cb79498c44 IDLE 2025-06-03 15:36:24.705576 Last full compaction completion time: 2025-06-03 15:36:22.395586 Last admin compaction request time: 2025-06-03 15:36:22.061267 ``` #### modify\_table\_placement\_info Modifies the placement information (cloud, region, and zone) for a table. **Syntax** ```sh yb-admin \ --master_addresses \ modify_table_placement_info \ [ ] ``` or alternatively: ```sh yb-admin \ --master_addresses \ modify_table_placement_info tableid. \ [ ] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *keyspace*: The namespace, or name of the database or keyspace. - *table-name*: The name of the table. - *table-id*: The unique UUID associated with the table whose placement policy is being changed. - *placement-info*: Comma-delimited list of placements for *cloud*.*region*.*zone*. Default is `cloud1.datacenter1.rack1`. - *replication-factor*: The number of replicas for each tablet. - *placement-id*: Identifier of the primary cluster. Optional. If set, it has to match the placement ID specified for the primary cluster in the cluster configuration. **Example** ```sh ./bin/yb-admin \ --master_addresses $MASTER_RPC_ADDRS \ modify_table_placement_info testdatabase testtable \ aws.us-west.us-west-2a,aws.us-west.us-west-2b,aws.us-west.us-west-2c 3 ``` Verify this in the Master UI by opening the **YB-Master UI** (`:7000/`) and clicking **Tables** in the navigation bar. Navigate to the appropriate table whose placement information you're changing, and check the Replication Info section. Notes Setting placement for tables is not supported for clusters with read-replicas or leader affinity policies enabled. Use this command to create custom placement policies only for YCQL tables or transaction status tables. For YSQL tables, use [CREATE TABLESPACE](/stable/api/ysql/the-sql-language/statements/ddl_create_tablespace/ "CREATE TABLESPACE") instead. #### create\_transaction\_table Creates a transaction status table to be used in a region. This command should always be followed by [modify\_table\_placement\_info](#modify-table-placement-info "modify_table_placement_info") to set the placement information for the newly-created transaction status table. **Syntax** ```sh yb-admin \ --master_addresses \ create_transaction_table \ ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *table-name*: The name of the transaction status table to be created; this must start with `transactions_`. The transaction status table will be created as `system.`. **Example** ```sh ./bin/yb-admin \ --master_addresses $MASTER_RPC_ADDRS \ create_transaction_table \ transactions_us_east ``` Verify this in the Master UI by opening the **YB-Master UI** (`:7000/`) and clicking **Tables** in the navigation bar. You should see a new system table with keyspace `system` and table name `transactions_us_east`. Next, set the placement on the newly created transactions table: ```sh ./bin/yb-admin \ --master_addresses $MASTER_RPC_ADDRS \ modify_table_placement_info system transactions_us_east \ aws.us-east.us-east-1a,aws.us-east.us-east-1b,aws.us-east.us-east-1c 3 ``` After the load balancer runs, all tablets of `system.transactions_us_east` should now be solely located in the AWS us-east region. Note The preferred way to create transaction status tables with YSQL is to create a tablespace with the appropriate placement. YugabyteDB automatically creates a transaction table using the tablespace's placement when you create the first table using the new tablespace. #### add\_transaction\_tablet Add a tablet to a transaction status table. **Syntax** ```sh yb-admin \ --master_addresses \ add_transaction_tablet \ ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *table-id*: The unique UUID associated with the table to be compacted. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ add_transaction_tablet 000033eb000030008000000000004002 ``` To verify that the new status tablet has been created, run the [list\_tablets](#list-tablets "list_tablets") command. #### flush\_table Flush the memstores of the specified table on all tablet servers to disk. **Syntax 1: Using table name** ```sh yb-admin \ --master_addresses \ flush_table .
[] [ADD_INDEXES] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *db-type*: The type of database. Valid values are `ysql` and `ycql`. - *namespace*: The name of the database (for YSQL) or keyspace (for YCQL). - *table*: The name of the table to flush. - *timeout-in-seconds*: Specifies duration (in seconds) yb-admin waits for flushing to end. Default is `20`. - ADD\_INDEXES: Indicates to flush the secondary indexes associated with the table. **Example** ```sh ./bin/yb-admin \ --master_addresses $MASTER_RPC_ADDRS \ flush_table ysql.yugabyte table_name ``` ```output Flushed [yugabyte.table_name] tables. ``` **Syntax 2: Using table ID** ```sh yb-admin \ --master_addresses \ flush_table tableid. [] [ADD_INDEXES] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *table-id*: The unique UUID associated with the table. - *timeout-in-seconds*: Specifies duration (in seconds) yb-admin waits for flushing to end. Default is `20`. - ADD\_INDEXES: Indicates to flush the secondary indexes associated with the table. **Example** ```sh ./bin/yb-admin \ --master_addresses $MASTER_RPC_ADDRS \ flush_table tableid.000033eb000030008000000000004002 ``` ```output Flushed [000033eb000030008000000000004002] tables. ``` #### backfill\_indexes\_for\_table Backfill all DEFERRED indexes in a YCQL table. **Syntax** ```sh yb-admin \ --master_addresses \ backfill_indexes_for_table ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *keyspace*: Specifies the keyspace `ycql.keyspace-name`. - *table-name*: Specifies the table name. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ backfill_indexes_for_table ybdemo table_name ``` A new backfill job is created for all the `DEFERRED` indexes of the table. The command does not have any output. #### get\_table\_hash Computes an XOR hash and row count over the data in a table, tablet by tablet. Use this to verify data consistency across clusters in an xCluster deployment by comparing hash values at the same hybrid timestamp. For colocated databases, pass a child table's *table-id* to scope the hash to a single colocated table. To hash all colocated tables sharing a tablet together, pass the colocation parent table ID, which is visible in [list\_tables](#list-tables "list_tables") when system tables are included. **Syntax** ```sh yb-admin \ --master_addresses \ get_table_hash \ [] [] [] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *table-id*: UUID of the table to hash. Obtain this from [list\_tables](#list-tables "list_tables"). For a colocated database, pass the child table UUID to scope the hash to one table, or the colocation parent table UUID to hash all colocated tables in the tablet. - *read-ht* (optional): Hybrid timestamp at which to read, as a 64-bit integer. Defaults to the current time. Because the arguments are positional, pass 0 to keep the default when you also need to specify *start-key-hex* / *end-key-hex*. Use the same value on both clusters when comparing hashes for xCluster consistency checks. - *start-key-hex* (optional): Inclusive lower bound of the partition-key range to hash, as the hex encoding of a tablet's `partition_key_start` from [list\_tablets](#list-tablets "list_tablets"). Pass an empty string (`""`) to leave this side unbounded. - *end-key-hex* (optional): Exclusive upper bound of the partition-key range, as the hex encoding of `partition_key_end`. `partition_key_end` values from [list\_tablets](#list-tablets "list_tablets") are inclusive; add 1 to match this exclusive bound. Pass an empty string (`""`) to leave this side unbounded. **Notes** - Key range arguments (*start-key-hex* / *end-key-hex*) require a concrete child table ID. Using them with a colocation parent table ID returns an error. - For hash-partitioned tables, each bound must be a valid 2-byte hash-partition key. - *start-key-hex* must be strictly less than *end-key-hex* when both are specified. - Key-range and per-table colocated scoping require YugabyteDB [v2024.2](/stable/releases/ybdb-releases/v2024.2), [v2025.2](/stable/releases/ybdb-releases/v2025.2), or [v2026.1](/stable/releases/ybdb-releases/v2026.1) on both yb-admin and the target YB-TServers. On older YB-TServer versions, the scoping arguments are silently ignored and the full table (or entire colocated tablet) is hashed instead of returning an error, so verify versions before relying on the result in a mixed-version cluster. **Example: Hash a full table** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ get_table_hash 000030af000030008000000000004000 ``` ```output Processing 3 tablets for table 000030af000030008000000000004000 Read HT: { physical: 1748000000000000 } Tablet ID: cea3aaac2f10460a880b0b4a2a4b652a Row count: 100 XOR hash: 3825474321 Tablet ID: e509cf8eedba410ba3b60c7e9138d479 Row count: 98 XOR hash: 2910384756 Tablet ID: f1a234b5c6d7e8f9a0b1c2d3e4f5a6b7 Row count: 102 XOR hash: 1029384756 Total row count: 300 Total XOR hash: 1948762961 ``` **Example: Hash a partition-key range** Use this to narrow down where data diverged across clusters (bisecting after a whole-table mismatch), or to hash only a fraction of a very large table. For example, sampling a random range periodically, or splitting a full scan into non-overlapping ranges run in parallel. *start-key-hex* and *end-key-hex* are the hex encodings of `partition_key_start` and `partition_key_end` which you can obtain from [list\_tablets](#list-tablets "list_tablets"). For hash-partitioned tables, `list_tablets` prints each tablet's range as `hash_split: [0x..., 0x...]`; use the values without the `0x` prefix. Remember that `list_tablets` shows `partition_key_end` as inclusive, while *end-key-hex* is exclusive, so add 1 to the end value to land on the same boundary. The range is logical and cluster-independent; each cluster resolves it against its own tablet boundaries. ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ get_table_hash 000030af000030008000000000004000 0 "" 8000 ``` This hashes the lower half of the hash-partition space (unbounded start through `0x8000` exclusive). * * * ### Backup and snapshot commands The following backup and snapshot commands are available: - [**create\_database\_snapshot**](#create-database-snapshot "create_database_snapshot") creates a snapshot of the specified YSQL database - [**create\_keyspace\_snapshot**](#create-keyspace-snapshot "create_keyspace_snapshot") creates a snapshot of the specified YCQL keyspace - [**list\_snapshots**](#list-snapshots "list_snapshots") returns a list of all snapshots, restores, and their states - [**create\_snapshot**](#create-snapshot "create_snapshot") creates a snapshot of one or more YCQL tables and indexes - [**restore\_snapshot**](#restore-snapshot "restore_snapshot") restores a snapshot - [**list\_snapshot\_restorations**](#list-snapshot-restorations "list_snapshot_restorations") returns a list of all snapshot restorations - [**export\_snapshot**](#export-snapshot "export_snapshot") creates a snapshot metadata file - [**import\_snapshot**](#import-snapshot "import_snapshot") imports a snapshot metadata file - [**import\_snapshot\_selective**](#import-snapshot-selective "import_snapshot_selective") imports a specified snapshot metadata file - [**delete\_snapshot**](#delete-snapshot "delete_snapshot") deletes a snapshot's information - [**create\_snapshot\_schedule**](#create-snapshot-schedule "create_snapshot_schedule") sets the schedule for snapshot creation - [**list\_snapshot\_schedules**](#list-snapshot-schedules "list_snapshot_schedules") returns a list of all snapshot schedules - [**edit\_snapshot\_schedule**](#edit-snapshot-schedule "edit_snapshot_schedule") modifies the schedule for snapshot creation - [**restore\_snapshot\_schedule**](#restore-snapshot-schedule "restore_snapshot_schedule") restores all objects in a scheduled snapshot - [**delete\_snapshot\_schedule**](#delete-snapshot-schedule "delete_snapshot_schedule") deletes the specified snapshot schedule - [**clone\_namespace**](#clone-namespace "clone_namespace") clones a YSQL database or YCQL keyspace as of a point in time - [**list\_clones**](#list-clones "list_clones") lists clone operations for a source database or keyspace YugabyteDB Anywhere A database or keyspace can have at most one snapshot schedule. If YugabyteDB Anywhere manages PITR for a universe, manage PITR only from the YugabyteDB Anywhere UI. Using yb-admin and the UI together to manage snapshot schedules can cause conflicts and is strongly discouraged. Changes you make using yb-admin are not reflected in YugabyteDB Anywhere. #### create\_database\_snapshot Creates a snapshot of the specified YSQL database. **Syntax** ```sh yb-admin \ --master_addresses \ create_database_snapshot ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *database*: The name of the YSQL database. When this command runs, a `snapshot_id` is generated and printed. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ create_database_snapshot ``` To see if the database snapshot creation has completed, run the [yb-admin list\_snapshots](#list-snapshots "yb-admin list_snapshots") command. #### create\_keyspace\_snapshot Creates a snapshot of the specified YCQL keyspace. **Syntax** ```sh yb-admin \ --master_addresses \ create_keyspace_snapshot ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *keyspace*: The name of the YCQL keyspace. When this command runs, a `snapshot_id` is generated and printed. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ create_keyspace_snapshot ``` To see if the database snapshot creation has completed, run the [yb-admin list\_snapshots](#list-snapshots "yb-admin list_snapshots") command. #### list\_snapshots Prints a list of all snapshot IDs, restoration IDs, and states. Optionally, prints details (including keyspaces, tables, and indexes) in JSON format. **Syntax** ```sh yb-admin \ --master_addresses \ list_snapshots \ [ show_details ] [ not_show_restored ] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - `show_details`: (Optional) Print snapshot details, including the keyspaces, tables, and indexes. - `not_show_restored`: (Optional) Do not show successful "restorations" (that is, `COMPLETE`). Use to see a list of only uncompleted or failed restore operations. - `show_deleted`: (Optional) Show snapshots that are deleted, but still retained in memory. Possible `state` values for creating and restoring snapshots: - `create_snapshot`: `CREATING`, `COMPLETE`, `DELETING`, `DELETED`, or `FAILED`. - `restore_snapshot`: `COMPLETE`, `DELETING`, `DELETED`, or `FAILED`. By default, the `list_snapshots` command prints the current state of the following operations: - `create_snapshot`: `snapshot_id`, `keyspace`, `table`, `state` - `restore_snapshot`: `snapshot_id`, `restoration_id`, `state`. - `delete_snapshot`: `snapshot_id`, `state`. When `show_details` is included, the `list_snapshots` command prints the following details in JSON format: - `type`: `NAMESPACE` - `id`: `` or `` - `data`: - `name`: `""` - `database_type`: `"YQL_DATABASE_CQL"` - `colocated`: `true` or `false` - `state`: `""` - `type`: `TABLE` <== Use for table or index - `id`: `""` or `""` - `data`: - `name`: `""` or `""` - `version`: `""` - `state`: `""` - `state_msg`: `""` - `next_column_id`: `""` - `table_type`: `"YQL_TABLE_TYPE"` - `namespace_id`: `""` - `indexed_table_id` (index only): `` - `is_local_index` (index only): `true` or `false` - `is_unique_index` (index only): `true` or `false` **Example** In this example, the optional `show_details` flag is added to generate the snapshot details. ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ list_snapshots show_details ``` Because `show_details` was included, `list_snapshots` prints the details in JSON format, like this: ```output f566b03b-b85e-41a0-b903-875cd305c1c5 COMPLETE {"type":"NAMESPACE","id":"8053dd55d478437cba57d9f67caac154","data":{"name":"yugabyte","database_type":"YQL_DATABASE_CQL","colocated":false,"state":"RUNNING"}} {"type":"TABLE","id":"a7e940e724ef497ebe94bf69bfe507d9","data":{"name":"tracking1","version":1,"state":"RUNNING","state_msg":"Current schema version=1","next_column_id":13,"table_type":"YQL_TABLE_TYPE","namespace_id":"8053dd55d478437cba57d9f67caac154"}} {"type":"NAMESPACE","id":"8053dd55d478437cba57d9f67caac154","data":{"name":"yugabyte","database_type":"YQL_DATABASE_CQL","colocated":false,"state":"RUNNING"}} {"type":"TABLE","id":"b48f4d7695f0421e93386f7a97da4bac","data":{"name":"tracking1_v_idx","version":0,"state":"RUNNING","next_column_id":12,"table_type":"YQL_TABLE_TYPE","namespace_id":"8053dd55d478437cba57d9f67caac154","indexed_table_id":"a7e940e724ef497ebe94bf69bfe507d9","is_local_index":false,"is_unique_index":false}} ``` If `show_details` is not included, `list_snapshots` prints the `snapshot_id` and `state`: ```output f566b03b-b85e-41a0-b903-875cd305c1c5 COMPLETE ``` #### create\_snapshot Creates a snapshot of the specified YCQL tables and their indexes. Prior to v.2.1.8, indexes were not automatically included. You can specify multiple tables, even from different keyspaces. Snapshots don't auto-expire Snapshots you create via `create_snapshot` persist on disk until you remove them using the [delete\_snapshot](#delete-snapshot "delete_snapshot") command. Use the [create\_snapshot\_schedule](#create-snapshot-schedule "create_snapshot_schedule") command to create snapshots that expire after a specified time interval. **Syntax** ```sh yb-admin \ --master_addresses \ create_snapshot | \ [ | ]... \ [] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *keyspace*: The name of the database or keyspace formatted as <ycql|ysql>.. - *table-name*: The name of the table name. - *table-id*: The unique UUID associated with the table. - *flush-timeout-in-seconds*: Specifies duration (in seconds) before flushing snapshot. Default is `60`. To skip flushing, set the value to `0`. When this command runs, a `snapshot_id` is generated and printed. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ create_snapshot ydb test_tb ``` ```output Started flushing table ydb.test_tb Flush request id: fe0db953a7a5416c90f01b1e11a36d24 Waiting for flushing... Flushing complete: SUCCESS Started snapshot creation: 4963ed18fc1e4f1ba38c8fcf4058b295 ``` To see if the snapshot creation has finished, run the [yb-admin list\_snapshots](#list-snapshots "yb-admin list_snapshots") command. #### restore\_snapshot Restores the specified snapshot, including the tables and indexes. Optionally, you can restore to a point in time. To restore a distributed snapshot as part of a recovery workflow, see [Restore a snapshot](/stable/manage/backup-restore/snapshot-ysql/#restore-a-snapshot "Restore a snapshot") or [Restore to PIT](/stable/manage/backup-restore/point-in-time-recovery/restore/ "Restore to PIT"). To rewind a live database to a point in time, use [Rewind to PIT](/stable/manage/backup-restore/point-in-time-recovery/rewind/ "Rewind to PIT") (`restore_snapshot_schedule`). When the operation starts, a `restoration_id` is generated. Do not restore to a point before the most recent DDL `restore_snapshot` is a low-level command for sophisticated users building a custom backup and restore workflow. Most users should not use this command. Restoring to a time before a DDL change (for example, `CREATE TABLE`, `DROP TABLE`, or `ALTER TABLE`) can have unexpected effects (whether or not you supply *restore-target*). **Syntax** ```sh yb-admin \ --master_addresses \ restore_snapshot [] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *snapshot-id*: The identifier (ID) for the snapshot. - *restore-target*: Optional. A timestamp at or before the snapshot's creation time. Absolute Unix time, or a relative time such as `minus 5m`. Omit to restore to the snapshot's creation time. **Example** ```sh ./bin/yb-admin restore_snapshot 72ad2eb1-65a2-4e88-a448-7ef4418bc469 ``` When the restore starts, the `snapshot_id` and the generated `restoration_id` are displayed. ```output Started restoring snapshot: 72ad2eb1-65a2-4e88-a448-7ef4418bc469 Restoration id: 5a9bc559-2155-4c38-ac8b-b6d0f7aa1af6 ``` To see if the snapshot was successfully restored, you can run the [yb-admin list\_snapshots](#list-snapshots "yb-admin list_snapshots") command. ```sh ./bin/yb-admin list_snapshots ``` For the example above, the restore failed, so the following displays: ```output Restoration UUID State 5a9bc559-2155-4c38-ac8b-b6d0f7aa1af6 FAILED ``` #### list\_snapshot\_restorations Lists the snapshots restorations. Returns one or more restorations in JSON format. **restorations list** entries contain: - the restoration's unique ID - the snapshot's unique ID - state of the restoration **Syntax** ```sh yb-admin \ --master_addresses \ list_snapshot_restorations ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *restoration-id*: The snapshot restoration's unique identifier. Optional; omit the ID to return all restorations in the system. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ list_snapshot_restorations 26ed9053-0c26-4277-a2b8-c12d0fa4c8cf ``` ```output.json { "restorations": [ { "id": "26ed9053-0c26-4277-a2b8-c12d0fa4c8cf", "snapshot_id": "ca8f3763-5437-4594-818d-713fb0cddb96", "state": "RESTORED" } ] } ``` #### export\_snapshot Generates a metadata file for the specified snapshot, listing all the relevant internal UUIDs for various objects (table, tablet, etc.). **Syntax** ```sh yb-admin \ --master_addresses \ export_snapshot ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *snapshot-id*: The identifier (ID) for the snapshot. - *file-name*: The name of the file to contain the metadata. Recommended file extension is `.snapshot`. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ export_snapshot 4963ed18fc1e4f1ba38c8fcf4058b295 \ test_tb.snapshot ``` ```output Exporting snapshot 4963ed18fc1e4f1ba38c8fcf4058b295 (COMPLETE) to file test_tb.snapshot Snapshot meta data was saved into file: test_tb.snapshot ``` #### import\_snapshot Imports the specified snapshot metadata file. **Syntax** ```sh yb-admin \ --master_addresses \ import_snapshot \ [ [ ]...] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *file-name*: The name of the snapshot file to import - *keyspace*: The name of the database or keyspace - *table-name*: The name of the table Note The *keyspace* and the *table* can be different from the exported one. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ import_snapshot test_tb.snapshot ydb test_tb ``` ```output Read snapshot meta file test_tb.snapshot Importing snapshot 4963ed18fc1e4f1ba38c8fcf4058b295 (COMPLETE) Target imported table name: ydb.test_tb Table being imported: ydb.test_tb Successfully applied snapshot. Object Old ID New ID Keyspace c478ed4f570841489dd973aacf0b3799 c478ed4f570841489dd973aacf0b3799 Table ff4389ee7a9d47ff897d3cec2f18f720 ff4389ee7a9d47ff897d3cec2f18f720 Tablet 0 cea3aaac2f10460a880b0b4a2a4b652a cea3aaac2f10460a880b0b4a2a4b652a Tablet 1 e509cf8eedba410ba3b60c7e9138d479 e509cf8eedba410ba3b60c7e9138d479 Snapshot 4963ed18fc1e4f1ba38c8fcf4058b295 4963ed18fc1e4f1ba38c8fcf4058b295 ``` #### import\_snapshot\_selective Imports only the specified tables from the specified snapshot metadata file. **Syntax** ```sh yb-admin \ --master_addresses \ import_snapshot_selective \ [ [ ]...] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *file-name*: The name of the snapshot file to import - *keyspace*: The name of the database or keyspace - *table-name*: The name of the table Note The *keyspace* can be different from the exported one. The name of the table needs to be the same. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ import_snapshot_selective test_tb.snapshot ydb test_tb ``` ```output Read snapshot meta file test_tb.snapshot Importing snapshot 4963ed18fc1e4f1ba38c8fcf4058b295 (COMPLETE) Target imported table name: ydb.test_tb Table being imported: ydb.test_tb Successfully applied snapshot. Object Old ID New ID Keyspace c478ed4f570841489dd973aacf0b3799 c478ed4f570841489dd973aacf0b3799 Table ff4389ee7a9d47ff897d3cec2f18f720 ff4389ee7a9d47ff897d3cec2f18f720 Tablet 0 cea3aaac2f10460a880b0b4a2a4b652a cea3aaac2f10460a880b0b4a2a4b652a Tablet 1 e509cf8eedba410ba3b60c7e9138d479 e509cf8eedba410ba3b60c7e9138d479 Snapshot 4963ed18fc1e4f1ba38c8fcf4058b295 4963ed18fc1e4f1ba38c8fcf4058b295 ``` #### delete\_snapshot Deletes the specified snapshot. **Syntax** ```sh yb-admin \ --master_addresses \ delete_snapshot ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *snapshot-id*: The identifier (ID) of the snapshot. #### create\_snapshot\_schedule Creates a snapshot schedule for a YSQL database or YCQL keyspace. A schedule takes snapshots at a set interval and retains them for a configured duration. Creating a schedule also enables [Rewind to PIT](/stable/manage/backup-restore/point-in-time-recovery/rewind/ "Rewind to PIT") and [Clone to PIT](/stable/manage/backup-restore/point-in-time-recovery/clone/ "Clone to PIT") for that database or keyspace. Returns a schedule ID in JSON format. **Syntax** ```sh yb-admin create_snapshot_schedule \ --master_addresses \ \ \ ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *snapshot-interval*: The frequency at which to take snapshots, in minutes. - *retention-time*: The number of minutes to keep a snapshot before deleting it. - *filter-expression*: The set of objects to include in the snapshot. The filter expression is a list of acceptable objects, which can be either raw tables, keyspaces (YCQL) in the format `keyspace_name`, or databases (YSQL) in the format `ysql.database_name`. For proper consistency guarantees, set this up *per-keyspace* (YCQL) or *per-database* (YSQL). **Example** Take a snapshot of the YSQL database `yugabyte` once an hour, and retain each snapshot for 2 hours: ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ create_snapshot_schedule 60 120 ysql.yugabyte ``` The equivalent command for the YCQL keyspace `yugabyte` would be the following: ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ create_snapshot_schedule 60 120 yugabyte ``` ```output.json { "schedule_id": "6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256" } ``` #### list\_snapshot\_schedules Lists the snapshots associated with a given schedule. Or, lists all schedules and their associated snapshots. Returns one or more schedule lists in JSON format. **Schedule list** entries contain: - schedule ID - schedule options (interval and retention time) - a list of snapshots that the system has automatically taken **Snapshot list** entries include: - the snapshot's unique ID - the snapshot's creation time - the previous snapshot's creation time, if available. Use this time to make sure that, on restore, you pick the correct snapshot, which is guaranteed to have the data you want to bring back. **Syntax** ```sh yb-admin \ --master_addresses \ list_snapshot_schedules ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *schedule-id*: The snapshot schedule's unique identifier. Optional; omit the ID to return all schedules in the system. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ list_snapshot_schedules 6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256 ``` ```output.json { "schedules": [ { "id": "6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256", "options": { "interval": "60.000s", "retention": "600.000s" }, "snapshots": [ { "id": "386740da-dc17-4e4a-9a2b-976968b1deb5", "snapshot_time_utc": "2021-04-28T13:35:32.499002+0000" }, { "id": "aaf562ca-036f-4f96-b193-f0baead372e5", "snapshot_time_utc": "2021-04-28T13:36:37.501633+0000", "previous_snapshot_time_utc": "2021-04-28T13:35:32.499002+0000" } ] } ] } ``` #### edit\_snapshot\_schedule Edits a snapshot schedule. A schedule consists of a list of objects to be included in a snapshot, a time interval at which to take snapshots for them, and a retention time. **Syntax** ```sh yb-admin \ --master_addresses \ edit_snapshot_schedule \ [ interval ] \ [ retention ] \ ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *schedule-id*: The identifier (ID) of the schedule to be edited. - *snapshot-interval*: The frequency at which to take snapshots, in minutes. - *retention-time*: The number of minutes to keep a snapshot before deleting it. **Example** Edit a snapshot schedule to take a snapshot once every 90 minutes, and retain each snapshot for 3 hours: ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ edit_snapshot_schedule 6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256 \ interval 90 retention 180 ``` #### restore\_snapshot\_schedule A snapshot schedule is defined for a particular YSQL database or YCQL keyspace. When you [rewind](/stable/manage/backup-restore/point-in-time-recovery/rewind/ "rewind") that database or keyspace to a point in time, you choose the corresponding schedule and revert the state of all objects in it to the chosen time. **Syntax** ```sh yb-admin \ --master_addresses \ restore_snapshot_schedule ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *schedule-id*: The identifier (ID) of the schedule for the database or keyspace to rewind. - *restore-target*: The time to which to rewind the database or keyspace. This can be either an absolute Unix timestamp, or a relative time such as `minus 5m` (to rewind to 5 minutes ago). You can also use a [YSQL timestamp](/stable/api/ysql/datatypes/type_datetime/ "YSQL timestamp") or [YCQL timestamp](/stable/api/ycql/type_datetime/#timestamp "YCQL timestamp") with the command, if you like. In addition to rewinding to a particular timestamp, you can also rewind from a relative time, such as "ten minutes ago". When you specify a relative time, you can specify any or all of *days*, *hours*, *minutes*, and *seconds*. For example: - `minus 5m` to rewind from five minutes ago - `minus 1h` to rewind from one hour ago - `minus 3d` to rewind from three days ago - `minus 1h 5m` to rewind from one hour and five minutes ago Relative times can be in any of the following formats (again, note that you can specify any or all of days, hours, minutes, and seconds): - ISO 8601: `3d 4h 5m 6s` - Abbreviated PostgreSQL: `3 d 4 hrs 5 mins 6 secs` - Traditional PostgreSQL: `3 days 4 hours 5 minutes 6 seconds` - SQL standard: `D H:M:S` **Examples** Restore from an absolute timestamp: ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ restore_snapshot_schedule 6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256 1617670679185100 ``` Restore from a relative time: ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ restore_snapshot_schedule 6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256 minus 60s ``` In both cases, the output is similar to the following: ```output.json { "snapshot_id": "6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256", "restoration_id": "b1b96d53-f9f9-46c5-b81c-6937301c8eff" } ``` #### delete\_snapshot\_schedule Deletes the snapshot schedule with the given ID, **and all of the snapshots** associated with that schedule. Returns a JSON object with the `schedule_id` that was just deleted. **Syntax** ```sh yb-admin \ --master_addresses \ delete_snapshot_schedule ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *schedule-id*: The snapshot schedule's unique identifier. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ delete_snapshot_schedule 6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256 ``` The output should show the schedule ID we just deleted. ```output.json { "schedule_id": "6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256" } ``` #### clone\_namespace Creates a clone of a YSQL database or YCQL keyspace as of a point in time. The clone is a new database or keyspace on the same cluster. The source must have a [snapshot schedule](#create-snapshot-schedule "snapshot schedule") that covers the clone time. For YSQL, you can also clone using `CREATE DATABASE ... TEMPLATE ... AS OF`. See [Clone to PIT](/stable/manage/backup-restore/point-in-time-recovery/clone/ "Clone to PIT"). **Syntax** ```sh yb-admin \ --master_addresses \ clone_namespace [ | minus ] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *source-namespace*: The source YSQL database (`ysql.`) or YCQL keyspace (`ycql.`). If you omit the prefix, the name is treated as a YCQL keyspace. - *target-namespace-name*: The name of the new clone. - *timestamp*: Unix timestamp in microseconds, or a [YSQL](/stable/api/ysql/datatypes/type_datetime/ "YSQL") or [YCQL](/stable/api/ycql/type_datetime/#timestamp "YCQL") timestamp. Optional; omit to clone as of the current time. - `minus `: Clone as of a relative time, using the same formats as [restore\_snapshot\_schedule](#restore-snapshot-schedule "restore_snapshot_schedule"). **Examples** Clone a YCQL keyspace as of an absolute time: ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ clone_namespace ycql.originaldb1 clonedb2 1715275616599020 ``` Clone a YSQL database as of five minutes ago: ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ clone_namespace ysql.yugabyte cloned_db minus 5m ``` Clone a YSQL database as of the current time: ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ clone_namespace ysql.yugabyte cloned_db ``` When the clone starts, the command returns the source namespace ID and a sequence number you can pass to [list\_clones](#list-clones "list_clones"): ```output.json { "source_namespace_id": "00004000000030008000000000000000", "seq_no": "1" } ``` #### list\_clones Lists clone operations for a source YSQL database or YCQL keyspace. **Syntax** ```sh yb-admin \ --master_addresses \ list_clones [] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *source-namespace-id*: The identifier of the source database or keyspace. Find this ID on the YB-Master leader UI `/namespaces` endpoint, or in the output of [clone\_namespace](#clone-namespace "clone_namespace"). - *seq-no*: Optional sequence number of a specific clone. Omit to list all clones of the source. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ list_clones 00004000000030008000000000000000 ``` ```output.json [ { "aggregate_state": "COMPLETE", "source_namespace_id": "00004000000030008000000000000000", "seq_no": "1", "target_namespace_name": "testing_clone_db", "restore_time": "2024-08-09 21:42:16.451974" } ] ``` To check a specific clone, pass the sequence number: ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ list_clones 00004000000030008000000000000000 1 ``` If a clone was aborted, the entry includes an `abort_message`. * * * ### Multi-zone and multi-region deployment commands #### modify\_placement\_info Modifies the placement information (cloud, region, and zone) for a deployment. **Syntax** ```sh yb-admin \ --master_addresses \ modify_placement_info \ [ ] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *placement-info*: Comma-delimited list of placements in the form *cloud*.*region*.*zone*`[:min[:max]]`. The optional minimum indicates how many replicas of each tablet must be placed in the block; it defaults to 1. The optional maximum limits how many replicas of one tablet can be placed in the block; when omitted, the number of replicas in the block is only limited by the replication factor. Maximums are only supported when every placement block in the policy is fully qualified; if any block specifies a maximum, no block in the policy may use the wildcard (`*`) placements described below. It is not recommended to repeat the same placement multiple times, but instead to specify the total counts after the colons. However, if you repeat a placement, its minimums are summed, and its maximums are summed if every occurrence specifies one (if any occurrence omits the maximum, the block has no maximum). For example, `aws.us-west.us-west-2a:1:2,aws.us-west.us-west-2a:1:2` is equivalent to `aws.us-west.us-west-2a:2:4`, whereas `aws.us-west.us-west-2a:1:2,aws.us-west.us-west-2a:1` is equivalent to `aws.us-west.us-west-2a:2`. - *replication-factor*: The number of replicas for each tablet. This value should be greater than or equal to the total of minimum replica counts specified in *placement-info*, and less than or equal to the total of maximum replica counts. - *placement-id*: The identifier of the primary cluster, which can be any unique string. Optional; if not set, a randomly-generated ID is used. **Example** ```sh ./bin/yb-admin \ --master_addresses $MASTER_RPC_ADDRS \ modify_placement_info \ aws.us-west.us-west-2a:2,aws.us-west.us-west-2b:2,aws.us-west.us-west-2c 5 ``` This will place a minimum of: 1. 2 replicas in aws.us-west.us-west-2a 2. 2 replicas in aws.us-west.us-west-2b 3. 1 replica in aws.us-west.us-west-2c To additionally limit how many replicas of each tablet can be placed in a zone, specify a maximum after the minimum: ```sh ./bin/yb-admin \ --master_addresses $MASTER_RPC_ADDRS \ modify_placement_info \ aws.us-west.us-west-2a:1:2,aws.us-west.us-west-2b:1:2,aws.us-west.us-west-2c:1:2 5 ``` This permits: 1. Between 1 and 2 replicas in aws.us-west.us-west-2a 2. Between 1 and 2 replicas in aws.us-west.us-west-2b 3. Between 1 and 2 replicas in aws.us-west.us-west-2c The maximum is a hard cap on placement decisions: neither table creation nor the load balancer will add replicas above a block's maximum, even if that means a tablet is temporarily under-replicated while other placement blocks lack tablet servers. The one exception is transient: when replacing a replica within the same block (for example, moving data off a blacklisted server onto another server in the same zone), the replacement replica is added before the old one is removed, so the block can briefly hold one replica above its maximum until the removal completes. You can verify the new placement information by running the following `curl` command: ```sh curl -s http://:7000/cluster-config ``` Use the wildcard `*` to allow placement in any zone in a specific region or any region in a specific cloud. For example: ```sh ./bin/yb-admin \ --master_addresses $MASTER_RPC_ADDRS \ modify_placement_info \ aws.*.*:5 5` ``` This requests a placement of 5 replicas anywhere in the `aws` cloud. Similarly: ```sh ./bin/yb-admin \ --master_addresses $MASTER_RPC_ADDRS \ modify_placement_info \ aws.us-east-1.*:3 3` ``` This requests a placement of 3 replicas anywhere in the `us-east-1` region of `aws` cloud. #### set\_preferred\_zones Sets [leader affinity](/stable/architecture/key-concepts/#leader-affinity "leader affinity") for the cluster (preferred zones). The load balancer places tablet leaders on alive, healthy replicas in the listed availability zones, in order of preference. When no healthy replica is available in preference 1, preference 2 is used, and so on. Zones you omit are used only after every preferred rank is exhausted. This command does not change tablet replica placement (use [modify\_placement\_info](#modify-placement-info "modify_placement_info")) and does not move YB-Master processes. By default, the sys catalog (master) leader steps down onto a master that is already running in a preferred zone. Having tablet leaders in a single region reduces the number of network hops for transactional writes, which lowers latency. Note - Make sure you've already run [modify\_placement\_info](#modify-placement-info "modify_placement_info"). Preferred zones must match existing placement blocks. - By default, transaction status tablet leaders don't respect these preferred zones and are balanced across all nodes. Transactions include a roundtrip from the user to the transaction status tablet serving the transaction; using the leader closest to the user rather than forcing a roundtrip to the preferred zone improves performance. - Leader-blacklisted nodes don't host any leaders, regardless of preference. - Cluster configuration stores preferred zones in `multi_affinitized_leaders`. Older clusters may still have `affinitized_leaders`; this command rewrites the list as `multi_affinitized_leaders`. - Tablespaces don't inherit cluster-level placement information, leader preference, or read replica configurations. - If the client application uses a smart driver, set the [topology keys](/stable/develop/drivers-orms/smart-drivers/#topology-aware-load-balancing "topology keys") to target the preferred zones. **Syntax** ```sh yb-admin \ --master_addresses \ set_preferred_zones [:] \ [[:]]... ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *cloud.region.zone*: Specifies the cloud, region, and zone. Use `*` for any zone in a region (`gcp.us-west1.*`) or any region in a cloud (`gcp.*.*`). Default is `cloud1.datacenter1.rack1`. - *preference*: Leader preference. Values must be contiguous integers starting at 1. Multiple zones can share a value (leaders are spread across them). Default is 1. **Example** Suppose you have a deployment in the following regions: `gcp.us-west1.us-west1-a`, `gcp.us-west1.us-west1-b`, `gcp.asia-northeast1.asia-northeast1-a`, and `gcp.us-east4.us-east4-a`. Looking at the cluster configuration: ```sh curl -s http://:7000/cluster-config ``` The following is a sample configuration: ```output replication_info { live_replicas { num_replicas: 5 placement_blocks { cloud_info { placement_cloud: "gcp" placement_region: "us-west1" placement_zone: "us-west1-a" } min_num_replicas: 1 } placement_blocks { cloud_info { placement_cloud: "gcp" placement_region: "us-west1" placement_zone: "us-west1-b" } min_num_replicas: 1 } placement_blocks { cloud_info { placement_cloud: "gcp" placement_region: "us-east4" placement_zone: "us-east4-a" } min_num_replicas: 2 } placement_blocks { cloud_info { placement_cloud: "gcp" placement_region: "us-asia-northeast1" placement_zone: "us-asia-northeast1-a" } min_num_replicas: 1 } } } ``` The following command prefers both zones in `gcp.us-west1` (rank 1) and falls back to `gcp.us-east4.us-east4-a` (rank 2): ```sh ssh -i $PEM $ADMIN_USER@$MASTER1 \ ~/master/bin/yb-admin --master_addresses $MASTER_RPC_ADDRS \ set_preferred_zones \ gcp.us-west1.us-west1-a:1 \ gcp.us-west1.us-west1-b:1 \ gcp.us-east4.us-east4-a:2 ``` The equivalent region-level form is `gcp.us-west1.*:1 gcp.us-east4.us-east4-a:2`. Verify by running the following. ```sh curl -s http://:7000/cluster-config ``` Looking again at the cluster configuration you should see `multi_affinitized_leaders` added: ```output replication_info { live_replicas { num_replicas: 5 placement_blocks { cloud_info { placement_cloud: "gcp" placement_region: "us-west1" placement_zone: "us-west1-a" } min_num_replicas: 1 } placement_blocks { cloud_info { placement_cloud: "gcp" placement_region: "us-west1" placement_zone: "us-west1-b" } min_num_replicas: 1 } placement_blocks { cloud_info { placement_cloud: "gcp" placement_region: "us-east4" placement_zone: "us-east4-a" } min_num_replicas: 2 } placement_blocks { cloud_info { placement_cloud: "gcp" placement_region: "us-asia-northeast1" placement_zone: "us-asia-northeast1-a" } min_num_replicas: 1 } } multi_affinitized_leaders { zones { placement_cloud: "gcp" placement_region: "us-west1" placement_zone: "us-west1-a" } zones { placement_cloud: "gcp" placement_region: "us-west1" placement_zone: "us-west1-b" } } multi_affinitized_leaders { zones { placement_cloud: "gcp" placement_region: "us-east4" placement_zone: "us-east4-a" } } } ``` ### Read replica deployment commands #### add\_read\_replica\_placement\_info Add a read replica cluster to the master configuration. **Syntax** ```sh yb-admin \ --master_addresses \ add_read_replica_placement_info \ \ [ ] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *placement-info*: A comma-delimited list of read replica placements for *cloud*.*region*.*zone*, using the format `:,:,...`. Default is `cloud1.datacenter1.rack1`. Read replica availability zones must be uniquely different from the primary availability zones. To use the same cloud, region, and availability zone for a read replica as a primary cluster, you can suffix the zone with `_rr` (for read replica). For example, `c1.r1.z1` vs `c1.r1.z1_rr:1`. - *replication-factor*: The total number of read replicas. - *placement-id*: The identifier of the read replica cluster, which can be any unique string. If not set, a randomly-generated ID will be used. Primary and read replica clusters must use different placement IDs. #### modify\_read\_replica\_placement\_info **Syntax** ```sh yb-admin \ --master_addresses \ modify_read_replica_placement_info \ \ [ ] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *placement-info*: A comma-delimited list of placements for *cloud*.*region*.*zone*. Default is `cloud1.datacenter1.rack1`. - *replication-factor*: The number of replicas. - *placement-id*: The identifier of the read replica cluster. #### delete\_read\_replica\_placement\_info Delete the read replica. **Syntax** ```sh yb-admin \ --master_addresses \ delete_read_replica_placement_info ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. * * * ### Security commands #### Encryption at rest commands For details on using encryption at rest, see [Encryption at rest](/stable/secure/encryption-at-rest "Encryption at rest"). #### add\_universe\_key\_to\_all\_masters Sets the contents of *key-path* in-memory on each YB-Master node. **Syntax** ```sh yb-admin \ --master_addresses \ add_universe_key_to_all_masters ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *key-id*: Universe-unique identifier (can be any string, such as a string of a UUID) that will be associated to the universe key contained in the contents of *key-path* as a byte\[]. - *key-path*: The path to the file containing the universe key. Note After adding the universe keys to all YB-Master nodes, you can verify the keys exist using the [all\_masters\_have\_universe\_key\_in\_memory](#all-masters-have-universe-key-in-memory "all_masters_have_universe_key_in_memory") command and enable encryption using the [rotate\_universe\_key\_in\_memory](#rotate-universe-key-in-memory "rotate_universe_key_in_memory") command. #### all\_masters\_have\_universe\_key\_in\_memory Checks whether the universe key associated with the provided *key-id* exists in-memory on each YB-Master node. ```sh yb-admin \ --master_addresses all_masters_have_universe_key_in_memory ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *key-id*: Universe-unique identifier (can be any string, such as a string of a UUID) that will be associated to the universe key contained in the contents of *key-path* as a byte\[]. #### rotate\_universe\_key\_in\_memory Rotates the in-memory universe key to start encrypting newly-written data files with the universe key associated with the provided *key-id*. Note The [all\_masters\_have\_universe\_key\_in\_memory](#all-masters-have-universe-key-in-memory "all_masters_have_universe_key_in_memory") value must be true for the universe key to be successfully rotated and enabled). **Syntax** ```sh yb-admin \ --master_addresses rotate_universe_key_in_memory ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *key-id*: Universe-unique identifier (can be any string, such as a string of a UUID) that will be associated to the universe key contained in the contents of *key-path* as a byte\[]. #### disable\_encryption\_in\_memory Disables the in-memory encryption at rest for newly-written data files. **Syntax** ```sh yb-admin \ --master_addresses \ disable_encryption_in_memory ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. #### is\_encryption\_enabled Checks if cluster-wide encryption is enabled. **Syntax** ```sh yb-admin \ --master_addresses \ is_encryption_enabled ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. Returns message: ```output Encryption status: ENABLED with key id ``` The new key ID (``) should be different from the previous one (``). **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ is_encryption_enabled ``` ```output Encryption status: ENABLED with key id ``` ### Change Data Capture (CDC) commands #### create\_change\_data\_stream Create a change data capture (CDC) DB stream for the specified namespace using the following command. Legacy workflow Use `yb-admin create_change_data_stream` to create streams in versions earlier than v2026.1.2.0. [EA](/stable/releases/versioning/#feature-maturity) In YugabyteDB v2026.1.2.0 and later, create and manage gRPC CDC streams using the PostgreSQL replication slot syntax and the `yb_grpc` output plugin. For example, `SELECT * FROM pg_create_logical_replication_slot('', 'yb_grpc');`. See [Create a gRPC CDC stream](/stable/additional-features/change-data-capture/using-yugabytedb-grpc-replication/cdc-get-started/#create-a-grpc-cdc-stream "Create a gRPC CDC stream"). **Syntax** ```sh yb-admin \ --master_addresses \ create_change_data_stream ysql. ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *namespace-name*: The namespace on which the DB stream ID is to be created. For example: ```sh ./bin/yb-admin \ --master_addresses 127.0.0.1:7100 \ create_change_data_stream ysql.yugabyte ``` ##### Creating a stream for Transactional CDC Create a change data capture (CDC) DB stream for the specified namespace that can be used for Transactional CDC using the following command. This feature is [TP](/stable/releases/versioning/#feature-maturity) . Use the [yb\_enable\_cdc\_consistent\_snapshot\_streams](/stable/reference/configuration/yb-tserver/#yb-enable-cdc-consistent-snapshot-streams "yb_enable_cdc_consistent_snapshot_streams") flag to enable the feature. **Syntax** ```sh yb-admin \ --master_addresses \ create_change_data_stream ysql. [EXPLICIT] [] [USE_SNAPSHOT | NOEXPORT_SNAPSHOT] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *namespace-name*: The namespace on which the DB stream ID is to be created. - EXPLICIT: Checkpointing type on the server. See [Creating stream in EXPLICIT checkpointing mode](#creating-stream-in-explicit-checkpointing-mode "Creating stream in EXPLICIT checkpointing mode"). - *before-image-mode*: Record type indicating to the server that the stream should send only the new values of the changed columns. See [Enabling before image](#enabling-before-image "Enabling before image"). - USE\_SNAPSHOT: Snapshot option indicating intention of client to consume the snapshot. If you don't want the client to consume the snapshot, use the NOEXPORT\_SNAPSHOT option. For example: ```sh ./bin/yb-admin \ --master_addresses 127.0.0.1:7100 \ create_change_data_stream ysql.yugabyte EXPLICIT CHANGE USE_SNAPSHOT ``` ##### Enabling before image To create a change data capture (CDC) DB stream which also supports sending the before image of the record, use the following command. **Syntax** ```sh yb-admin \ --master_addresses \ create_change_data_stream ysql. [EXPLICIT] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *namespace-name*: The namespace on which the DB stream ID is to be created. - EXPLICIT: Checkpointing type on the server. See [Creating stream in EXPLICIT checkpointing mode](#creating-stream-in-explicit-checkpointing-mode "Creating stream in EXPLICIT checkpointing mode"). - *before-image-mode*: Record type indicating to the server that the stream should send only the new values of the changed columns. Refer to [Before image modes](/stable/additional-features/change-data-capture/using-yugabytedb-grpc-replication/cdc-get-started/#before-image-modes "Before image modes"). A successful operation of the above command returns a message with a DB stream ID: ```output CDC Stream ID: d540f5e4890c4d3b812933cbfd703ed3 ``` ##### Creating stream in EXPLICIT checkpointing mode To create a change data capture (CDC) DB stream which works in the EXPLICIT checkpointing mode where the client is responsible for managing the checkpoints, use the following command: **Syntax** ```sh yb-admin \ --master_addresses \ create_change_data_stream ysql. EXPLICIT ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *namespace-name*: The namespace on which the DB stream ID is to be created. - EXPLICIT: Checkpointing type on the server. A successful operation of the above command returns a message with a DB stream ID: ```output CDC Stream ID: d540f5e4890c4d3b812933cbfd703ed3 ``` IMPLICIT checkpointing is deprecated It is recommended that you create streams in EXPLICIT checkpointing mode only (the default). IMPLICIT checkpointing mode will be completely removed in future releases. #### list\_change\_data\_streams Lists all the created CDC DB streams. **Syntax** ```sh yb-admin \ --master_addresses \ list_change_data_streams [namespace-name] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *namespace-name*: (Optional) The namespace name for which to list the streams. If not specified, all streams are listed without filtering. **Example:** ```sh ./bin/yb-admin \ --master_addresses 127.0.0.1:7100 \ list_change_data_streams ``` This command results in the following response. It will have all the table IDs associated with the stream ID: ```output CDC Streams: streams { stream_id: "d540f5e4890c4d3b812933cbfd703ed3" table_id: "000033e1000030008000000000004000" options { key: "id_type" value: "NAMESPACEID" } options { key: "checkpoint_type" value: "EXPLICIT" } options { key: "source_type" value: "CDCSDK" } options { key: "record_format" value: "PROTO" } options { key: "record_type" value: "CHANGE" } options { key: "state" value: "ACTIVE" } } ``` #### get\_change\_data\_stream\_info Get the information associated with a particular CDC DB stream. **Syntax** ```sh yb-admin \ --master_addresses \ get_change_data_stream_info ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *db-stream-id*: The CDC DB stream ID to get the info of. **Example:** ```sh ./bin/yb-admin \ --master_addresses 127.0.0.1:7100 \ get_change_data_stream_info d540f5e4890c4d3b812933cbfd703ed3 ``` The previous command results in the following response. It will have the table\_id(s) associated with the stream and the namespace\_id on which the stream is created: ```output CDC DB Stream Info: table_info { stream_id: "d540f5e4890c4d3b812933cbfd703ed3" table_id: "000033e1000030008000000000004000" } namespace_id: "000033e1000030008000000000000000" ``` #### delete\_change\_data\_stream Delete the specified CDC DB stream. **Syntax** ```sh yb-admin \ --master_addresses \ delete_change_data_stream ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *db-stream-id*: The CDC DB stream ID to be deleted. **Example:** ```sh ./bin/yb-admin \ --master_addresses 127.0.0.1:7100 \ delete_change_data_stream d540f5e4890c4d3b812933cbfd703ed3 ``` The above command results in the following response: ```output Successfully deleted CDC DB Stream ID: d540f5e4890c4d3b812933cbfd703ed3 ``` ### xCluster Replication Commands For detailed step-by-step instructions on deploying xCluster, refer to the [Deploy xCluster](/stable/deploy/multi-dc/async-replication "Deploy xCluster"). For monitoring xCluster, refer to [Monitor xCluster](/stable/launch-and-manage/monitor-and-alert/xcluster-monitor "Monitor xCluster"). #### setup\_universe\_replication Sets up the universe replication for the specified source universe. Use this command only if no tables have been configured for replication. If tables are already configured for replication, use [alter\_universe\_replication](#alter-universe-replication "alter_universe_replication") to add more tables. To verify if any tables are already configured for replication, use [list\_cdc\_streams](#list-cdc-streams "list_cdc_streams"). **Syntax** ```sh yb-admin \ --master_addresses \ setup_universe_replication \ \ \ \ [ ] \ [ transactional ] ``` - *target-master-addresses*: Comma-separated list of target YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. - *source-master-addresses*: Comma-separated list of the source master addresses. - *source-table-ids*: Comma-separated list of source universe table identifiers (`table_id`). - *bootstrap-ids*: Comma-separated list of source universe bootstrap identifiers (`bootstrap_id`). Obtain these with [bootstrap\_cdc\_producer](#bootstrap-cdc-producer-comma-separated-list-of-table-ids "bootstrap_cdc_producer"), using a comma-separated list of source universe table IDs. - `transactional`: identifies the universe as Active in a transactional xCluster deployment. Important Enter the source universe bootstrap IDs in the same order as their corresponding table IDs. Tip To display a list of tables and their UUID (`table_id`) values, open the **YB-Master UI** (`:7000/`) and click **Tables** in the navigation bar. **Example** ```sh ./bin/yb-admin \ --master_addresses 127.0.0.11:7100,127.0.0.12:7100,127.0.0.13:7100 \ setup_universe_replication e260b8b6-e89f-4505-bb8e-b31f74aa29f3_xClusterSetup1 \ 127.0.0.1:7100,127.0.0.2:7100,127.0.0.3:7100 \ 000030a5000030008000000000004000,000030a5000030008000000000004005,dfef757c415c4b2cacc9315b8acb539a ``` #### alter\_universe\_replication Changes the universe replication for the specified source universe. Use this command to do the following: - Add or remove tables in an existing replication UUID. - Modify the source master addresses. If no tables have been configured for replication, use [setup\_universe\_replication](#setup-universe-replication "setup_universe_replication"). To check if any tables are configured for replication, use [list\_cdc\_streams](#list-cdc-streams "list_cdc_streams"). **Syntax** Use the `set_master_addresses` subcommand to replace the source master address list. Use this if the set of masters on the source changes: ```sh yb-admin --master_addresses \ alter_universe_replication \ set_master_addresses ``` - *target-master-addresses*: Comma-separated list of target YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. - *source-master-addresses*: Comma-separated list of the source master addresses. Use the `add_table` subcommand to add one or more tables to the existing list: ```sh yb-admin --master_addresses \ alter_universe_replication \ add_table \ [ ] ``` - *target-master-addresses*: Comma-separated list of target YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. - *source-table-ids*: Comma-separated list of source universe table identifiers (`table_id`). - *bootstrap-ids*: Comma-separated list of source universe bootstrap identifiers (`bootstrap_id`). Obtain these with [bootstrap\_cdc\_producer](#bootstrap-cdc-producer-comma-separated-list-of-table-ids "bootstrap_cdc_producer"), using a comma-separated list of source universe table IDs. Important Enter the source universe bootstrap IDs in the same order as their corresponding table IDs. Use the `remove_table` subcommand to remove one or more tables from the existing list: ```sh yb-admin --master_addresses \ alter_universe_replication \ remove_table [ignore-errors] ``` - *target-master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. - *source-table-ids*: Comma-separated list of source universe table identifiers (`table_id`). - `ignore-errors`: Execute the command, ignoring any errors. It is recommended that you contact support before using this option. Use the `rename_id` subcommand to rename xCluster replication streams. ```sh yb-admin --master_addresses \ alter_universe_replication \ rename_id ``` - *target-master-addresses*: Comma-separated list of target YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The existing replication group identifier. - *new-replication-group-id*: The new replication group identifier. #### delete\_universe\_replication <source\_universe\_uuid> Deletes universe replication for the specified source universe. **Syntax** ```sh yb-admin \ --master_addresses \ delete_universe_replication ``` - *target-master-addresses*: Comma-separated list of target YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. #### set\_universe\_replication\_enabled Sets the universe replication to be enabled or disabled. **Syntax** ```sh yb-admin \ --master_addresses \ set_universe_replication_enabled [0|1] ``` - *target-master-addresses*: Comma-separated list of target YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. - `0` | `1`: Disabled (`0`) or enabled (`1`). Default is `1`. #### get\_xcluster\_safe\_time Reports the current xCluster safe time for each namespace, which is the time at which reads will be performed. **Syntax** ```sh yb-admin \ --master_addresses \ get_xcluster_safe_time \ [include_lag_and_skew] ``` - *target-master-addresses*: Comma-separated list of target YB-Master hosts and ports. Default is `localhost:7100`. - `include_lag_and_skew`: Display the `safe_time_lag_sec` and `safe_time_skew_sec`. **Example** ```sh ./bin/yb-admin \ --master_addresses 127.0.0.11:7100,127.0.0.12:7100,127.0.0.13:7100 \ get_xcluster_safe_time include_lag_and_skew ``` ```output { "namespace_id": "000033f1000030008000000000000000", "namespace_name": "yugabyte", "safe_time": "2023-04-14 18:34:18.429430", "safe_time_epoch": "1681522458429430", "safe_time_lag_sec": "15.66", "safe_time_skew_sec": "14.95" } ``` - *namespace\_id*: ID of the stream. - *namespace\_name*: Name of the stream. - *safe\_time*: Safe time in timestamp format. - *safe\_time\_epoch*: The `epoch` of the safe time. - *safe\_time\_lag\_sec*: Safe time lag is computed as `(current time - current safe time)`. - *safe\_time\_skew\_sec*: Safe time skew is computed as `(safe time of most caught up tablet - safe time of laggiest tablet)`. #### wait\_for\_replication\_drain Verify when the producer and consumer are in sync for a given list of `stream_ids` at a given timestamp. **Syntax** ```sh yb-admin \ --master_addresses \ wait_for_replication_drain \ [ | minus ] ``` - *source-master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *stream-ids*: Comma-separated list of stream IDs. - *timestamp*: The time to which to wait for replication to drain. If not provided, it will be set to current time in the YB-Master API. - `minus `: The same format as described in [Restore from a relative time](/stable/explore/cluster-management/point-in-time-recovery-ysql/#restore-from-a-relative-time "Restore from a relative time"), or see [restore\_snapshot\_schedule](#restore-snapshot-schedule "restore_snapshot_schedule"). **Example** ```sh ./bin/yb-admin \ --master_addresses 127.0.0.1:7100,127.0.0.2:7100,127.0.0.3:7100 \ wait_for_replication_drain 000033f1000030008000000000000000,200033f1000030008000000000000002 minus 1m ``` If all streams are caught-up, the API outputs `All replications are caught-up.` to the console. Otherwise, it outputs the non-caught-up streams in the following format: ```output Found undrained replications: - Under Stream : - Tablet: - Tablet: // ...... // ...... ``` #### list\_cdc\_streams Lists the xCluster outbound streams. Tip Use this command when setting up xCluster replication to verify if any tables are configured for replication. If not, run [setup\_universe\_replication](#setup-universe-replication "setup_universe_replication"); if tables are already configured for replication, use [alter\_universe\_replication](#alter-universe-replication "alter_universe_replication") to add more tables. **Syntax** ```sh yb-admin \ --master_addresses \ list_cdc_streams ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. **Example** ```sh ./bin/yb-admin \ --master_addresses 127.0.0.11:7100,127.0.0.12:7100,127.0.0.13:7100 \ list_cdc_streams ``` #### delete\_cdc\_stream Deletes underlying xCluster outbound streams. **Syntax** ```sh yb-admin \ --master_addresses \ delete_cdc_stream \ [force_delete] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *stream-id*: The ID of the xCluster stream. - `force_delete`: Force the delete operation. Note This command should only be needed for advanced operations, such as doing manual cleanup of old bootstrapped streams that were never fully initialized, or otherwise failed replication streams. For normal xCluster replication cleanup, use [delete\_universe\_replication](#delete-universe-replication-source-universe-uuid "delete_universe_replication"). #### bootstrap\_cdc\_producer Mark a set of tables in preparation for setting up xCluster replication. **Syntax** ```sh yb-admin \ --master_addresses \ bootstrap_cdc_producer ``` - *source-master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *source-table-ids*: Comma-separated list of unique UUIDs associated with the tables (`table_id`). **Example** ```sh ./bin/yb-admin \ --master_addresses 172.0.0.11:7100,127.0.0.12:7100,127.0.0.13:7100 \ bootstrap_cdc_producer 000030ad000030008000000000004000 ``` ```output table id: 000030ad000030008000000000004000, CDC bootstrap id: dd5ea73b5d384b2c9ebd6c7b6d05972c ``` Note The xCluster bootstrap IDs are the ones that should be used with [setup\_universe\_replication](#setup-universe-replication "setup_universe_replication") and [alter\_universe\_replication](#alter-universe-replication "alter_universe_replication"). #### get\_replication\_status Returns the xCluster replication status of all inbound replication groups. If *replication-group-id* is provided, this will only return streams that belong to an associated replication group. **Syntax** ```sh yb-admin \ --master_addresses \ get_replication_status [ ] ``` - *target-master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. **Example** ```sh ./bin/yb-admin \ --master_addresses 172.0.0.11:7100,127.0.0.12:7100,127.0.0.13:7100 \ get_replication_status e260b8b6-e89f-4505-bb8e-b31f74aa29f3 ``` ```output statuses { table_id: "03ee1455f2134d5b914dd499ccad4377" stream_id: "53441ad2dd9f4e44a76dccab74d0a2ac" errors { error: REPLICATION_MISSING_OP_ID error_detail: "Unable to find expected op id on the producer" } } ``` #### create\_xcluster\_checkpoint Checkpoint namespaces for use in xCluster replication. **Syntax** ```sh yb-admin \ --master_addresses \ create_xcluster_checkpoint \ \ \ [automatic_ddl_mode] ``` - *source-master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. - *namespace\_names*: Comma-separated list of namespaces. - `automatic_ddl_mode`: Use [xCluster automatic mode](/stable/deploy/multi-dc/async-replication/async-transactional-setup-automatic/ "xCluster automatic mode"). #### is\_xcluster\_bootstrap\_required Checks if the databases of a previously checkpointed replication group requires a bootstrap (backup/restore) of the database to the target universe. **Syntax** ```sh yb-admin \ --master_addresses \ is_xcluster_bootstrap_required \ \ ``` - *source-master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. - *namespace-names*: Comma-separated list of namespaces. #### setup\_xcluster\_replication Setup xCluster replication using a previously created [checkpoint](#create-xcluster-checkpoint "checkpoint"). **Syntax** ```sh yb-admin \ --master_addresses \ setup_xcluster_replication \ \ ``` - *source-master-addresses*: Comma-separated list of source universe YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. - *target-master-addresses*: Comma-separated list of target universe YB-Master hosts and ports. Default is `localhost:7100`. #### drop\_xcluster\_replication Drops the xCluster replication group. If *target-master-addresses* are provided, it will also drop the replication on the target universe. **Syntax** ```sh yb-admin \ --master_addresses \ drop_xcluster_replication \ \ [] ``` - *source-master-addresses*: Comma-separated list of source universe YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. - *target-master-addresses*: Comma-separated list of target universe YB-Master hosts and ports. Default is `localhost:7100`. #### add\_namespace\_to\_xcluster\_checkpoint Adds a database to an existing xCluster checkpoint. **Syntax** ```sh yb-admin \ --master_addresses \ add_namespace_to_xcluster_checkpoint \ \ ``` - *source-master-addresses*: Comma-separated list of source universe YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. - *namespace-name*: The namespace to checkpoint. #### add\_namespace\_to\_xcluster\_replication Adds a database to an existing xCluster replication after it has been checkpointed (and bootstrapped if needed). **Syntax** ```sh yb-admin \ --master_addresses \ add_namespace_to_xcluster_replication \ \ \ ``` - *source-master-addresses*: Comma-separated list of source universe YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. - *namespace-name*: The namespace name. - *target-master-addresses*: Comma-separated list of target universe YB-Master hosts and ports. Default is `localhost:7100`. #### remove\_namespace\_from\_xcluster\_replication Removes a database from an existing xCluster replication. If target master addresses are provided, it will also remove the database from the target universe xCluster metadata. **Syntax** ```sh yb-admin \ --master_addresses \ remove_namespace_from_xcluster_replication \ \ \ [] ``` - *source-master-addresses*: Comma-separated list of source universe YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. - *namespace-name*: The namespace name. - *target-master-addresses*: Comma-separated list of target universe YB-Master hosts and ports. Default is `localhost:7100`. #### list\_xcluster\_outbound\_replication\_groups List The replication group identifiers for all outbound xCluster replications. If namespace-id is provided, only the replication groups for that namespace will be returned. **Syntax** ```sh yb-admin \ --master_addresses \ list_xcluster_outbound_replication_groups \ [] ``` - *source-master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *namespace-id*: The namespace UUID. #### get\_xcluster\_outbound\_replication\_group\_info Display the status of a specific outbound xCluster replication group. **Syntax** ```sh yb-admin \ --master_addresses \ get_xcluster_outbound_replication_group_info \ ``` - *source-master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *replication-group-id*: The replication group identifier. #### list\_universe\_replications List The replication group identifiers for all inbound xCluster replications. If *namespace-id* is provided, only the replication groups for that namespace will be returned. **Syntax** ```sh yb-admin \ --master_addresses \ list_universe_replications \ [] ``` - *target-master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *namespace-id*: The namespace UUID. * * * ### Decommissioning commands #### are\_nodes\_safe\_to\_take\_down Checks whether the specified nodes can be taken down without losing quorum. Use this before planned maintenance (for example, rolling upgrades or reboots) to ensure that taking down the given tablet servers or masters will not cause loss of replication quorum. Available in YugabyteDB versions [v2024.2.8.0](/stable/releases/ybdb-releases/v2024.2#v2024.2.8.0) and later, [v2025.1.4.0](/stable/releases/ybdb-releases/v2025.1#v2025.1.4.0) and later, and [v2025.2](/stable/releases/ybdb-releases/v2025.2). **Syntax** ```sh yb-admin \ --master_addresses \ are_nodes_safe_to_take_down [follower_lag_bound_ms] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *server-uuids*: Comma-separated list of YB-TServer or YB-Master server UUIDs to check. Obtain UUIDs using `list_all_tablet_servers` and `list_all_masters`. - `follower_lag_bound_ms`: Optional. Maximum allowed follower lag in milliseconds. Default is `1000`. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ are_nodes_safe_to_take_down 000033eb000030008000000000004002 ``` To check multiple nodes with a custom follower lag bound (for example, 2000 ms): ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ are_nodes_safe_to_take_down 1b9486461cdd48f59eb46b33992cd73a, c0505f1d31774a3d88fae26ce14cde10 2000 ``` #### get\_leader\_blacklist\_completion Gets the tablet load move completion percentage for blacklisted nodes. **Syntax** ```sh yb-admin \ --master_addresses \ get_leader_blacklist_completion ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ get_leader_blacklist_completion ``` #### change\_blacklist Changes the blacklist for YB-TServer servers. After old YB-TServer servers are terminated, you can use this command to clean up the blacklist. **Syntax** ```sh yb-admin \ --master_addresses \ change_blacklist [ ADD | REMOVE ] : \ [ : ]... ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - ADD | REMOVE: Adds or removes the specified YB-TServer server from blacklist. - *ip\_addr:port*: The IP address and port of the YB-TServer. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ change_blacklist \ ADD node1:9100 node2:9100 node3:9100 node4:9100 node5:9100 node6:9100 ``` #### change\_leader\_blacklist **Syntax** ```sh yb-admin \ --master_addresses \ change_leader_blacklist [ ADD | REMOVE ] : \ [ : ]... ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - ADD | REMOVE: Adds or removes the specified YB-Master, or YB-TServer from leader blacklist. - *ip\_addr:port*: The IP address and port of the YB-TServer. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ change_leader_blacklist \ ADD node1:9100 node2:9100 node3:9100 node4:9100 node5:9100 node6:9100 ``` #### leader\_stepdown Forces the YB-TServer leader of the specified tablet to step down. Note Use this command only if recommended by Yugabyte support. There is a possibility of downtime. **Syntax** ```sh yb-admin \ --master_addresses \ leader_stepdown ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *tablet-id*: The identifier (ID) of the tablet. - *dest-ts-uuid*: The destination identifier (UUID) for the new YB-TServer leader. To move leadership **from** the current leader, when you do not need to specify a new leader, use `""` for the value. If you want to transfer leadership intentionally **to** a specific new leader, then specify the new leader. Note If specified, *dest-ts-uuid* becomes the new leader. If the argument is empty (`""`), then a new leader will be elected automatically. In a future release, this argument will be optional. See GitHub issue [#4722](https://github.com/yugabyte/yugabyte-db/issues/4722 "#4722") * * * ### Cluster balancing commands YugabyteDB automatically balances the cluster via the [YB-Master](/stable/architecture/yb-master/ "YB-Master") service. The following manual commands are for advanced use cases. For detailed information on automatic cluster balancing scenarios, monitoring, and configuration, see [Cluster balancing](/stable/architecture/docdb-sharding/cluster-balancing/ "Cluster balancing"). For YB-Master cluster balancing flags, see [Cluster balancing flags](/stable/reference/configuration/yb-master/#cluster-balancing-flags "Cluster balancing flags"). #### set\_load\_balancer\_enabled Enables or disables the cluster balancer. **Syntax** ```sh yb-admin \ --master_addresses \ set_load_balancer_enabled [ 0 | 1 ] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - `0` | `1`: Enabled (`1`) is the default. To disable, set to `0`. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ set_load_balancer_enabled 0 ``` #### get\_load\_balancer\_state Returns the cluster load balancer state. **Syntax** ```sh yb-admin \ --master_addresses get_load_balancer_state ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. #### get\_load\_move\_completion Checks the percentage completion of the data move. You can rerun this command periodically until the value reaches `100.0`, indicating that the data move has completed. **Syntax** ```sh yb-admin \ --master_addresses \ get_load_move_completion ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. Note The time needed to complete a data move depends on the following: - number of tablets and tables - size of each of those tablets - SSD transfer speeds - network bandwidth between new nodes and existing ones For an example of performing a data move and the use of this command, refer to [Change cluster configuration](/stable/manage/change-cluster-config/ "Change cluster configuration"). **Example** In the following example, the data move is `66.6` percent done. ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ get_load_move_completion ``` Returns the following percentage: ```output 66.6 ``` #### get\_is\_load\_balancer\_idle Finds out if the cluster balancer is idle. **Syntax** ```sh yb-admin \ --master_addresses \ get_is_load_balancer_idle ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ get_is_load_balancer_idle ``` * * * ### Upgrade Refer to [Upgrade a deployment](/stable/manage/upgrade-deployment/ "Upgrade a deployment") to learn about how to upgrade a YugabyteDB cluster. For information on AutoFlags and how it secures upgrades with new data formats, refer to [AutoFlags](https://github.com/yugabyte/yugabyte-db/blob/master/architecture/design/auto_flags.md "AutoFlags"). #### get\_auto\_flags\_config Returns the current AutoFlags configuration of the universe. **Syntax** ```sh yb-admin \ --master_addresses \ get_auto_flags_config ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. **Example** ```sh ./bin/yb-admin --master_addresses ip1:7100,ip2:7100,ip3:7100 get_auto_flags_config ``` If the operation is successful you should see output similar to the following: ```output AutoFlags config: config_version: 1 promoted_flags { process_name: "yb-master" flags: "enable_automatic_tablet_splitting" flags: "master_enable_universe_uuid_heartbeat_check" flag_infos { promoted_version: 1 } flag_infos { promoted_version: 1 } } promoted_flags { process_name: "yb-tserver" flags: "regular_tablets_data_block_key_value_encoding" flags: "remote_bootstrap_from_leader_only" flags: "ysql_yb_enable_expression_pushdown" flag_infos { promoted_version: 1 } flag_infos { promoted_version: 1 } flag_infos { promoted_version: 1 } } ``` #### promote\_auto\_flags After all YugabyteDB processes have been upgraded to the new version, these features can be enabled by promoting their AutoFlags. Note that `promote_auto_flags` is a cluster-level operation; you don't need to run it on every node. **Syntax** ```sh yb-admin \ --master_addresses \ promote_auto_flags \ [ [ [force]]] ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. - *max-flags-class*: The maximum AutoFlag class to promote. Allowed values are `kLocalVolatile`, `kLocalPersisted` and `kExternal`. Default is `kExternal`. - *promote-non-runtime-flags*: Weather to promote non-runtime flags. Allowed values are `true` and `false`. Default is `true`. - `force`: Forces the generation of a new AutoFlag configuration and sends it to all YugabyteDB processes even if there are no new AutoFlags to promote. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ promote_auto_flags kLocalPersisted ``` If the operation is successful you should see output similar to the following: ```output PromoteAutoFlags status: New AutoFlags were promoted. Config version: 2 ``` OR ```output PromoteAutoFlags status: No new AutoFlags to promote ``` #### upgrade\_ysql Upgrades the YSQL system catalog after a successful [YugabyteDB cluster upgrade](/stable/manage/upgrade-deployment/ "YugabyteDB cluster upgrade"). YSQL upgrades are not required for clusters where [YSQL is not enabled](/stable/reference/configuration/yb-tserver/#ysql "YSQL is not enabled"). **Syntax** ```sh yb-admin \ --master_addresses \ upgrade_ysql ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. **Example** ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ upgrade_ysql ``` A successful upgrade returns the following message: ```output YSQL successfully upgraded to the latest version ``` In certain scenarios, a YSQL upgrade can take longer than 60 seconds, which is the default timeout value for yb-admin. To account for that, run the command with a higher timeout value: ```sh ./bin/yb-admin \ --master_addresses ip1:7100,ip2:7100,ip3:7100 \ --timeout_ms 180000 \ upgrade_ysql ``` Running `upgrade_ysql` is an online operation and doesn't require stopping a running cluster. `upgrade_ysql` is also a cluster-level operation; you don't need to run it on every node. Note Concurrent operations in a cluster can lead to various transactional conflicts, catalog version mismatches, and read restart errors. This is expected, and should be addressed by rerunning the upgrade command. #### finalize\_upgrade Finalizes an upgrade after a successful [YSQL major upgrade](/stable/manage/ysql-major-upgrade-local/ "YSQL major upgrade"). You can run this command from any node in the cluster. Note that `finalize_upgrade` is a cluster-level operation; you don't need to run it on every node. **Syntax** ```sh yb-admin \ --master_addresses \ finalize_upgrade ``` - *master-addresses*: Comma-separated list of YB-Master hosts and ports. Default is `localhost:7100`. **Example** ```sh ./bin/yb-admin --master_addresses 127.0.0.1:7100,127.0.0.2:7100,127.0.0.3:7100 finalize_upgrade ``` ```output Finalizing YSQL major catalog upgrade Finalize successful Promoting auto flags PromoteAutoFlags completed successfully New AutoFlags were promoted New config version: 2 Upgrading YSQL YSQL successfully upgraded to the latest version Upgrade successfully finalized ```