Project: YugabyteDB (App Definition and Development / Database)
File: yb-admin.md

title: yb-admin - command line tool for advanced YugabyteDB administration headerTitle: yb-admin linkTitle: yb-admin description: Use the yb-admin command line tool for advanced administration of YugabyteDB clusters. menu: v2.18: identifier: yb-admin parent: admin weight: 30 type: docs The `yb-admin` utility, located in the `bin` directory of YugabyteDB home, provides a command line interface for administering clusters. It invokes the and servers to perform the necessary administration. To use the `yb-admin` utility from the YugabyteDB home directory, run `./bin/yb-admin` using the following syntax. ```sh yb-admin \ [ -master_addresses <master-addresses> ] \ [ -initmasteraddrs <master-address> ] \ [ -timeout_ms <millisec> ] \ [ -certsdirname <dir_name> ] \ <command> [ command_flags ] ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. initmasteraddrs*: 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 value is `60000`. A value of `0` means don't wait; `-1` means wait indefinitely. certsdirname*: The directory with certificates to use for secure server connections. Default value is `""`. To connect to a cluster with TLS enabled, you must include the `-certsdirname` flag with the directory location where the root certificate is located. command*: The operation to be performed. See command for syntax details and examples. command_flags*: Configuration flags that can be applied to the command. To display the online help, run `yb-admin --help` from the YugabyteDB home directory. ```sh ./bin/yb-admin --help ``` * * Gets the configuration for the universe. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ getuniverseconfig ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. Changes the configuration of a tablet. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ changeconfig <tabletid> \ [ ADDSERVER | REMOVESERVER ] \ <peer_uuid> \ [ PREVOTER | PREOBSERVER ] ``` master_addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. tablet_id*: The identifier (ID) of the tablet. ADDSERVER | REMOVESERVER: Subcommand to add or remove the server. peer_uuid*: The UUID of the tablet server hosting the peer tablet. PREVOTER | PREOBSERVER*: 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 `REMOVESERVER` subcommand) and then add in a new node (using the `ADDSERVER` subcommand). Changes the master configuration. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ changemasterconfig \ [ ADDSERVER|REMOVESERVER ] \ <ip_addr> <port> \ [<uuid>] ``` master_addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. ADDSERVER | REMOVESERVER: 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>) or run the . 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

Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ listtabletservers <tablet_id> ``` master_addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. tablet_id*: The identifier (ID) of the tablet. 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 <master-addresses> \ listtablets <keyspacetype>.<keyspacename> <table> [maxtablets] ``` master_addresses*: Comma-separated list of YB-Master hosts and ports. Default value 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 \ listtablets ysql.dbname table_name 0 ``` ```output Tablet UUID Range Leader cea3aaac2f10460a880b0b4a2a4b652a partitionkeystart: "" partitionkeyend: "\177\377" 127.0.0.1:9100 e509cf8eedba410ba3b60c7e9138d479 partitionkeystart: "\177\377" partitionkeyend: "" ``` Lists all tablet servers. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ listalltablet_servers ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. 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 <master-addresses> \ listallmasters ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. Example ```sh ./bin/yb-admin \ -master_addresses node7:7100,node8:7100,node9:7100 \ listallmasters ``` ```output Master UUID RPC Host/Port State Role ... node8:7100 ALIVE FOLLOWER ... node9:7100 ALIVE FOLLOWER ... node7:7100 ALIVE LEADER ``` Prints a list of replica types and counts for the specified table. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ listreplicatypecounts <keyspace> <tablename> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. keyspace*: The name of the database or keyspace. table_name*: The name of the table. Prints the status of the YB-Master servers. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ dumpmastersstate ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. List the locations of the tablet server logs. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ listtabletserverloglocations ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. Lists all tablets for the specified tablet server (YB-TServer). Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ listtabletsfortabletserver <ts_uuid> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. ts_uuid*: The UUID of the tablet server (YB-TServer). Splits the specified hash-sharded tablet and computes the split point as the middle of tablet's sharding range. ```sh splittablet -masteraddresses <master-addresses> <tabletidto_split> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. tabletidto_split*: The identifier of the tablet to split. For more information on tablet splitting, see: Architecture overview Architecture design document in the GitHub repository. Forces the master leader to step down. The specified YB-Master node will take its place as leader. {{< note title="Note" >}} Use this command only if recommended by Yugabyte support. There is a possibility of downtime. {{< /note >}} Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ masterleaderstepdown [ <newleaderid> ] ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. newleaderid*: (Optional) The identifier (ID) of the new YB-Master leader. If not specified, the new leader is automatically elected. Prints the current YSQL schema catalog version. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ ysqlcatalogversion ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. Example ```sh

\ -master_addresses ip1:7100,ip2:7100,ip3:7100 \ ysqlcatalogversion ``` The version output displays: ```output Version:1 ``` Prints a list of all tables. Optionally, include the database type, table ID, and the table type. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ list_tables \ [ includedbtype ] [ includetableid ] [ includetabletype ] ``` ```sh yb-admin \ -masteraddresses <master-addresses> listtables ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. `includedbtype`: (Optional) Add this flag to include the database type for each table. `includetableid`: (Optional) Add this flag to include the unique UUID associated with the table. `includetabletype`: (Optional) Add this flag to include the table type for each table. Returns tables in the following format, depending on the flags used: ```output <dbtype>.<namespace>.<tablename> tableid tabletype ``` db_type*: The type of database. Valid values include `ysql`, `ycql`, `yedis`, and `unknown`. namespace*: The name of the database (for YSQL) or keyspace (for YCQL). table_name*: The name of the table. table_type*: The type of table. Valid values include `catalog`, `table`, `index`, and `other`. {{< note title="Tip" >}} To display a list of tables and their UUID (`tableid`) values, open the **YB-Master UI** (`<masterhost>:7000/`) and click Tables in the navigation bar. {{< /note >}} Example ```sh ./bin/yb-admin \ -master_addresses ip1:7100,ip2:7100,ip3:7100 \ list_tables ``` ```output ... yugabyte.pg_range template1.pg_attrdef template0.pgattrdefadrelidadnumindex template1.pg_conversion systemplatform.pgopfamily postgres.pgopfamilyamnamensp_index system_schema.functions template0.pg_statistic system.local template1.pginheritsparent_index template1.pg_amproc systemplatform.pgrewrite yugabyte.pgtsconfigcfgnameindex template1.pgtriggertgconstraint_index template1.pg_class template1.pg_largeobject systemplatform.sqlparts template1.pg_inherits ... ``` Triggers manual compaction on a table. Syntax 1: Using table name ```sh yb-admin \ -masteraddresses <masteraddresses> \ compacttable <dbtype>.<namespace> <table> [timeoutinseconds] [ADD_INDEXES] ``` master_addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. db_type*: The type of database. Valid values include ysql and ycql. namespace*: The name of the database (for YSQL) or keyspace (for YCQL). table*: The name of the table to compact. timeoutinseconds*: Specifies duration (in seconds) yb-admin waits for compaction to end. Default value is `20`. ADD_INDEXES*: Whether to compact the secondary indexes associated with the table. Default is `false`. Example ```sh ./bin/yb-admin \ -masteraddresses $MASTERRPC_ADDRS \ compacttable ysql.yugabyte tablename ``` ```output Compacted [yugabyte.table_name] tables. ``` Syntax 2: Using table ID ```sh yb-admin \ -masteraddresses <masteraddresses> \ compacttable tableid.<tableid> [timeoutinseconds] [ADD_INDEXES] ``` master_addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. table_id*: The unique UUID associated with the table. timeoutinseconds*: Specifies duration (in seconds) yb-admin waits for compaction to end. Default value is `20`. ADD_INDEXES*: Whether to compact the secondary indexes associated with the table. Default is `false`. Example ```sh ./bin/yb-admin \ -masteraddresses $MASTERRPC_ADDRS \ compact_table tableid.000033eb000030008000000000004002 ``` ```output Compacted [000033eb000030008000000000004002] tables. ``` Modifies the placement information (cloud, region, and zone) for a table. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ modifytableplacementinfo <keyspace> <tablename> <placementinfo> <replicationfactor> \ [ <placement_id> ] ``` or alternatively: ```sh yb-admin \ -master_addresses <master-addresses> \ modifytableplacementinfo tableid.<tableid> <placementinfo> <replicationfactor> \ [ <placement_id> ] ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value 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 value is `cloud1.datacenter1.rack1`. replication_factor*: The number of replicas for each tablet. placementid*: Identifier of the primary cluster. Optional. If set, it has to match the `placementid` specified for the primary cluster in the cluster configuration. Example ```sh ./bin/yb-admin \ -masteraddresses $MASTERRPC_ADDRS \ modifytableplacement_info testdatabase testtable \

3 ``` Verify this in the Master UI by opening the YB-Master UI (`<master_host>: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. {{< note title="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 instead. {{< /note >}} Creates a transaction status table to be used in a region. This command should always be followed by to set the placement information for the newly-created transaction status table. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ createtransactiontable \ <table_name> ``` master_addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. tablename*: The name of the transaction status table to be created; this must start with `transactions`. The transaction status table will be created as `system.<table_name>`. Example ```sh ./bin/yb-admin \ -masteraddresses $MASTERRPC_ADDRS \ createtransactiontable \ transactionsuseast ``` Verify this in the Master UI by opening the YB-Master UI (`<masterhost>:7000/`) and clicking **Tables** in the navigation bar. You should see a new system table with keyspace `system` and table name `transactionsus_east`. Next, set the placement on the newly created transactions table: ```sh ./bin/yb-admin \ -masteraddresses $MASTERRPC_ADDRS \ modifytableplacementinfo system transactionsus_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.transactionsuseast` should now be solely located in the AWS us-east region. {{< note title="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. {{< /note >}} Add a tablet to a transaction status table. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ addtransactiontablet \ <table_id> ``` master_addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. table_id*: The unique UUID associated with the table. Example ```sh ./bin/yb-admin \ -master_addresses ip1:7100,ip2:7100,ip3:7100 \ addtransactiontablet 000033eb000030008000000000004002 ``` To verify that the new status tablet has been created, run the command. Flush the memstores of the specified table on all tablet servers to disk. Syntax 1: Using table name ```sh yb-admin \ -masteraddresses <masteraddresses> \ flushtable <dbtype>.<namespace> <table> [timeoutinseconds] [ADD_INDEXES] ``` master_addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. db_type*: The type of database. Valid values include ysql and ycql. namespace*: The name of the database (for YSQL) or keyspace (for YCQL). table*: The name of the table to flush. timeoutinseconds*: Specifies duration (in seconds) yb-admin waits for flushing to end. Default value is `20`. ADD_INDEXES*: Whether to flush the secondary indexes associated with the table. Default is `false`. Example ```sh ./bin/yb-admin \ -masteraddresses $MASTERRPC_ADDRS \ flushtable ysql.yugabyte tablename ``` ```output Flushed [yugabyte.table_name] tables. ``` Syntax 2: Using table ID ```sh yb-admin \ -masteraddresses <masteraddresses> \ flushtable tableid.<tableid> [timeoutinseconds] [ADD_INDEXES] ``` master_addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. table_id*: The unique UUID associated with the table. timeoutinseconds*: Specifies duration (in seconds) yb-admin waits for flushing to end. Default value is `20`. ADD_INDEXES*: Whether to flush the secondary indexes associated with the table. Default is `false`. Example ```sh ./bin/yb-admin \ -masteraddresses $MASTERRPC_ADDRS \ flush_table tableid.000033eb000030008000000000004002 ``` ```output Flushed [000033eb000030008000000000004002]

``` The following backup and snapshot commands are available: creates a snapshot of the specified YSQL database creates a snapshot of the specified YCQL keyspace returns a list of all snapshots, restores, and their states creates a snapshot of one or more YCQL tables and indexes restores a snapshot returns a list of all snapshot restorations creates a snapshot metadata file imports a snapshot metadata file imports a specified snapshot metadata file deletes a snapshot's information sets the schedule for snapshot creation returns a list of all snapshot schedules restores all objects in a scheduled snapshot deletes the specified snapshot schedule Creates a snapshot of the specified YSQL database. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ createdatabasesnapshot <database_name> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value 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 \ createdatabasesnapshot ``` To see if the database snapshot creation has completed, run the command. Creates a snapshot of the specified YCQL keyspace. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ createkeyspacesnapshot <keyspace_name> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value 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 \ createkeyspacesnapshot ``` To see if the database snapshot creation has completed, run the command. 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 <master-addresses> \ list_snapshots \ [ showdetails ] [ notshow_restored ] ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. `show_details`: (Optional) Print snapshot details, including the keyspaces, tables, and indexes. `notshowrestored`: (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_snapshot` command prints the current state of the following operations: `createsnapshot`: `snapshotid`, `keyspace`, `table`, `state` `restoresnapshot`: `snapshotid`, `restoration_id`, `state`. `deletesnapshot`: `snapshotid`, `state`. When `showdetails` is included, the `listsnapshot` command prints the following details in JSON format: `type`: `NAMESPACE` `id`: `<snapshotid>` or `<restorationid>` `data`: `name`: `"<namespace_name>"` `databasetype`: `"YQLDATABASE_CQL"` `colocated`: `true` or `false` `state`: `"<state>"` `type`: `TABLE` <== Use for table or index `id`: `"<tableid>"` or `"<indexid>"` `data`: `name`: `"<tablename>"` or `"<indexid>"` `version`: `"<table_version>"` `state`: `"<state>"` `statemsg`: `"<statemsg>"` `nextcolumnid`: `"<column_id>"` `tabletype`: `"YQLTABLE_TYPE"` `namespaceid`: `"<namespaceid>"` `indexedtableid` (index only): `<table_id>` `islocalindex` (index only): `true` or `false` `isuniqueindex` (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 \ listsnapshots showdetails ``` Because `showdetails` was included, `listsnapshots` prints the details in JSON format, like this: ```output f566b03b-b85e-41a0-b903-875cd305c1c5 COMPLETE {"type":"NAMESPACE","id":"8053dd55d478437cba57d9f67caac154","data":{"name":"yugabyte","databasetype":"YQLDATABASE_CQL","colocated":false,"state":"RUNNING"}} {"type":"TABLE","id":"a7e940e724ef497ebe94bf69bfe507d9","data":{"name":"tracking1","version":1,"state":"RUNNING","statemsg":"Current schema version=1","nextcolumnid":13,"tabletype":"YQLTABLETYPE","namespace_id":"8053dd55d478437cba57d9f67caac154"}} {"type":"NAMESPACE","id":"8053dd55d478437cba57d9f67caac154","data":{"name":"yugabyte","databasetype":"YQLDATABASE_CQL","colocated":false,"state":"RUNNING"}} {"type":"TABLE","id":"b48f4d7695f0421e93386f7a97da4bac","data":{"name":"tracking1vidx","version":0,"state":"RUNNING","nextcolumnid":12,"tabletype":"YQLTABLETYPE","namespaceid":"8053dd55d478437cba57d9f67caac154","indexedtableid":"a7e940e724ef497ebe94bf69bfe507d9","islocalindex":false,"isuniqueindex":false}} ``` If `showdetails` is not included, `listsnapshots` prints the `snapshot_id` and `state`: ```output f566b03b-b85e-41a0-b903-875cd305c1c5 COMPLETE ``` 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. {{< note title="Snapshots don't auto-expire" >}} Snapshots you create via `create_snapshot` persist on disk until you remove them using the command. Use the command to create snapshots that expire after a specified time interval. {{</ note >}} Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ createsnapshot <keyspace> <tablename> | <table_id> \ [<keyspace> <tablename> | <tableid> ]... \ [flushtimeoutin_seconds] ``` master-addresses*: Comma-separated list of YB-Master hosts and

Default value is `localhost:7100`. keyspace*: The name of the database or keyspace formatted as <ycql|ysql|yedis>.<keyspace>. table_name*: The name of the table name. table_id*: The unique UUID associated with the table. flushtimeoutin_seconds*: Specifies duration (in seconds) before flushing snapshot. Default value 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 \ createsnapshot ydb testtb ``` ```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 command. Restores the specified snapshot, including the tables and indexes. When the operation starts, a `restoration_id` is generated. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ restoresnapshot <snapshotid> <restore-target> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. snapshot_id*: The identifier (ID) for the snapshot. restore-target*: The time to which to restore the snapshot. This can be either an absolute Unix time, or a relative time such as `minus 5m` (to restore to 5 minutes ago). Optional; omit to restore to the given snapshot's creation time. Example ```sh ./bin/yb-admin restore_snapshot 72ad2eb1-65a2-4e88-a448-7ef4418bc469 ``` When the restore starts, the `snapshotid` and the generated `restorationid` 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 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 ``` 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 <master-addresses> \ listsnapshotrestorations <restoration_id> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. restoration_id*: the snapshot restoration's unique identifier. The ID is optional; omit the ID to return all restorations in the system. Example ```sh ./bin/yb-admin \ -master_addresses ip1:7100,ip2:7100,ip3:7100 \ listsnapshotrestorations 26ed9053-0c26-4277-a2b8-c12d0fa4c8cf ``` ```output.json { "restorations": [ { "id": "26ed9053-0c26-4277-a2b8-c12d0fa4c8cf", "snapshot_id": "ca8f3763-5437-4594-818d-713fb0cddb96", "state": "RESTORED" } ] } ``` 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 <master-addresses> \ exportsnapshot <snapshotid> <file_name> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value 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 ``` Imports the specified snapshot metadata file. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ importsnapshot <filename> \ [<keyspace> <tablename> [<keyspace> <tablename>]...] ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value 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 title="Note" >}} The keyspace and the table can be different from the exported one. {{< /note >}} Example ```sh ./bin/yb-admin \ -master_addresses ip1:7100,ip2:7100,ip3:7100 \ importsnapshot testtb.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

Object Old ID New ID Keyspace c478ed4f570841489dd973aacf0b3799 c478ed4f570841489dd973aacf0b3799 Table ff4389ee7a9d47ff897d3cec2f18f720 ff4389ee7a9d47ff897d3cec2f18f720 Tablet 0 cea3aaac2f10460a880b0b4a2a4b652a cea3aaac2f10460a880b0b4a2a4b652a Tablet 1 e509cf8eedba410ba3b60c7e9138d479 e509cf8eedba410ba3b60c7e9138d479 Snapshot 4963ed18fc1e4f1ba38c8fcf4058b295 4963ed18fc1e4f1ba38c8fcf4058b295 ``` Imports only the specified tables from the specified snapshot metadata file. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ importsnapshotselective <file_name> \ [<keyspace> <tablename> [<keyspace> <tablename>]...] ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value 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 title="Note" >}} The keyspace can be different from the exported one. The name of the table needs to be the same. {{< /note >}} Example ```sh ./bin/yb-admin \ -master_addresses ip1:7100,ip2:7100,ip3:7100 \ importsnapshotselective testtb.snapshot ydb testtb ``` ```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 ``` Deletes the specified snapshot. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ deletesnapshot <snapshotid> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. snapshot_id*: The identifier (ID) of the snapshot. Creates 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. Returns a schedule ID in JSON format. Syntax ```sh yb-admin createsnapshotschedule \ -master_addresses <master-addresses> \ <snapshot-interval>\ <retention-time>\ <filter-expression> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value 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, or keyspaces (YCQL) or databases (YSQL). For proper consistency guarantees, it is recommended to set this up on a per-keyspace (YCQL) or per-database (YSQL) level. Example Take a snapshot of the `ysql.yugabyte` database once per minute, and retain each snapshot for 10 minutes: ```sh ./bin/yb-admin \ -master_addresses ip1:7100,ip2:7100,ip3:7100 \ createsnapshotschedule 1 10 ysql.yugabyte ``` ```output.json { "schedule_id": "6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256" } ``` 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 <master-addresses> \ listsnapshotschedules <schedule-id> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. schedule-id*: the snapshot schedule's unique identifier. The ID is optional; omit the ID to return all schedules in the system. Example ```sh ./bin/yb-admin \ -master_addresses ip1:7100,ip2:7100,ip3:7100 \ listsnapshotschedules 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", "snapshottimeutc": "2021-04-28T13:35:32.499002+0000" }, { "id": "aaf562ca-036f-4f96-b193-f0baead372e5", "snapshottimeutc": "2021-04-28T13:36:37.501633+0000", "previoussnapshottime_utc": "2021-04-28T13:35:32.499002+0000" } ] } ] } ``` Schedules group a set of items into a single tracking object (the schedule). When you restore, you can choose a particular schedule and a point in time, and revert the state of all affected objects back to the chosen

Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ restoresnapshotschedule <schedule-id> <restore-target> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. schedule-id*: The identifier (ID) of the schedule to be restored. restore-target*: The time to which to restore the snapshots in the schedule. This can be either an absolute Unix timestamp, or a relative time such as `minus 5m` (to restore to 5 minutes ago). You can also use a or with the restore command, if you like. In addition to restoring to a particular timestamp, you can also restore 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 restore from five minutes ago `minus 1h` to restore from one hour ago `minus 3d` to restore from three days ago `minus 1h 5m` to restore 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 \ restoresnapshotschedule 6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256 1617670679185100 ``` Restore from a relative time: ```sh ./bin/yb-admin \ -master_addresses ip1:7100,ip2:7100,ip3:7100 \ restoresnapshotschedule 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" } ``` 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 <master-addresses> \ deletesnapshotschedule <schedule-id> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. schedule-id*: the snapshot schedule's unique identifier. Example ```sh ./bin/yb-admin \ -master_addresses ip1:7100,ip2:7100,ip3:7100 \ deletesnapshotschedule 6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256 ``` The output should show the schedule ID we just deleted. ```output.json { "schedule_id": "6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256" } ``` <a name="deployment-topology-commands"></a> Modifies the placement information (cloud, region, and zone) for a deployment. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ modifyplacementinfo <placementinfo> <replicationfactor> \ [ <placement_id> ] ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. placement_info: Comma-delimited list of placements for cloud.region.zone*. Optionally, after each placement block, we can also specify a minimum replica count separated by a colon. This count indicates how many minimum replicas of each tablet we want in that placement block. Its default value is 1. It is not recommended to repeat the same placement multiple times but instead specify the total count after the colon. However, in the event that the user specifies a placement multiple times, the total count from all mentions is taken. replicationfactor*: The number of replicas for each tablet. This value should be greater than or equal to the total of replica counts specified in *placementinfo*. placement_id*: The identifier of the primary cluster, which can be any unique string. Optional. If not set, a randomly-generated ID will be used. Example ```sh ./bin/yb-admin \ -masteraddresses $MASTERRPC_ADDRS \ modifyplacementinfo \ 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: 2 replicas in aws.us-west.us-west-2a 2 replicas in aws.us-west.us-west-2b 1 replica in aws.us-west.us-west-2c You can verify the new placement information by running the following `curl` command: ```sh curl -s http://<any-master-ip>:7000/cluster-config ``` Sets the preferred availability zones (AZs) and

Tablet leaders are placed in alive and healthy nodes of AZs in order of preference. When no healthy node is available in the most preferred AZs (preference value 1), then alive and healthy nodes from the next preferred AZs are picked. AZs with no preference are equally eligible to host tablet leaders. Having all tablet leaders reside in a single region reduces the number of network hops for the database to write transactions, which increases performance and reduces latency. {{< note title="Note" >}} Make sure you've already run command beforehand. By default, the 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 irrespective of their preference. Cluster configuration stores preferred zones in either affinitizedleaders or multiaffinitized_leaders object. Tablespaces don't inherit cluster-level placement information, leader preference, or read replica configurations. If the client application uses a smart driver, set the to target the preferred zones. {{< /note >}} Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ setpreferredzones <cloud.region.zone>[:preference] \ [<cloud.region.zone>[:preference]]... ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. cloud.region.zone*: Specifies the cloud, region, and zone. Default value is `cloud1.datacenter1.rack1`. preference*: Specifies the leader preference for a zone. Values have to be contiguous non-zero integers. Multiple zones can have the same value. Default value 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://<any-master-ip>: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" } minnumreplicas: 1 } placement_blocks { cloud_info { placement_cloud: "gcp" placement_region: "us-west1" placement_zone: "us-west1-b" } minnumreplicas: 1 } placement_blocks { cloud_info { placement_cloud: "gcp" placement_region: "us-east4" placement_zone: "us-east4-a" } minnumreplicas: 2 } placement_blocks { cloud_info { placement_cloud: "gcp" placement_region: "us-asia-northeast1" placement_zone: "us-asia-northeast1-a" } minnumreplicas: 1 } } } ``` The following command sets the preferred region to `gcp.us-west1` and the fallback to zone `gcp.us-east4.us-east4-a`: ```sh ssh -i $PEM $ADMIN_USER@$MASTER1 \ ~/master/bin/yb-admin --masteraddresses $MASTERRPC_ADDRS \ setpreferredzones \ gcp.us-west1.us-west1-a:1 \ gcp.us-west1.us-west1-b:1 \ gcp.us-east4.us-east4-a:2 ``` Verify by running the following. ```sh curl -s http://<any-master-ip>:7000/cluster-config ``` Looking again at the cluster configuration you should see `multiaffinitizedleaders` 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" } minnumreplicas: 1 } placement_blocks { cloud_info { placement_cloud: "gcp" placement_region: "us-west1" placement_zone: "us-west1-b" } minnumreplicas: 1 } placement_blocks { cloud_info { placement_cloud: "gcp" placement_region: "us-east4" placement_zone: "us-east4-a" } minnumreplicas: 2 } placement_blocks { cloud_info { placement_cloud: "gcp" placement_region: "us-asia-northeast1" placement_zone: "us-asia-northeast1-a" } minnumreplicas: 1 } } multiaffinitizedleaders { 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" } } multiaffinitizedleaders { zones { placement_cloud: "gcp" placement_region: "us-east4" placement_zone: "us-east4-a" } } } ``` Add a read replica cluster to the master configuration. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ addreadreplicaplacementinfo <placement_info> \ <replication_factor> \ [ <placement_id> ] ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. placementinfo*: A comma-delimited list of read replica placements for *cloud*.*region*.*zone*, using the format `<cloud1.region1.zone1>:<numreplicasinzone1>,<cloud2.region2.zone2>:<numreplicasin_zone2>,...`. Default value is `cloud1.datacenter1.rack1`. Read replica availability zones must be uniquely different from the primary availability

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.z1rr:1`. replication_factor*: The number of 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. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ modifyreadreplicaplacementinfo <placement_info> \ <replication_factor> \ [ <placement_id> ] ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. placement_info: A comma-delimited list of placements for cloud.region.zone*. Default value is `cloud1.datacenter1.rack1`. replication_factor*: The number of 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. Delete the read replica. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ deletereadreplicaplacementinfo [ <placement_id> ] ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. 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. For details on using encryption at rest, see . Sets the contents of `key_path` in-memory on each YB-Master node. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ adduniversekeytoallmasters <keyid> <key_path> ``` keyid*: 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 `keypath` as a byte[]. key_path*: The path to the file containing the universe key. {{< note title="Note" >}} After adding the universe keys to all YB-Master nodes, you can verify the keys exist using the `yb-admin` command and enable encryption using the command. {{< /note >}} Checks whether the universe key associated with the provided key_id exists in-memory on each YB-Master node. ```sh yb-admin \ -masteraddresses <master-addresses> allmastershaveuniversekeyinmemory <keyid> ``` keyid*: 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 `keypath` as a byte[]. Rotates the in-memory universe key to start encrypting newly-written data files with the universe key associated with the provided `key_id`. {{< note title="Note" >}} The value must be true for the universe key to be successfully rotated and enabled). {{< /note >}} Syntax ```sh yb-admin \ -masteraddresses <master-addresses> rotateuniversekeyinmemory <keyid> ``` keyid*: 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 `keypath` as a byte[]. Disables the in-memory encryption at rest for newly-written data files. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ disableencryptionin_memory ``` Checks if cluster-wide encryption is enabled. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ isencryptionenabled ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. Returns message: ```output Encryption status: ENABLED with key id <keyid2> ``` The new key ID (`<keyid2>`) should be different from the previous one (`<key_id>`). Example ```sh ./bin/yb-admin \ -master_addresses ip1:7100,ip2:7100,ip3:7100 \ isencryptionenabled ``` ```output Encryption status: ENABLED with key id <keyid2> ``` Creates a change data capture (CDC) DB stream for the specified table. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ createchangedatastream ysql.<namespacename> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is

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 \ createchangedata_stream ysql.yugabyte ``` 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 <master-addresses> \ createchangedatastream ysql.<namespacename> IMPLICIT ALL ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. namespace_name*: The namespace on which the DB stream ID is to be created. `IMPLICIT`: Checkpointing type on the server. `ALL`: Record type indicating the server that the stream should send the before image too. A successful operation of the above command returns a message with a DB stream ID: ```output CDC Stream ID: d540f5e4890c4d3b812933cbfd703ed3 ``` 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 <master-addresses> \ createchangedatastream ysql.<namespacename> EXPLICIT ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value 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 ``` Lists all the created CDC DB streams. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ listchangedatastreams [namespacename] ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. namespace_name*: Optional - The namespace name for which the streams are to be listed, if not provided it would list all the streams without filtering. Example: ```sh ./bin/yb-admin \ -master_addresses 127.0.0.1:7100 \ listchangedata_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 the information associated with a particular CDC DB stream. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ getchangedatastreaminfo <dbstreamid> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. dbstreamid*: The CDC DB stream ID to get the info of. Example: ```sh ./bin/yb-admin \ -master_addresses 127.0.0.1:7100 \ getchangedatastreaminfo d540f5e4890c4d3b812933cbfd703ed3 ``` The previous command results in the following response. It will have the tableid(s) associated with the stream and the namespaceid on which the stream is created: ```output CDC DB Stream Info: table_info { stream_id: "d540f5e4890c4d3b812933cbfd703ed3" table_id: "000033e1000030008000000000004000" } namespace_id: "000033e1000030008000000000000000" ``` Delete the specified CDC DB stream. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ deletechangedatastream <dbstream_id> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. dbstreamid*: The CDC DB stream ID to be deleted. Example: ```sh ./bin/yb-admin \ -master_addresses 127.0.0.1:7100 \ deletechangedata_stream d540f5e4890c4d3b812933cbfd703ed3 ``` The above command results in the following response: ```output Successfully deleted CDC DB Stream ID: d540f5e4890c4d3b812933cbfd703ed3 ``` 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 to add more tables. To verify if any tables are already configured for replication, use

Syntax ```sh yb-admin \ -masteraddresses <targetmaster_addresses> \ setupuniversereplication \ <sourceuniverseuuid><replicationname> \ <sourcemasteraddresses> \ <commaseparatedlistoftable_ids> \ [ <commaseparatedlistofproducerbootstrapids> ] \ [ transactional ] ``` targetmasteraddresses*: Comma-separated list of target YB-Master hosts and ports. Default value is `localhost:7100`. sourceuniverseuuid*: The UUID of the source universe. replication_name*: The name for the replication. sourcemasteraddresses*: Comma-separated list of the source master addresses. commaseparatedlistoftableids*: Comma-separated list of source universe table identifiers (`tableid`). commaseparatedlistofproducerbootstrapids*: Comma-separated list of source universe bootstrap identifiers (`bootstrap_id`). Obtain these with , using a comma-separated list of source universe table IDs. transactional*: identifies the universe as Active in a transactional xCluster deployment. {{< warning title="Important" >}} Enter the source universe bootstrap IDs in the same order as their corresponding table IDs. {{< /warning >}} {{< note title="Tip" >}} To display a list of tables and their UUID (`tableid`) values, open the **YB-Master UI** (`<masterhost>:7000/`) and click Tables in the navigation bar. {{< /note >}} Example ```sh ./bin/yb-admin \ -master_addresses 127.0.0.11:7100,127.0.0.12:7100,127.0.0.13:7100 \ setupuniversereplication e260b8b6-e89f-4505-bb8e-b31f74aa29f3_xClusterSetup1 \ 127.0.0.1:7100,127.0.0.2:7100,127.0.0.3:7100 \ 000030a5000030008000000000004000,000030a5000030008000000000004005,dfef757c415c4b2cacc9315b8acb539a ``` 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 . To check if any tables are configured for replication, use . Syntax Use the `setmasteraddresses` subcommand to replace the source master address list. Use this if the set of masters on the source changes: ```sh yb-admin -masteraddresses <targetmaster_addresses> \ alteruniversereplication <sourceuniverseuuid><replicationname> \ setmasteraddresses <sourcemasteraddresses> ``` targetmasteraddresses*: Comma-separated list of target YB-Master hosts and ports. Default value is `localhost:7100`. sourceuniverseuuid*: The UUID of the source universe. replication_name*: The name of the replication to be altered. sourcemasteraddresses*: 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 -masteraddresses <targetmaster_addresses> \ alteruniversereplication <sourceuniverseuuid><replicationname> \ addtable [ <commaseparatedlistoftableids> ] \ [ <commaseparatedlistofproducerbootstrapids> ] ``` targetmasteraddresses*: Comma-separated list of target YB-Master hosts and ports. Default value is `localhost:7100`. sourceuniverseuuid*: The UUID of the source universe. replication_name*: The name of the replication to be altered. commaseparatedlistoftableids*: Comma-separated list of source universe table identifiers (`tableid`). commaseparatedlistofproducerbootstrapids*: Comma-separated list of source universe bootstrap identifiers (`bootstrap_id`). Obtain these with , using a comma-separated list of source universe table IDs. {{< warning title="Important" >}} Enter the source universe bootstrap IDs in the same order as their corresponding table IDs. {{< /warning >}} Use the `remove_table` subcommand to remove one or more tables from the existing list: ```sh yb-admin -masteraddresses <targetmaster_addresses> \ alteruniversereplication <sourceuniverseuuid><replicationname> \ removetable [ <commaseparatedlistoftableids> ] ``` targetmasteraddresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. sourceuniverseuuid*: The UUID of the source universe. replication_name*: The name of the replication to be altered. commaseparatedlistoftableids*: Comma-separated list of source universe table identifiers (`tableid`). Use the `rename_id` subcommand to rename xCluster replication streams. ```sh yb-admin -masteraddresses <targetmaster_addresses> \ alteruniversereplication <sourceuniverseuuid><replicationname> \ renameid <sourceuniverseuuid><newreplicationname> ``` targetmasteraddresses*: Comma-separated list of target YB-Master hosts and ports. Default value is `localhost:7100`. sourceuniverseuuid*: The UUID of the source universe. replication_name*: The name of the replication to be altered. newreplicationname*: The new name of the replication stream. Deletes universe replication for the specified source universe. Syntax ```sh yb-admin \ -masteraddresses <targetmaster_addresses> \ deleteuniversereplication <sourceuniverseuuid><replicationname> ``` targetmasteraddresses*: Comma-separated list of target YB-Master hosts and ports. Default value is `localhost:7100`. sourceuniverseuuid*: The UUID of the source universe. replication_name*: The name of the replication to be deleted. Sets the universe replication to be enabled or

Syntax ```sh yb-admin \ -masteraddresses <targetmaster_addresses> \ setuniversereplicationenabled <sourceuniverseuuid><replication_name> ``` targetmasteraddresses*: Comma-separated list of target YB-Master hosts and ports. Default value is `localhost:7100`. sourceuniverseuuid*: The UUID of the source universe. replication_name*: The name of the replication to be enabled or disabled. `0` | `1`: Disabled (`0`) or enabled (`1`). Default is `1`. Sets the xCluster role to `STANDBY` or `ACTIVE`. Syntax ```sh yb-admin \ -masteraddresses <masteraddresses> \ changexclusterrole \ <role> ``` master_addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. These are the addresses of the master nodes where the role is to be applied. For example, to change the target to `STANDBY`, use target universe master addresses, and to change the source universe role, use source universe master addresses. role*: Can be `STANDBY` or `ACTIVE`. Example ```sh ./bin/yb-admin \ -master_addresses 127.0.0.11:7100,127.0.0.12:7100,127.0.0.13:7100 \ changexclusterrole STANDBY ``` Reports the current xCluster safe time for each namespace, which is the time at which reads will be performed. Syntax ```sh yb-admin \ -masteraddresses <targetmaster_addresses> \ getxclustersafe_time \ [includelagand_skew] ``` targetmasteraddresses*: Comma-separated list of target YB-Master hosts and ports. Default value is `localhost:7100`. includelagandskew*: Set `includelagandskew` option to show `safetimelagsec` and `safetimeskewsec`, otherwise these are hidden by default. Example ```sh ./bin/yb-admin \ -master_addresses 127.0.0.11:7100,127.0.0.12:7100,127.0.0.13:7100 \ getxclustersafe_time ``` ```output { "namespace_id": "000033f1000030008000000000000000", "namespace_name": "yugabyte", "safe_time": "2023-04-14 18:34:18.429430", "safetimeepoch": "1681522458429430", "safetimelag_sec": "15.66", "safetimeskew_sec": "14.95" } ``` namespace_id*: ID of the stream. namespace_name*: Name of the stream. safe_time*: Safe time in timestamp format. safetimeepoch*: The `epoch` of the safe time. safetimelag_sec*: Safe time lag is computed as `(current time - current safe time)`. safetimeskew_sec*: Safe time skew is computed as `(safe time of most caught up tablet - safe time of laggiest tablet)`. Verify when the producer and consumer are in sync for a given list of `stream_ids` at a given timestamp. Syntax ```sh yb-admin \ -masteraddresses <sourcemaster_addresses> \ waitforreplication_drain \ <commaseparatedlistofstream_ids> [<timestamp> | minus <interval>] ``` sourcemasteraddresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. commaseparatedlistofstream_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 <interval>*: The `minus <interval>` is the same format as described in , or see . Example ```sh ./bin/yb-admin \ -master_addresses 127.0.0.1:7100,127.0.0.2:7100,127.0.0.3:7100 \ waitforreplication_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 <stream_id>: Tablet: <tablet_id> Tablet: <tablet_id> // ...... // ...... ``` Lists the CDC streams for the specified YB-Master servers. {{< note title="Tip" >}} Use this command when setting up universe replication to verify if any tables are configured for replication. If not, run ; if tables are already configured for replication, use to add more tables. {{< /note >}} Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ listcdcstreams ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value 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 \ listcdcstreams ``` Deletes underlying CDC stream for the specified YB-Master servers. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ deletecdcstream <streamid [forcedelete]> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. stream_id*: The ID of the CDC stream. `force_delete`: (Optional) Force the delete operation. {{< note title="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

{{< /note >}} Mark a set of tables in preparation for setting up universe level replication. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ bootstrapcdcproducer <commaseparatedlistoftable_ids> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. commaseparatedlistoftableids*: Comma-separated list of unique UUIDs associated with the tables (`tableid`). Example ```sh ./bin/yb-admin \ -master_addresses 172.0.0.11:7100,127.0.0.12:7100,127.0.0.13:7100 \ bootstrapcdcproducer 000030ad000030008000000000004000 ``` ```output table id: 000030ad000030008000000000004000, CDC bootstrap id: dd5ea73b5d384b2c9ebd6c7b6d05972c ``` {{< note title="Note" >}} The CDC bootstrap ids are the ones that should be used with and . {{< /note >}} Returns the replication status of all consumer streams. If source_universe_uuid is provided, this will only return streams that belong to an associated universe key. If replication_name is provided, this will only return the stream that belongs to the specified replication. Syntax ```sh yb-admin \ -master_addresses <target-master-addresses> \ getreplicationstatus [ <sourceuniverseuuid><replicationname> ] ``` sourceuniverseuuid*: (Optional) The UUID of the source universe. replication_name*: (Optional) The name of the replication stream. Example ```sh ./bin/yb-admin \ -master_addresses 172.0.0.11:7100,127.0.0.12:7100,127.0.0.13:7100 \ getreplicationstatus e260b8b6-e89f-4505-bb8e-b31f74aa29f3 ``` ```output statuses { table_id: "03ee1455f2134d5b914dd499ccad4377" stream_id: "53441ad2dd9f4e44a76dccab74d0a2ac" errors { error: REPLICATIONMISSINGOP_ID error_detail: "Unable to find expected op id on the producer" } } ``` Gets the tablet load move completion percentage for blacklisted nodes. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ getleaderblacklist_completion ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. Example ```sh ./bin/yb-admin \ -master_addresses ip1:7100,ip2:7100,ip3:7100 \ getleaderblacklist_completion ``` 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 <master-addresses> \ changeblacklist [ ADD | REMOVE ] <ipaddr>:<port> \ [ <ip_addr>:<port> ]... ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value 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 ``` Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ changeleaderblacklist [ ADD | REMOVE ] <ip_addr>:<port> \ [ <ip_addr>:<port> ]... ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. ADD | REMOVE: Adds or removes the specified 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 \ changeleaderblacklist \ ADD node1:9100 node2:9100 node3:9100 node4:9100 node5:9100 node6:9100 ``` Forces the YB-TServer leader of the specified tablet to step down. {{< note title="Note" >}} Use this command only if recommended by Yugabyte support. There is a possibility of downtime. {{< /note >}} Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ leaderstepdown <tabletid> <desttsuuid> ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. tablet_id*: The identifier (ID) of the tablet. desttsuuid: 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 title="Note" >}} If specified, `destsuuid` 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 {{< /note >}} For information on YB-Master load balancing, see For YB-Master load balancing flags, see . Enables or disables the load

Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ setloadbalancer_enabled [ 0 | 1 ] ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value 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 \ setloadbalancer_enabled 0 ``` Returns the cluster load balancer state. Syntax ```sh yb-admin \ -masteraddresses <master-addresses> getloadbalancerstate ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. 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 <master-addresses> \ getloadmove_completion ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. {{< note title="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 {{< /note >}} For an example of performing a data move and the use of this command, refer to . 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 \ getloadmove_completion ``` Returns the following percentage: ```output 66.6 ``` Finds out if the load balancer is idle. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ getisloadbalanceridle ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. Example ```sh ./bin/yb-admin \ -master_addresses ip1:7100,ip2:7100,ip3:7100 \ getisloadbalanceridle ``` Refer to to learn about how to upgrade a YugabyteDB cluster. protect new features that modify the format of data sent over the wire or stored on-disk. After all YugabyteDB processes have been upgraded to the new version, these features can be enabled by promoting their AutoFlags. Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ promoteautoflags \ [<maxflagsclass> [<promotenonruntime_flags> [force]]] ``` master-addresses*: Comma-separated list of YB-Master hosts and ports. Default value is `localhost:7100`. maxflagsclass*: The maximum AutoFlag class to promote. Allowed values are `kLocalVolatile`, `kLocalPersisted`, `kExternal`, `kNewInstallsOnly`. Default value is `kExternal`. promotenonruntime_flags*: Weather to promote non-runtime flags. Allowed values are `true` and `false`. Default value 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 \ promoteautoflags 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 ``` Upgrades the YSQL system catalog after a successful . YSQL upgrades are not required for clusters where . Syntax ```sh yb-admin \ -master_addresses <master-addresses> \ upgrade_ysql ``` 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 the above command is an online operation and doesn't require stopping a running cluster. This command is idempotent and can be run multiple times without any side effects. {{< note title="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. {{< /note >}}