docs/content/stable/admin/yb-admin.md
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 and yb-tserver servers to perform the necessary administration.
{{< note title="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 or 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 and 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 {{% support-platform %}}.
{{< /note >}}
To use yb-admin from the YugabyteDB home directory, run ./bin/yb-admin using the following syntax.
yb-admin \
[ --master_addresses <master-addresses> ] \
[ --init_master_addrs <master-address> ] \
[ --timeout_ms <millisec> ] \
[ --certs_dir_name <dir-name> ] \
<command> [ 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.
command: The operation to be performed. See Commands 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.
./bin/yb-admin --help
Gets the configuration for the universe.
Syntax
yb-admin \
--master_addresses <master-addresses> \
get_universe_config
localhost:7100.Changes the configuration of a tablet.
Syntax
yb-admin \
--master_addresses <master-addresses> \
change_config <tablet-id> \
[ ADD_SERVER | REMOVE_SERVER ] \
<peer-uuid> \
[ PRE_VOTER | PRE_OBSERVER ]
localhost:7100.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 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).
Changes the master configuration.
Syntax
yb-admin \
--master_addresses <master-addresses> \
change_master_config \
[ ADD_SERVER|REMOVE_SERVER ] \
<ip-addr> <port> \
[<uuid>]
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) or run the yb-admin 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.
Syntax
yb-admin \
--master_addresses <master-addresses> \
list_tablet_servers <tablet-id>
localhost:7100.Lists all tablets and their replica locations for a particular table.
Use this to find out who the LEADER of a tablet is.
Syntax
yb-admin \
--master_addresses <master-addresses> \
list_tablets <keyspace-type>.<keyspace-name> <table> [<max-tablets>]
localhost:7100.10. Set to 0 to return all tablets.Example
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
list_tablets ysql.db_name table_name 0
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: ""
Lists all tablet servers.
Syntax
yb-admin \
--master_addresses <master-addresses> \
list_all_tablet_servers
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
yb-admin \
--master_addresses <master-addresses> \
list_all_masters
localhost:7100.Example
./bin/yb-admin \
--master_addresses node7:7100,node8:7100,node9:7100 \
list_all_masters
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
yb-admin \
--master_addresses <master-addresses> \
list_replica_type_counts <keyspace> <table-name>
localhost:7100.Prints the status of the YB-Master servers.
Syntax
yb-admin \
--master_addresses <master-addresses> \
dump_masters_state
localhost:7100.List the locations of the tablet server logs.
Syntax
yb-admin \
--master_addresses <master-addresses> \
list_tablet_server_log_locations
localhost:7100.Lists all tablets for the specified tablet server (YB-TServer).
Syntax
yb-admin \
--master_addresses <master-addresses> \
list_tablets_for_tablet_server <ts-uuid>
localhost:7100.Splits the specified hash-sharded tablet and computes the split point as the middle of tablet's sharding range.
yb-admin \
--master_addresses <master-addresses> \
split_tablet <tablet-id-to-split>
localhost:7100.For more information on tablet splitting, see:
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
yb-admin \
--master_addresses <master-addresses> \
master_leader_stepdown [ <new-leader-id> ]
localhost:7100.Prints the current YSQL schema catalog version.
Syntax
yb-admin \
--master_addresses <master-addresses> \
ysql_catalog_version
localhost:7100.Example
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
ysql_catalog_version
The version output displays:
Version:1
Prints a list of all tables. Optionally, include the database type, table ID, and the table type.
Syntax
yb-admin \
--master_addresses <master-addresses> \
list_tables \
[ include_db_type ] [ include_table_id ] [ include_table_type ]
yb-admin \
--master_addresses <master-addresses> list_tables
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:
<db-type>.<namespace>.<table-name> <table-id> <table-type>
ysql, ycql, and unknown.catalog, table, index, and other.{{< note title="Tip" >}}
To display a list of tables and their UUID (table_id) values, open the YB-Master UI (<master_host>:7000/) and click Tables in the navigation bar.
{{< /note >}}
Example
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
list_tables
...
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
...
Triggers manual compaction on a table.
Syntax 1: Using table name
yb-admin \
--master_addresses <master-addresses> \
compact_table <db-type>.<namespace> <table> [<timeout-in-seconds>] [ADD_INDEXES] [ADD_VECTOR_INDEXES]
localhost:7100.ysql and ycql.20.Example
./bin/yb-admin \
--master_addresses $MASTER_RPC_ADDRS \
compact_table ysql.yugabyte table_name
Compacted [yugabyte.table_name] tables.
Syntax 2: Using table ID
yb-admin \
--master_addresses <master-addresses> \
compact_table tableid.<table-id> [<timeout-in-seconds>] [ADD_INDEXES] [ADD_VECTOR_INDEXES]
localhost:7100.20.Example
./bin/yb-admin \
--master_addresses $MASTER_RPC_ADDRS \
compact_table tableid.000033eb000030008000000000004002
Compacted [000033eb000030008000000000004002] tables.
Triggers manual compaction on a table by table ID (without resolving namespace and table name).
Syntax
yb-admin \
--master_addresses <master-addresses> \
compact_table_by_id <table-id> [<timeout-in-seconds>] [ADD_INDEXES] [ADD_VECTOR_INDEXES]
localhost:7100.20.Example
./bin/yb-admin \
--master_addresses $MASTER_RPC_ADDRS \
compact_table_by_id 000033eb000030008000000000004002 ADD_VECTOR_INDEXES
Compacted [000033eb000030008000000000004002] tables.
Show the status of full compaction on a table.
yb-admin \
--master_addresses <master-addresses> \
compaction_status <db-type>.<namespace> <table> [show_tablets]
localhost:7100.ysql and ycql.show_tablets: Show the compactions status of individual tablets.Example
./bin/yb-admin \
--master_addresses $MASTER_RPC_ADDRS \
compaction_status ysql.yugabyte table_name show_tablets
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
Modifies the placement information (cloud, region, and zone) for a table.
Syntax
yb-admin \
--master_addresses <master-addresses> \
modify_table_placement_info <keyspace> <table-name> <placement-info> <replication-factor> \
[ <placement-id> ]
or alternatively:
yb-admin \
--master_addresses <master-addresses> \
modify_table_placement_info tableid.<table-id> <placement-info> <replication-factor> \
[ <placement-id> ]
localhost:7100.cloud1.datacenter1.rack1.Example
./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 (<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 Tablespaces instead. {{< /note >}}
Creates a transaction status table to be used in a region. This command should always be followed by modify_table_placement_info to set the placement information for the newly-created transaction status table.
Syntax
yb-admin \
--master_addresses <master-addresses> \
create_transaction_table \
<table-name>
localhost:7100.transactions_.The transaction status table will be created as system.<table-name>.
Example
./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 (<master_host>: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:
./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 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
yb-admin \
--master_addresses <master-addresses> \
add_transaction_tablet \
<table-id>
localhost:7100.Example
./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 command.
Flush the memstores of the specified table on all tablet servers to disk.
Syntax 1: Using table name
yb-admin \
--master_addresses <master-addresses> \
flush_table <db-type>.<namespace> <table> [<timeout-in-seconds>] [ADD_INDEXES]
localhost:7100.ysql and ycql.20.Example
./bin/yb-admin \
--master_addresses $MASTER_RPC_ADDRS \
flush_table ysql.yugabyte table_name
Flushed [yugabyte.table_name] tables.
Syntax 2: Using table ID
yb-admin \
--master_addresses <master-addresses> \
flush_table tableid.<table-id> [<timeout-in-seconds>] [ADD_INDEXES]
localhost:7100.20.Example
./bin/yb-admin \
--master_addresses $MASTER_RPC_ADDRS \
flush_table tableid.000033eb000030008000000000004002
Flushed [000033eb000030008000000000004002] tables.
Backfill all DEFERRED indexes in a YCQL table.
Syntax
yb-admin \
--master_addresses <master-addresses> \
backfill_indexes_for_table <keyspace> <table-name>
localhost:7100.ycql.keyspace-name.Example
./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.
The following backup and snapshot commands are available:
{{< note title="YugabyteDB Anywhere" >}}
If you are using YugabyteDB Anywhere to manage point-in-time-recovery (PITR) for a universe, you must initiate and manage PITR using the YugabyteDB Anywhere UI. If you use the yb-admin CLI to make changes to the PITR configuration of a universe managed by YugabyteDB Anywhere, including creating schedules and snapshots, your changes are not reflected in YugabyteDB Anywhere.
{{< /note >}}
Creates a snapshot of the specified YSQL database.
Syntax
yb-admin \
--master_addresses <master-addresses> \
create_database_snapshot <database>
localhost:7100.When this command runs, a snapshot_id is generated and printed.
Example
./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 command.
Creates a snapshot of the specified YCQL keyspace.
Syntax
yb-admin \
--master_addresses <master-addresses> \
create_keyspace_snapshot <keyspace>
localhost:7100.When this command runs, a snapshot_id is generated and printed.
Example
./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 command.
Prints a list of all snapshot IDs, restoration IDs, and states. Optionally, prints details (including keyspaces, tables, and indexes) in JSON format.
Syntax
yb-admin \
--master_addresses <master-addresses> \
list_snapshots \
[ show_details ] [ not_show_restored ]
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, staterestore_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: <snapshot_id> or <restoration_id>data:
name: "<namespace_name>"database_type: "YQL_DATABASE_CQL"colocated: true or falsestate: "<state>"type: TABLE <== Use for table or index
id: "<table_id>" or "<index_id>"data:
name: "<table_name>" or "<index_id>"version: "<table_version>"state: "<state>"state_msg: "<state_msg>"next_column_id: "<column_id>"table_type: "YQL_TABLE_TYPE"namespace_id: "<namespace_id>"indexed_table_id (index only): <table_id>is_local_index (index only): true or falseis_unique_index (index only): true or falseExample
In this example, the optional show_details flag is added to generate the snapshot details.
./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:
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:
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 delete_snapshot command.
Use the create_snapshot_schedule command to create snapshots that expire after a specified time interval.
{{</ note >}}
Syntax
yb-admin \
--master_addresses <master-addresses> \
create_snapshot <keyspace> <table-name> | <table_id> \
[<keyspace> <table-name> | <table-id> ]... \
[<flush-timeout-in-seconds>]
localhost:7100.60. To skip flushing, set the value to 0.When this command runs, a snapshot_id is generated and printed.
Example
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
create_snapshot ydb test_tb
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 command.
Restores the specified snapshot, including the tables and indexes. When the operation starts, a restoration_id is generated.
Syntax
yb-admin \
--master_addresses <master-addresses> \
restore_snapshot <snapshot-id> <restore-target>
localhost:7100.minus 5m (to restore to 5 minutes ago). Optional; omit to restore to the given snapshot's creation time.Example
./bin/yb-admin restore_snapshot 72ad2eb1-65a2-4e88-a448-7ef4418bc469
When the restore starts, the snapshot_id and the generated restoration_id are displayed.
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 command.
./bin/yb-admin list_snapshots
For the example above, the restore failed, so the following displays:
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:
Syntax
yb-admin \
--master_addresses <master-addresses> \
list_snapshot_restorations <restoration-id>
localhost:7100.Example
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
list_snapshot_restorations 26ed9053-0c26-4277-a2b8-c12d0fa4c8cf
{
"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
yb-admin \
--master_addresses <master-addresses> \
export_snapshot <snapshot-id> <file-name>
localhost:7100..snapshot.Example
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
export_snapshot 4963ed18fc1e4f1ba38c8fcf4058b295 \
test_tb.snapshot
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
yb-admin \
--master_addresses <master-addresses> \
import_snapshot <file-name> \
[<keyspace> <table-name> [<keyspace> <table-name>]...]
localhost:7100.{{< note title="Note" >}}
The keyspace and the table can be different from the exported one.
{{< /note >}}
Example
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
import_snapshot test_tb.snapshot ydb test_tb
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
Imports only the specified tables from the specified snapshot metadata file.
Syntax
yb-admin \
--master_addresses <master-addresses> \
import_snapshot_selective <file-name> \
[<keyspace> <table-name> [<keyspace> <table-name>]...]
localhost:7100.{{< note title="Note" >}}
The keyspace can be different from the exported one. The name of the table needs to be the same.
{{< /note >}}
Example
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
import_snapshot_selective test_tb.snapshot ydb test_tb
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
yb-admin \
--master_addresses <master-addresses> \
delete_snapshot <snapshot-id>
localhost:7100.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
yb-admin create_snapshot_schedule \
--master_addresses <master-addresses> \
<snapshot-interval>\
<retention-time>\
<filter-expression>
localhost:7100.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:
./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:
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
create_snapshot_schedule 60 120 yugabyte
{
"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:
Snapshot list entries include:
Syntax
yb-admin \
--master_addresses <master-addresses> \
list_snapshot_schedules <schedule-id>
localhost:7100.Example
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
list_snapshot_schedules 6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256
{
"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"
}
]
}
]
}
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
yb-admin \
--master_addresses <master-addresses> \
edit_snapshot_schedule <schedule-id> \
[ interval <snapshot-interval> ] \
[ retention <retention-time> ] \
localhost:7100.Example
Edit a snapshot schedule to take a snapshot once every 90 minutes, and retain each snapshot for 3 hours:
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
edit_snapshot_schedule 6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256 \
interval 90 retention 180
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 time.
Syntax
yb-admin \
--master_addresses <master-addresses> \
restore_snapshot_schedule <schedule-id> <restore-target>
localhost:7100.minus 5m (to restore to 5 minutes ago).You can also use a YSQL timestamp or YCQL timestamp 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 agominus 1h to restore from one hour agominus 3d to restore from three days agominus 1h 5m to restore from one hour and five minutes agoRelative times can be in any of the following formats (again, note that you can specify any or all of days, hours, minutes, and seconds):
3d 4h 5m 6s3 d 4 hrs 5 mins 6 secs3 days 4 hours 5 minutes 6 secondsD H:M:SExamples
Restore from an absolute timestamp:
./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:
./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:
{
"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
yb-admin \
--master_addresses <master-addresses> \
delete_snapshot_schedule <schedule-id>
localhost:7100.Example
./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.
{
"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
yb-admin \
--master_addresses <master-addresses> \
modify_placement_info <placement-info> <replication-factor> \
[ <placement-id> ]
localhost:7100.Example
./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:
You can verify the new placement information by running the following curl command:
curl -s http://<any-master-ip>: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:
./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:
./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.
Sets the preferred availability zones (AZs) and regions. 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 modify_placement_info 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 affinitized_leaders or multi_affinitized_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 topology keys to target the preferred zones.
{{< /note >}}
Syntax
yb-admin \
--master_addresses <master-addresses> \
set_preferred_zones <cloud.region.zone>[:<preference>] \
[<cloud.region.zone>[:<preference>]]...
localhost:7100.cloud1.datacenter1.rack1.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:
curl -s http://<any-master-ip>:7000/cluster-config
The following is a sample configuration:
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 sets the preferred region to gcp.us-west1 and the fallback to zone gcp.us-east4.us-east4-a:
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
Verify by running the following.
curl -s http://<any-master-ip>:7000/cluster-config
Looking again at the cluster configuration you should see multi_affinitized_leaders added:
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"
}
}
}
Add a read replica cluster to the master configuration.
Syntax
yb-admin \
--master_addresses <master-addresses> \
add_read_replica_placement_info <placement-info> \
<replication-factor> \
[ <placement-id> ]
localhost:7100.<cloud1.region1.zone1>:<num_replicas_in_zone1>,<cloud2.region2.zone2>:<num_replicas_in_zone2>,.... 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.Syntax
yb-admin \
--master_addresses <master-addresses> \
modify_read_replica_placement_info <placement-info> \
<replication-factor> \
[ <placement-id> ]
localhost:7100.cloud1.datacenter1.rack1.Delete the read replica.
Syntax
yb-admin \
--master_addresses <master-addresses> \
delete_read_replica_placement_info
localhost:7100.For details on using encryption at rest, see Encryption at rest.
Sets the contents of key-path in-memory on each YB-Master node.
Syntax
yb-admin \
--master_addresses <master-addresses> \
add_universe_key_to_all_masters <key-id> <key-path>
localhost:7100.{{< note title="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 command and enable encryption using the rotate_universe_key_in_memory command.
{{< /note >}}
Checks whether the universe key associated with the provided key-id exists in-memory on each YB-Master node.
yb-admin \
--master_addresses <master-addresses> all_masters_have_universe_key_in_memory <key-id>
localhost:7100.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 all_masters_have_universe_key_in_memory value must be true for the universe key to be successfully rotated and enabled).
{{< /note >}}
Syntax
yb-admin \
--master_addresses <master-addresses> rotate_universe_key_in_memory <key-id>
localhost:7100.Disables the in-memory encryption at rest for newly-written data files.
Syntax
yb-admin \
--master_addresses <master-addresses> \
disable_encryption_in_memory
localhost:7100.Checks if cluster-wide encryption is enabled.
Syntax
yb-admin \
--master_addresses <master-addresses> \
is_encryption_enabled
localhost:7100.Returns message:
Encryption status: ENABLED with key id <key_id_2>
The new key ID (<key_id_2>) should be different from the previous one (<key_id>).
Example
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
is_encryption_enabled
Encryption status: ENABLED with key id <key_id_2>
Create a change data capture (CDC) DB stream for the specified namespace using the following command.
Syntax
yb-admin \
--master_addresses <master-addresses> \
create_change_data_stream ysql.<namespace-name>
localhost:7100.For example:
./bin/yb-admin \
--master_addresses 127.0.0.1:7100 \
create_change_data_stream ysql.yugabyte
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 {{<tags/feature/tp>}}. Use the yb_enable_cdc_consistent_snapshot_streams flag to enable the feature.
Syntax
yb-admin \
--master_addresses <master-addresses> \
create_change_data_stream ysql.<namespace-name> [EXPLICIT] [<before-image-mode>] [USE_SNAPSHOT | NOEXPORT_SNAPSHOT]
localhost:7100.For example:
./bin/yb-admin \
--master_addresses 127.0.0.1:7100 \
create_change_data_stream ysql.yugabyte EXPLICIT CHANGE USE_SNAPSHOT
To create a change data capture (CDC) DB stream which also supports sending the before image of the record, use the following command.
Syntax
yb-admin \
--master_addresses <master-addresses> \
create_change_data_stream ysql.<namespace-name> [EXPLICIT] <before-image-mode>
localhost:7100.A successful operation of the above command returns a message with a DB stream ID:
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
yb-admin \
--master_addresses <master-addresses> \
create_change_data_stream ysql.<namespace-name> EXPLICIT
localhost:7100.A successful operation of the above command returns a message with a DB stream ID:
CDC Stream ID: d540f5e4890c4d3b812933cbfd703ed3
{{< note title="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.
{{< /note >}}
Lists all the created CDC DB streams.
Syntax
yb-admin \
--master_addresses <master-addresses> \
list_change_data_streams [namespace-name]
localhost:7100.Example:
./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:
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
yb-admin \
--master_addresses <master-addresses> \
get_change_data_stream_info <db-stream-id>
localhost:7100.Example:
./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:
CDC DB Stream Info:
table_info {
stream_id: "d540f5e4890c4d3b812933cbfd703ed3"
table_id: "000033e1000030008000000000004000"
}
namespace_id: "000033e1000030008000000000000000"
Delete the specified CDC DB stream.
Syntax
yb-admin \
--master_addresses <master-addresses> \
delete_change_data_stream <db-stream-id>
localhost:7100.Example:
./bin/yb-admin \
--master_addresses 127.0.0.1:7100 \
delete_change_data_stream d540f5e4890c4d3b812933cbfd703ed3
The above command results in the following response:
Successfully deleted CDC DB Stream ID: d540f5e4890c4d3b812933cbfd703ed3
For detailed step-by-step instructions on deploying xCluster, refer to the Deploy xCluster. For monitoring xCluster, refer to Monitor xCluster.
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 to add more tables.
To verify if any tables are already configured for replication, use list_cdc_streams.
Syntax
yb-admin \
--master_addresses <target-master-addresses> \
setup_universe_replication \
<replication-group-id> \
<source-master-addresses> \
<source-table-ids> \
[ <bootstrap-ids> ] \
[ transactional ]
localhost:7100.table_id).bootstrap_id). Obtain these with bootstrap_cdc_producer, 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 (table_id) values, open the YB-Master UI (<master_host>:7000/) and click Tables in the navigation bar.
{{< /note >}}
Example
./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
Changes the universe replication for the specified source universe. Use this command to do the following:
If no tables have been configured for replication, use setup_universe_replication.
To check if any tables are configured for replication, use 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:
yb-admin --master_addresses <target-master-addresses> \
alter_universe_replication <replication-group-id> \
set_master_addresses <source-master-addresses>
localhost:7100.Use the add_table subcommand to add one or more tables to the existing list:
yb-admin --master_addresses <target-master-addresses> \
alter_universe_replication <replication-group-id> \
add_table <source-table-ids> \
[ <bootstrap-ids> ]
localhost:7100.table_id).bootstrap_id). Obtain these with bootstrap_cdc_producer, 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:
yb-admin --master_addresses <target-master-addresses> \
alter_universe_replication <replication-group-id> \
remove_table <source-table-ids> [ignore-errors]
localhost:7100.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.
yb-admin --master_addresses <target-master-addresses> \
alter_universe_replication <replication-group-id> \
rename_id <new-replication-group-id>
localhost:7100.Deletes universe replication for the specified source universe.
Syntax
yb-admin \
--master_addresses <target-master-addresses> \
delete_universe_replication <replication-group-id>
localhost:7100.Sets the universe replication to be enabled or disabled.
Syntax
yb-admin \
--master_addresses <target-master-addresses> \
set_universe_replication_enabled <replication-group-id> [0|1]
localhost:7100.0 | 1: Disabled (0) or enabled (1). Default is 1.Reports the current xCluster safe time for each namespace, which is the time at which reads will be performed.
Syntax
yb-admin \
--master_addresses <target-master-addresses> \
get_xcluster_safe_time \
[include_lag_and_skew]
localhost:7100.include_lag_and_skew: Display the safe_time_lag_sec and safe_time_skew_sec.Example
./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
{
"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"
}
epoch of the safe time.(current time - current safe time).(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
yb-admin \
--master_addresses <source-master-addresses> \
wait_for_replication_drain \
<stream-ids> [<timestamp> | minus <interval>]
localhost:7100.minus <interval>: The same format as described in Restore from a relative time, or see restore_snapshot_schedule.Example
./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:
Found undrained replications:
- Under Stream <stream_id>:
- Tablet: <tablet_id>
- Tablet: <tablet_id>
// ......
// ......
Lists the xCluster outbound streams.
{{< note title="Tip" >}}
Use this command when setting up xCluster replication to verify if any tables are configured for replication. If not, run setup_universe_replication; if tables are already configured for replication, use alter_universe_replication to add more tables.
{{< /note >}}
Syntax
yb-admin \
--master_addresses <master-addresses> \
list_cdc_streams
localhost:7100.Example
./bin/yb-admin \
--master_addresses 127.0.0.11:7100,127.0.0.12:7100,127.0.0.13:7100 \
list_cdc_streams
Deletes underlying xCluster outbound streams.
Syntax
yb-admin \
--master_addresses <master-addresses> \
delete_cdc_stream <stream-id> \
[force_delete]
localhost:7100.force_delete: 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 delete_universe_replication. {{< /note >}}
Mark a set of tables in preparation for setting up xCluster replication.
Syntax
yb-admin \
--master_addresses <source-master-addresses> \
bootstrap_cdc_producer <source-table-ids>
localhost:7100.table_id).Example
./bin/yb-admin \
--master_addresses 172.0.0.11:7100,127.0.0.12:7100,127.0.0.13:7100 \
bootstrap_cdc_producer 000030ad000030008000000000004000
table id: 000030ad000030008000000000004000, CDC bootstrap id: dd5ea73b5d384b2c9ebd6c7b6d05972c
{{< note title="Note" >}} The xCluster bootstrap IDs are the ones that should be used with setup_universe_replication and alter_universe_replication. {{< /note >}}
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
yb-admin \
--master_addresses <target-master-addresses> \
get_replication_status [ <replication-group-id> ]
localhost:7100.Example
./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
statuses {
table_id: "03ee1455f2134d5b914dd499ccad4377"
stream_id: "53441ad2dd9f4e44a76dccab74d0a2ac"
errors {
error: REPLICATION_MISSING_OP_ID
error_detail: "Unable to find expected op id on the producer"
}
}
Checkpoint namespaces for use in xCluster replication.
Syntax
yb-admin \
--master_addresses <source-master-addresses> \
create_xcluster_checkpoint \
<replication-group-id> \
<namespace_names> \
[automatic_ddl_mode]
localhost:7100.automatic_ddl_mode: Use xCluster automatic mode.Checks if the databases of a previously checkpointed replication group requires a bootstrap (backup/restore) of the database to the target universe.
Syntax
yb-admin \
--master_addresses <source-master-addresses> \
is_xcluster_bootstrap_required \
<replication-group-id> \
<namespace-names>
localhost:7100.Setup xCluster replication using a previously created checkpoint.
Syntax
yb-admin \
--master_addresses <source-master-addresses> \
setup_xcluster_replication \
<replication-group-id> \
<target-master-addresses>
localhost:7100.localhost:7100.Drops the xCluster replication group. If target-master-addresses are provided, it will also drop the replication on the target universe.
Syntax
yb-admin \
--master_addresses <source-master-addresses> \
drop_xcluster_replication \
<replication-group-id> \
[<target-master-addresses>]
localhost:7100.localhost:7100.Adds a database to an existing xCluster checkpoint.
Syntax
yb-admin \
--master_addresses <source-master-addresses> \
add_namespace_to_xcluster_checkpoint \
<replication-group-id> \
<namespace-name>
localhost:7100.Adds a database to an existing xCluster replication after it has been checkpointed (and bootstrapped if needed).
Syntax
yb-admin \
--master_addresses <source-master-addresses> \
add_namespace_to_xcluster_replication \
<replication-group-id> \
<namespace-name> \
<target-master-addresses>
localhost:7100.localhost:7100.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
yb-admin \
--master_addresses <source-master-addresses> \
remove_namespace_from_xcluster_replication \
<replication-group-id> \
<namespace-name> \
[<target-master-addresses>]
localhost:7100.localhost:7100.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
yb-admin \
--master_addresses <source-master-addresses> \
list_xcluster_outbound_replication_groups \
[<namespace-id>]
localhost:7100.Display the status of a specific outbound xCluster replication group.
Syntax
yb-admin \
--master_addresses <source-master-addresses> \
get_xcluster_outbound_replication_group_info \
<replication-group-id>
localhost:7100.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
yb-admin \
--master_addresses <target-master-addresses> \
list_universe_replications \
[<namespace-id>]
localhost:7100.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 {{<release "2024.2.8.0">}} and later, {{<release "2025.1.4.0">}} and later, and {{<release "2025.2">}}.
Syntax
yb-admin \
--master_addresses <master-addresses> \
are_nodes_safe_to_take_down <server-uuids> [follower_lag_bound_ms]
localhost:7100.list_all_tablet_servers and list_all_masters.follower_lag_bound_ms: Optional. Maximum allowed follower lag in milliseconds. Default is 1000.Example
./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):
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
are_nodes_safe_to_take_down 1b9486461cdd48f59eb46b33992cd73a, c0505f1d31774a3d88fae26ce14cde10 2000
Gets the tablet load move completion percentage for blacklisted nodes.
Syntax
yb-admin \
--master_addresses <master-addresses> \
get_leader_blacklist_completion
localhost:7100.Example
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
get_leader_blacklist_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
yb-admin \
--master_addresses <master-addresses> \
change_blacklist [ ADD | REMOVE ] <ip_addr>:<port> \
[ <ip_addr>:<port> ]...
localhost:7100.Example
./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
yb-admin \
--master_addresses <master-addresses> \
change_leader_blacklist [ ADD | REMOVE ] <ip_addr>:<port> \
[ <ip_addr>:<port> ]...
localhost:7100.Example
./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
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
yb-admin \
--master_addresses <master-addresses> \
leader_stepdown <tablet-id> <dest-ts-uuid>
localhost:7100."" 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, 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
{{< /note >}}
YugabyteDB automatically balances the cluster via the 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.
For YB-Master cluster balancing flags, see Cluster balancing flags.
Enables or disables the cluster balancer.
Syntax
yb-admin \
--master_addresses <master-addresses> \
set_load_balancer_enabled [ 0 | 1 ]
localhost:7100.0 | 1: Enabled (1) is the default. To disable, set to 0.Example
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
set_load_balancer_enabled 0
Returns the cluster load balancer state.
Syntax
yb-admin \
--master_addresses <master-addresses> get_load_balancer_state
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
yb-admin \
--master_addresses <master-addresses> \
get_load_move_completion
localhost:7100.{{< note title="Note" >}}
The time needed to complete a data move depends on the following:
{{< /note >}}
For an example of performing a data move and the use of this command, refer to Change cluster configuration.
Example
In the following example, the data move is 66.6 percent done.
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
get_load_move_completion
Returns the following percentage:
66.6
Finds out if the cluster balancer is idle.
Syntax
yb-admin \
--master_addresses <master-addresses> \
get_is_load_balancer_idle
localhost:7100.Example
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
get_is_load_balancer_idle
Refer to 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.
Returns the current AutoFlags configuration of the universe.
Syntax
yb-admin \
--master_addresses <master-addresses> \
get_auto_flags_config
localhost:7100.Example
./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:
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
}
}
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
yb-admin \
--master_addresses <master-addresses> \
promote_auto_flags \
[<max-flags-class> [<promote-non-runtime-flags> [force]]]
localhost:7100.kLocalVolatile, kLocalPersisted and kExternal. Default is kExternal.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
./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:
PromoteAutoFlags status:
New AutoFlags were promoted. Config version: 2
OR
PromoteAutoFlags status:
No new AutoFlags to promote
Upgrades the YSQL system catalog after a successful YugabyteDB cluster upgrade.
YSQL upgrades are not required for clusters where YSQL is not enabled.
Syntax
yb-admin \
--master_addresses <master-addresses> \
upgrade_ysql
localhost:7100.Example
./bin/yb-admin \
--master_addresses ip1:7100,ip2:7100,ip3:7100 \
upgrade_ysql
A successful upgrade returns the following message:
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:
./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 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 >}}
Finalizes an upgrade after a successful 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
yb-admin \
--master_addresses <master-addresses> \
finalize_upgrade
localhost:7100.Example
./bin/yb-admin --master_addresses 127.0.0.1:7100,127.0.0.2:7100,127.0.0.3:7100 finalize_upgrade
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