YugabyteDB Client API
YugabyteDB Client API provides high level API operations and command line interface for YugabyteDB RPC.
Command line interface is very roughly modelled after the yb-admin
tool.
Usage
go run ./main.go [command] [flags]
Common flags
--master
: string, repeated, host port of the master to query, default127.0.0.1:7100, 127.0.0.1:7101, 127.0.0.1:7102
--operation-timeout
: RPC operation timeout, duration string (5s
,1m
, ...), default60s
--tls-ca-cert-file-path
: full path to the CA certificate file, defaultempty string
--tls-cert-file-path
: full path to the certificate file, defaultempty string
--tls-key-file-path
: full path to the key file, defaultempty string
Logging flags:
--log-level
: log level, defaultinfo
--log-as-json
: log entries as JSON, defaultfalse
--log-color
: log colored output, defaultfalse
--log-force-color
: force colored output, defaultfalse
Commands
- Universe and cluster commands
- Table commands
- Backup and snapshot commands
- Multi-zone and multi-region deployment commands
- Change data capture (CDC) commands
- Decommissioning commands
- Rebalancing commands
- Other commands
Universe and cluster commands
get-universe-config
Get the placement info and blacklist info of the universe.
change-config
TODO: track.
change-master-config
TODO: track.
list-tablet-servers
List all the tablet servers in this database.
--primary-only
: boolean, list primary tablet servers only, defaultfalse
list-masters
List all the masters in this database.
list-replica-type-counts
TODO: track.
dump-masters-state
TODO: track.
list-tablets-for-table-server
TODO: track.
split-tablet
TODO: track.
master-leader-stepdown
Try to force the current master leader to step down.
ysql-catalog-version
Fetch current YSQL catalog version.
Table commands
list-tables
List all tables in this database.
--name-filter
: string, When used, only returns tables that satisfy a substring match onname_filter
, defaultempty string
--keyspace
: string, the namespace name to fetch info, defaultempty string
--exclude-system-tables
: boolean, exclude system tables, defaultfalse
--include-not-running
: boolean, include not running, defaultfalse
--relation-type
: list of strings, filter tables based on RelationType - supported values:system_table
,user_table
,index_table
, default: all values
Examples:
- list all PostgreSQL
system_platform
relations:cli list-tables --keyspace ysql.system_platform
- list all PostgreSQL
postgres
relations:cli list-tables --keyspace ysql.postgres
- list all PostgreSQL
yugabyte
relations:cli list-tables --keyspace ysql.yugabyte
- list all PostgreSQL
template0
relations:cli list-tables --keyspace ysql.template0
- list all CQL
system_schema
relations:cli list-tables --keyspace ycql.system_schema
- list all Redis
system_redis
relations:cli list-tables --keyspace yedis.system_redis
compact-table
TODO: requires an issue.
modify-table-placement-info
TODO: requires an issue.
Backup and snapshot commands
create-snapshot
Creates a snapshot of an entire keyspace or selected tables in a keyspace.
--keyspace
: string, keyspace name to create snapshot of, default<empty string>
--name
: repeated string, table name to create snapshot of, defaultempty list
--uuid
: repeated string, table ID to create snapshot of, defaultempty list
--schedule-id
: base64 encoded, create snapshot to this schedule, other fields are ignored, defaultempty
--base64-encoded
: boolean, base64 decode given schedule ID before handling over to the API, defaultfalse
Remarks:
- Multiple
--name
and--uuid
values can be combined together. - YSQL keyspace snapshots do not support explicit
--name
and--uuid
selection. - To create a snapshot of an entire keyspace, do not specify any
--name
or--uuid
. YCQL only. yedis.*
keyspaces are not supported.
Examples:
- create a snapshot of an entire YSQL
yugabyte
database:cli create-snapshot --keyspace ysql.yugabyte
- create a snapshot of selected YCQL tables in the
example
database:cli create-snapshot --keyspace ycql.example --name table
delete-snapshot
Delete a snapshot.
--snapshot-id
: string, snapshot identifier - literal ID or Base64 encoded value from YugabyteDB RPC API, required, defaultempty string
(not defined)
list-snapshots
List snapshots.
--snapshot-id
: string, snapshot identifier - literal ID or Base64 encoded value from YugabyteDB RPC API, optional, defaultempty string
(not defined)--list-deleted-snapshots
: boolean, list deleted snapshots, defaultfalse
--prepare-for-backup
: boolean, prepare for backup, defaultfalse
list-snapshot-restorations
List snapshot restorations.
--schedule-id
: string, snapshot identifier - literal ID or Base64 encoded value from YugabyteDB RPC API, optional, defaultempty string
(not defined)--restoration-id
: string, restoration identifier - literal ID or Base64 encoded value from YugabyteDB RPC API, optional, defaultempty string
(not defined)
export-snapshot
Export a snapshot.
--snapshot-id
: string, snapshot identifier- literal ID or Base64 encoded value from YugabyteDB RPC API, required, defaultempty string
(not defined)--file-path
: string, full path to the export file, parent directories must exist, defaultempty
import-snapshot
Import a snapshot.
--file-path
: string, full path to the exported snapshot file--keyspace
: string, fully qualified keyspace name, for exampleycql.system_namespace
, no effect for YSQL imports, defaultempty
--table-name
: string, repeated, table name to import, no effect for YSQL snapshots, defaultempty list
restore-snapshot
Restore a snapshot.
--schedule-id
: string, schedule identifier - literal ID or Base64 encoded value from YugabyteDB RPC API, required, defaultempty string
(not defined)--restore-target
: exact past HT (16 digit literal
) or duration expression (1h
,5h15m
, ...), absolute Timing Option: Max HybridTime, or relative past interval, defaultempty
(undefined)
create-snapshot-schedule
Create a new snapshot schedule.
--keyspace
: string, keyspace name to create snapshot of, default<empty string>
--interval
: duration expression (1h
,1d
, ...), interval for taking snapshot in seconds, default0
(undefined)--retention-duration
: duration expression (1h
,1d
, ...), how long store snapshots in seconds, default0
(undefined)--delete-after
: exact future HT (16 digit literal
) or duration expression (1h
,5h15m
, ...), how long until schedule is removed in seconds, hybrid time will be calculated by fetching server hybrid time and adding this value, default0
(undefined)
Examples:
- create a snapshot schedule of an entire YSQL
yugabyte
database:cli create-snapshot-schedule --keyspace ysql.yugabyte --interval 1h --retention-duration 2h --delete-after 1h
- create a snapshot schedule of selected YSQL tables in the
yugabyte
database:cli create-snapshot-schedule --keyspace ysql.yugabyte --name table --name another-table
delete-snapshot-schedule
Delete a snapshot schedule.
--schedule-id
: string, snapshot identifier - literal ID or Base64 encoded value from YugabyteDB RPC API, required, defaultempty string
(not defined)
list-snapshot-schedules
List snapshot schedules.
--schedule-id
: string, snapshot identifier - literal ID or Base64 encoded value from YugabyteDB RPC API, optional, defaultempty string
(not defined)
restore-snapshot-schedule
Restore a snapshot schedule.
--snapshot-id
: string, snapshot identifier - literal ID or Base64 encoded value from YugabyteDB RPC API, required, defaultempty string
(not defined)--restore-target
: exact past HT (16 digit literal
) or duration expression (1h
,5h15m
, ...), absolute Timing Option: Max HybridTime, or relative past interval, defaultempty
(undefined)
Multi-zone and multi-region deployment commands
modify-placement-info
Modifies the placement information (cloud, region, and zone) for a deployment.
--placement-info
: string, repeated, placement for cloud.region.zone, default cluster value iscloud1.datacenter1.rack1
, defaultempty
, at least one required--replication-factor
: uint32, the number of replicas for each tablet, default0
(must be explicitly specified)--placement-uuid
: string, the identifier of the primary cluster, which can be any unique string, optional, if not set, a randomly-generated ID will be used, defaultnot set
set-preferred-zones
Sets the preferred availability zones (AZs) and regions.
--zone-info
: string, repeated, specifies the cloud, region, and zone, defaultempty
Change data capture (CDC) commands
create-cdc-stream
TODO: track.
delete-cdc-stream
TODO: track.
list-cdc-streams
TODO: track.
Decommissioning commands
get-leader-blacklist-completion
TODO: track.
change-blacklist
TODO: track.
change-leader-blacklist
TODO: track.
leader-stepdown
--destination-uuid
: UUID of server this request is addressed to, defaultempty
- not specified--disable-graceful-transition
: boolean, ifnew-leader-uuid
is not specified, the current leader will attempt to gracefully transfer leadership to another peer; setting this flag disables that behavior, defaultfalse
--new-leader-uuid
: UUID of the server that should run the election to become the new leader, defaultempty
- not specified--tablet-id
: the id of the tablet, defaultempty
- not specified
Rebalancing commands
set-load-balancer-state
Options are mutually exclusive, exactly one has to be set:
--enabled
: boolean, defaultfalse
, new desired state: enabled--disabled
: boolean, defaultfalse
, new desired state: disabled
get-load-balancer-idle
Finds out if the load balancer is idle.
get-load-move-completion
Get the completion percentage of tablet load move from blacklisted servers.
is-load-balanced
Check if master leader thinks that the load is balanced across TServers.
--expected-num-servers
: int32, how many servers to include in this check, default-1
(undefined
)
Other commands
check-exists
Check that a table exists.
--keyspace
: string, keyspace name to check in, default<empty string>
--name
: string, table name to check for, default<empty string>
--uuid
: string, table identified (uuid) to check for, default<empty string>
describe-table
Info on a table in this database.
--keyspace
: string, keyspace name to check in, default<empty string>
, ignored when using--uuid
--name
: string, table name to check for, default<empty string>
--uuid
: string, table identified (uuid) to check for, default<empty string>
Examples:
- describe table
test
in theyugabyte
database:cli describe-table --keyspace yugabyte --name test
- describe table with ID
000033c0000030008000000000004000
:cli describe-table --uuid 000033c0000030008000000000004000
get-master-registration
Get master registration info.
get-tablets-for-table
Fetch tablet information for a given table.
--keyspace
: string, keyspace to describe the table in, defaultempty string
--name
: string, table name to check for, defaultempty string
--uuid
: string, table identifier to check for, defaultempty string
--partition-key-start
: base64 encoded, partition key range start, defaultempty
--partition-key-end
: base64 encoded, partition key range end, defaultempty
--max-returned-locations
: uint32, maximum number of returned locations, default10
--require-tablet-running
: boolean, require tablet running, defaultfalse
is-server-ready
Check if server is ready to serve IO requests.
--host
: string, host to check, default<empty string>
--port
: int, port to check, default0
, must be higher than0
--is-tserver
: boolean, whentrue
- indicated a TServer, defaultfalse
ping
Ping a certain YB server.
--host
: string, host to ping, default<empty string>
--port
: int, port to ping, default0
, must be higher than0
Minimal YugabyteDB cluster in Docker compose
This repository contains a minimal YugabyteDB Docker compose setup which can be used for client testing or validation.
To start the cluster:
cd .compose/
docker compose -f yugabytedb-minimal.yml up
To restart:
docker compose -f yugabytedb-minimal.yml rm
docker compose -f yugabytedb-minimal.yml up
Docker image
Build the Docker image:
make docker-image
Run against the provided minimal YugabyteDB cluster:
docker run --rm \
--net yb-client-minimal \
-ti local/ybdb-go-cli:0.0.1 \
list-masters --master yb-master-1:7100 \
--master yb-master-2:7100 \
--master yb-master-3:7100