yb-admin

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.

Syntax

To use the yb-admin utility from the YugabyteDB home directory, run ./bin/yb-admin using the following syntax.

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.

• timeout_ms: The RPC timeout, in milliseconds. Default value is 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 value 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 command for syntax details and examples.

• command_flags: Configuration flags that can be applied to the command.

Online help

To display the online help, run yb-admin --help from the YugabyteDB home directory.

Commands

• Universe and cluster
• Table
• Backup and snapshot
• Deployment topology
  • Multi-zone and multi-region
  • Master-follower
  • Read replica
• Security
  • Encryption at rest
• Change data capture (CDC)
• Decommissioning
• Rebalancing
• Upgrade YSQL system catalog

---

Universe and cluster commands

get_universe_config

Gets the configuration for the universe.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.

change_config

Changes the configuration of a tablet.

Syntax

• master_addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• tablet_id: The identifier (ID) of the tablet.
• ADD_SERVER | REMOVE_SERVER: Subcommand to add or remove the server.
• peer_uuid: The UUID of the tablet server hosting the peer tablet.
• PRE_VOTER | PRE_OBSERVER: Role of the new peer joining the quorum. Required when using the ADD_SERVER subcommand.

Notes:

If you need to take a node down temporarily, but intend to bring it back up, you should not need to use the REMOVE_SERVER subcommand.

• If the node is down for less than 15 minutes, it will catch up through RPC calls when it comes back online.
• If the node is offline longer than 15 minutes, then it will go through Remote Bootstrap, where the current leader will forward all relevant files to catch up.

If you do not intend to bring a node back up (perhaps you brought it down for maintenance, but discovered that the disk is bad), then you want to decommission the node (using the REMOVE_SERVER subcommand) and then add in a new node (using the ADD_SERVER subcommand).

change_master_config

Changes the master configuration.

Syntax

• master_addresses: Comma-separated list of YB-Master hosts and ports. Default value 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.

list_tablet_servers

Syntax

• master_addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• tablet_id: The identifier (ID) of the tablet.

list_tablets

Lists all tablets and their replica locations for a particular table.

Useful to find out who the LEADER of a tablet is.

Syntax

• 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.
• max_tablets: The maximum number of tables to be returned. Default is 10. Set to 0 to return all tablets.

Example

Tablet UUID                       Range                                                     Leader
cea3aaac2f10460a880b0b4a2a4b652a  partition_key_start: "" partition_key_end: "\177\377"     127.0.0.1:9100
e509cf8eedba410ba3b60c7e9138d479  partition_key_start: "\177\377" partition_key_end: ""

list_all_tablet_servers

Lists all tablet servers.

Syntax

yb-admin \
    -master_addresses <master-addresses> \
    list_all_tablet_servers

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.

list_all_masters

Displays a list of all YB-Master servers in a table listing the master UUID, RPC host and port, state (ALIVE or DEAD), and role (LEADER, FOLLOWER, or UNKNOWN_ROLE).

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.

Example

Master UUID         RPC Host/Port          State      Role
...                   node8:7100           ALIVE     FOLLOWER
...                   node9:7100           ALIVE     FOLLOWER
...                   node7:7100           ALIVE     LEADER

list_replica_type_counts

Prints a list of replica types and counts for the specified table.

Syntax

• 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.

dump_masters_state

Prints the status of the YB-Master servers.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.

list_tablet_server_log_locations

List the locations of the tablet server logs.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.

list_tablets_for_tablet_server

Lists all tablets for the specified tablet server (YB-TServer).

Syntax

• 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).

split_tablet

Splits the specified hash-sharded tablet and computes the split point as the middle of tablet's sharding range.

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• tablet_id_to_split: The identifier of the tablet to split.

For more information on tablet splitting, see:

• Tablet splitting — Architecture overview
• Automatic Re-sharding of Data with Tablet Splitting — Architecture design document in the GitHub repository.

master_leader_stepdown

Forces the master leader to step down. The specified YB-Master node will take its place as leader.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• new_leader_id: (Optional) The identifier (ID) of the new YB-Master leader. If not specified, the new leader is automatically elected.

ysql_catalog_version

Prints the current YSQL schema catalog version.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.

Example

The version output displays:

Version:1

---

Table commands

list_tables

Prints a list of all tables. Optionally, include the database type, table ID, and the table type.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• include_db_type: (Optional) Add this flag to include the database type for each table.
• include_table_id: (Optional) Add this flag to include the table ID for each 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

• 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.

Example

...
yugabyte.pg_range
template1.pg_attrdef
template0.pg_attrdef_adrelid_adnum_index
template1.pg_conversion
system_platform.pg_opfamily
postgres.pg_opfamily_am_name_nsp_index
system_schema.functions
template0.pg_statistic
system.local
template1.pg_inherits_parent_index
template1.pg_amproc
system_platform.pg_rewrite
yugabyte.pg_ts_config_cfgname_index
template1.pg_trigger_tgconstraint_index
template1.pg_class
template1.pg_largeobject
system_platform.sql_parts
template1.pg_inherits
...

compact_table

Triggers manual compaction on a table.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• keyspace: Specifies the database ysql.db-name or keyspace ycql.keyspace-name.
• table_name: Specifies the table name.
• timeout_in_seconds: Specifies duration, in seconds when the cli timeouts waiting for compaction to end. Default value is 20.

Example

Started compaction of table kong.test
Compaction request id: 75c406c1d2964487985f9c852a8ef2a3
Waiting for compaction...
Compaction complete: SUCCESS

modify_table_placement_info

Modifies the placement information (cloud, region, and zone) for a table.

Syntax

or alternatively:

• 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.
• placement_id: Identifier of the primary cluster. Optional. If set, it has to match the placement_id specified for the primary cluster in the cluster configuration.

Example

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.

create_transaction_table

Creates a transaction status table to be used within 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

• master_addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• table_name: The name of the transaction status table to be created; this must start with transactions_.

The transaction status table will be created as system.<table_name>.

Example

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:

After the load balancer runs, all tablets of system.transactions_us_east should now be solely located within the AWS us-east region.

---

Backup and snapshot commands

The following backup and snapshot commands are available:

• create_database_snapshot creates a snapshot of the specified YSQL database
• create_keyspace_snapshot creates a snapshot of the specified YCQL keyspace
• list_snapshots returns a list of all snapshots, restores, and their states
• create_snapshot creates a snapshot of one or more YCQL tables and indexes
• restore_snapshot restores a snapshot
• export_snapshot creates a snapshot metadata file
• import_snapshot imports a snapshot metadata file
• delete_snapshot deletes a snapshot's information
• create_snapshot_schedule sets the schedule for snapshot creation
• list_snapshot_schedules returns a list of all snapshot schedules
• restore_snapshot_schedule restores all objects in a scheduled snapshot

create_database_snapshot

Creates a snapshot of the specified YSQL database.

Syntax

• 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

To see if the database snapshot creation has completed, run the yb-admin list_snapshots command.

create_keyspace_snapshot

Creates a snapshot of the specified YCQL keyspace.

Syntax

• 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

To see if the database snapshot creation has completed, run the yb-admin list_snapshots command.

list_snapshots

Prints a list of all snapshot IDs, restoration IDs, and states. Optionally, prints details (including keyspaces, tables, and indexes) in JSON format.

Syntax

• 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.
• not_show_restored: (Optional) Do not show successful "restorations" (that is, COMPLETE). Useful 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:

• create_snapshot: snapshot_id, keyspace, table, state
• restore_snapshot: snapshot_id, restoration_id, state.
• delete_snapshot: snapshot_id, state.

When show_details is included, the list_snapshot 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 false
    • state: "<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 false
    • is_unique_index (index only): true or false

Example

In this example, the optional show_details flag is added to generate the snapshot details.

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

create_snapshot

Creates a snapshot of the specified YCQL tables and their indexes. Prior to v.2.1.8, indexes were not automatically included. You can specify multiple tables, even from different keyspaces.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• keyspace: The name of the database or keyspace formatted as <ycql|ysql|yedis>..
• table_name: The name of the table name.
• table_id: The identifier (ID) of the table.
• flush_timeout_in_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

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.

restore_snapshot

Restores the specified snapshot, including the tables and indexes. When the operation starts, a restoration_id is generated.

Syntax

• 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

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.

For the example above, the restore failed, so the following displays:

Restoration UUID                      State
5a9bc559-2155-4c38-ac8b-b6d0f7aa1af6  FAILED

export_snapshot

Generates a metadata file for the specified snapshot, listing all the relevant internal UUIDs for various objects (table, tablet, etc.).

Syntax

• 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

Exporting snapshot 4963ed18fc1e4f1ba38c8fcf4058b295 (COMPLETE) to file test_tb.snapshot
Snapshot meta data was saved into file: test_tb.snapshot

import_snapshot

Imports the specified snapshot metadata file.

Syntax

• 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

Example

Read snapshot meta file test_tb.snapshot
Importing snapshot 4963ed18fc1e4f1ba38c8fcf4058b295 (COMPLETE)
Target imported table name: ydb.test_tb
Table being imported: ydb.test_tb
Successfully applied snapshot.
Object            Old ID                            New ID
Keyspace          c478ed4f570841489dd973aacf0b3799  c478ed4f570841489dd973aacf0b3799
Table             ff4389ee7a9d47ff897d3cec2f18f720  ff4389ee7a9d47ff897d3cec2f18f720
Tablet 0          cea3aaac2f10460a880b0b4a2a4b652a  cea3aaac2f10460a880b0b4a2a4b652a
Tablet 1          e509cf8eedba410ba3b60c7e9138d479  e509cf8eedba410ba3b60c7e9138d479
Snapshot          4963ed18fc1e4f1ba38c8fcf4058b295  4963ed18fc1e4f1ba38c8fcf4058b295

delete_snapshot

Deletes the specified snapshot.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• snapshot_id: The identifier (ID) of the snapshot.

create_snapshot_schedule

Creates a snapshot schedule. A schedule consists of a list of objects to be included in a snapshot, a time interval at which to back them up, and a retention time.

Returns a schedule ID in JSON format.

Syntax

• 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, Yugabyte recommends setting 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:

{
  "schedule_id": "6eaaa4fb-397f-41e2-a8fe-a93e0c9f5256"
}

list_snapshot_schedules

Lists the snapshots associated with a given schedule. Or, lists all schedules and their associated snapshots.

Returns one or more schedule lists in JSON format.

Schedule list entries contain:

• schedule ID
• schedule options (interval and retention time)
• a list of snapshots that the system has automatically taken

Snapshot list entries include:

• the snapshot's unique ID
• the snapshot's creation time
• the previous snapshot’s creation time, if available. Use this time to make sure that, on restore, you pick the correct snapshot, which is guaranteed to have the data you want to bring back.

Syntax

Where snapshot-id is the snapshot's unique identifier. The ID is optional; omit the ID to return all schedules in the system.

Example

{
  "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"
        }
      ]
    }
  ]
}

restore_snapshot_schedule

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

• 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 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 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:

Restore from a relative time:

In both cases, the output is similar to the following:

{
    "snapshot_id": "f71c265d-4b33-4c71-9fc5-c0acab943ee7",
    "restoration_id": "b1b96d53-f9f9-46c5-b81c-6937301c8eff"
}

---

Multi-zone and multi-region deployment commands

modify_placement_info

Modifies the placement information (cloud, region, and zone) for a deployment.

Syntax

• 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.
• replication_factor: The number of replicas for each tablet. This value should be greater than or equal to the total of replica counts specified in placement_info.
• 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

This will place a minimum of:

1. 2 replicas in aws.us-west.us-west-2a
2. 2 replicas in aws.us-west.us-west-2b
3. 1 replica in aws.us-west.us-west-2c

You can verify the new placement information by running the following curl command:

set_preferred_zones

Sets the preferred availability zones (AZs) and regions.

Syntax

• 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.

Suppose you have a deployment in the following regions: gcp.us-east4.us-east4-b, gcp.asia-northeast1.asia-northeast1-c, and gcp.us-west1.us-west1-c. Looking at the cluster config:

Here is a sample configuration:

replication_info {
  live_replicas {
    num_replicas: 3
    placement_blocks {
      cloud_info {
        placement_cloud: "gcp"
        placement_region: "us-west1"
        placement_zone: "us-west1-c"
      }
      min_num_replicas: 1
    }
    placement_blocks {
      cloud_info {
        placement_cloud: "gcp"
        placement_region: "us-east4"
        placement_zone: "us-east4-b"
      }
      min_num_replicas: 1
    }
    placement_blocks {
      cloud_info {
        placement_cloud: "gcp"
        placement_region: "us-asia-northeast1"
        placement_zone: "us-asia-northeast1-c"
      }
      min_num_replicas: 1
    }
  }
}

The following command sets the preferred zone to gcp.us-west1.us-west1-c:

Verify by running the following.

Looking again at the cluster config you should see affinitized_leaders added:

replication_info {
  live_replicas {
    num_replicas: 3
    placement_blocks {
      cloud_info {
        placement_cloud: "gcp"
        placement_region: "us-west1"
        placement_zone: "us-west1-c"
      }
      min_num_replicas: 1
    }
    placement_blocks {
      cloud_info {
        placement_cloud: "gcp"
        placement_region: "us-east4"
        placement_zone: "us-east4-b"
      }
      min_num_replicas: 1
    }
    placement_blocks {
      cloud_info {
        placement_cloud: "gcp"
        placement_region: "us-asia-northeast1"
        placement_zone: "us-asia-northeast1-c"
      }
      min_num_replicas: 1
    }
  }
  affinitized_leaders {
    placement_cloud: "gcp"
    placement_region: "us-west1"
    placement_zone: "us-west1-c"
  }
}

Master-follower deployment commands

setup_universe_replication

Sets up the universe replication for the specified source universe. Use this command only if no tables have been configured for replication. If tables are already configured for replication, use alter_universe_replication to add more tables.

To verify if any tables are already configured for replication, use list_cdc_streams.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• source_universe_uuid: The UUID of the source universe.
• source_master_addresses: Comma-separated list of the source master addresses.
• comma_separated_list_of_table_ids: Comma-separated list of table identifiers (table_id).
• comma_separated_list_of_producer_bootstrap_ids: Comma-separated list of bootstrap identifiers (bootstrap_id). These are obtained from using bootstrap_cdc_producer.

Example

alter_universe_replication

Changes the universe replication for the specified source universe. Use this command to:

• Add or remove tables in an existing replication UUID
• Modify the source master addresses

If no tables have been configured for replication, use setup_universe_replication.

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:

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• source_universe_uuid: The UUID of the source universe.
• source_master_addresses: Comma-separated list of the source master addresses.

Use the add_table subcommand to add one or more tables to the existing list:

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• source_universe_uuid: The UUID of the source universe.
• comma_separated_list_of_table_ids: Comma-separated list of table identifiers (table_id).
• comma_separated_list_of_producer_bootstrap_ids: Comma-separated list of bootstrap identifiers (bootstrap_id). These are obtained from using bootstrap_cdc_producer.

Use the remove_table subcommand to remove one or more tables from the existing list:

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• source_universe_uuid: The UUID of the source universe.
• comma_separated_list_of_table_ids: Comma-separated list of table identifiers (table_id).

delete_universe_replication <source_universe_uuid>

Deletes universe replication for the specified source universe.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• source_universe_uuid: The UUID of the source universe.

set_universe_replication_enabled

Sets the universe replication to be enabled or disabled.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• source_universe_uuid: The UUID of the source universe.
• 0 | 1: Disabled (0) or enabled (1). Default is 1.

Read replica deployment commands

add_read_replica_placement_info

Add a read replica cluster to the master configuration.

Syntax

• 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.

modify_read_replica_placement_info

Syntax

• 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_read_replica_placement_info

Delete the read replica.

Syntax

• 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.

---

Security commands

Encryption at rest commands

For details on using encryption at rest, see Encryption at rest.

add_universe_keys_to_all_masters

Sets the contents of key_path in-memory on each YB-Master node.

Syntax

• key_id: Universe-unique identifier (can be any string, such as a string of a UUID) that will be associated to the universe key contained in the contents of key_path as a byte[].
• key_path: The path to the file containing the universe key.

all_masters_have_universe_key_in_memory

Checks whether the universe key associated with the provided key_id exists in-memory on each YB-Master node.

• key_id: Universe-unique identifier (can be any string, such as a string of a UUID) that will be associated to the universe key contained in the contents of key_path as a byte[].

rotate_universe_key_in_memory

Rotates the in-memory universe key to start encrypting newly-written data files with the universe key associated with the provided key_id.

• key_id: Universe-unique identifier (can be any string, such as a string of a UUID) that will be associated to the universe key contained in the contents of key_path as a byte[].

disable_encryption_in_memory

Disables the in-memory encryption at rest for newly-written data files.

Syntax

is_encryption_enabled

Checks if cluster-wide encryption is enabled.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is 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

Encryption status: ENABLED with key id <key_id_2>

Change data capture (CDC) commands

create_cdc_stream

Creates a change data capture (CDC) stream for the specified table.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• table_id: The identifier (ID) of the table.

list_cdc_streams

Lists the CDC streams for the specified YB-Master servers.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.

Example

delete_cdc_stream <stream_id> [force_delete]

Deletes underlying CDC stream for the specified YB-Master servers.

Syntax

• 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.

bootstrap_cdc_producer <comma_separated_list_of_table_ids>

Mark a set of tables in preparation for setting up universe level replication.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• comma_separated_list_of_table_ids: Comma-separated list of table identifiers (table_id).

Example

table id: 000030ad000030008000000000004000, CDC bootstrap id: dd5ea73b5d384b2c9ebd6c7b6d05972c

---

Decommissioning commands

get_leader_blacklist_completion

Gets the tablet load move completion percentage for blacklisted nodes.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.

Example

change_blacklist

Changes the blacklist for YB-TServer servers.

After old YB-TServer servers are terminated, you can use this command to clean up the blacklist.

Syntax

• 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.
• ip_addr:port: The IP address and port of the YB-TServer.

Example

change_leader_blacklist

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• ADD or REMOVE: Adds or removes nodes from blacklist.
• ip_addr: The IP address of the node.
• port: The port of the node.

leader_stepdown

Forces the YB-TServer leader of the specified tablet to step down.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.
• tablet_id: The identifier (ID) of the tablet.
• dest_ts_uuid: The destination identifier (UUID) for the new YB-TServer leader. To move leadership from the current leader, when you do not need to specify a new leader, use "" for the value. If you want to transfer leadership intentionally to a specific new leader, then specify the new leader.

---

Rebalancing commands

For information on YB-Master load balancing, see Data placement and load balancing

For YB-Master load balancing flags, see Load balancing flags.

set_load_balancer_enabled

Enables or disables the load balancer.

Syntax

• 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

get_load_balancer_state

Returns the cluster load balancer state.

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.

get_load_move_completion

Checks the percentage completion of the data move.

You can rerun this command periodically until the value reaches 100.0, indicating that the data move has completed.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.

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.

Returns the following percentage:

66.6

get_is_load_balancer_idle

Finds out if the load balancer is idle.

Syntax

• master-addresses: Comma-separated list of YB-Master hosts and ports. Default value is localhost:7100.

Example

---

Upgrade YSQL system catalog

upgrade_ysql

Upgrades the YSQL system catalog after a successful YugabyteDB cluster upgrade. YSQL upgrades are not required for clusters where YSQL is not enabled. Learn more about configuring YSQL flags here.

Syntax

Example

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:

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.

Refer Upgrade a deployment to learn about YB-Master and YB-Tserver upgrades, followed by YSQL system catalog upgrades.