Database Lab Client CLI reference (dblab)
#
DescriptionThe Database Lab Command Line Interface (dblab
) is a tool that allows working with Database Lab instances in the console. This tool is also used to enable working with thin clones in CI/CD pipelines, to run automated tests on full-size database copies.
#
Getting startedBefore you run any commands, install Database Lab CLI and initialize configuration. For more information, see Install and initialize Database Lab CLI.
#
SynopsisUse Database Lab CLI command help
for information on a specific command. The synopsis for each command shows its parameters and their usage. Optional parameters are shown in square brackets.
To list available commands, either run dblab
with no parameters or with flag dblab --help
#
Global options--url
(string) - URL (with protocol and port, if needed) of Database Lab instance's API.The environment variable
DBLAB_INSTANCE_URL
can be used as well. The flag--url
overrides config/env settings.--token
(string) - verification token of Database Lab instance.The environment variable
DBLAB_VERIFICATION_TOKEN
can be used as well. The flag--token
overrides config/env settings.--insecure
,-k
(boolean, default: false) - allow insecure server connections when using SSL.The environment variable
DBLAB_INSECURE_SKIP_VERIFY
can be used as well. The flags--insecure
and-k
override config/env settings.--forwarding-server-url
(string, default: "") - forwarding server URL of Database Lab instance.The environment variable
DBLAB_CLI_FORWARDING_SERVER_URL
can be used as well. The flag--forwarding-server-url
overrides config/env settings.--forwarding-local-port
(string, default: "") - local port for forwarding to the Database Lab instance.The environment variable
DBLAB_CLI_FORWARDING_LOCAL_PORT
can be used as well. The flag--forwarding-local-port
overrides config/env settings.--identity-file
(string, default: "") - select a file from which the identity (private key) for public key authentication is read".The environment variable
DBLAB_CLI_IDENTITY_FILE
can be used as well. The flag--identity-file
overrides config/env settings.--debug
(boolean, default: false) - run CLI in the debug mode.The environment variable
DBLAB_CLI_DEBUG
can be used as well.--help
,-h
(boolean, default: false) - show help.--version
,-v
(boolean, default: false) - print the version.
Examples
tip
If you register a Database Lab instance on the Postgres.ai Platform through the Platform server tunnel, it means that to use Database Lab API and CLI, your users need to be able to reach your infrastructure somehow. Consider use of VPN or custom SSH port forwarding.
#
Command Overviewinit
#
Command: Initialize a working directory containing Database Lab configuration files. This is the first command that should be run before managing clones or changing the Database Lab configuration.
It is safe to run this command multiple times.
Usage
Options
--environment-id
(string, required) - an arbitrary environment ID of Database Lab instance's API--url
(string, required) - URL of Database Lab instance's API--token
(string, required) - verification token of Database Lab instance--insecure
(boolean, optional, default: false) - allow insecure server connections when using SSL--forwarding-server-url
(string, optional) - forwarding server URL of Database Lab instance. For example:ssh://[email protected]:22
--forwarding-local-port
(string, optional) - local port for forwarding to the Database Lab instance--identity-file
(string, optional) - select a file from which the identity (private key) for public key authentication is read"
Example
port-forward
#
Command: Start port forwarding to the Database Lab instance.
Usage
Global options
--forwarding-server-url
(string, optional) - forwarding server URL of Database Lab instance. For example:ssh://[email protected]:22
--forwarding-local-port
(string, optional) - local port for forwarding to the Database Lab instance--identity-file
(string, optional) - a path to a file from which the identity (private key) for public key authentication is read
Example
clone
#
Command: Manage Database Lab clones.
Usage
Subcommands
list
- list all existing clonesstatus
- display clone's informationcreate
- create new cloneupdate
- update existing clonereset
- reset clone's statedestroy
- destroy cloneport-forward
- start port forwardinghelp
,h
- shows a list of commands or help for one command
list
#
Subcommand List all existing clones.
Usage
status
#
Subcommand Display the clone's information.
Usage
Arguments
CLONE_ID
(string, required) - an ID of the Database Lab clone to display information
create
#
Subcommand Create a new clone. Usage
Options
--username
(string, required) - database username--password
(string, required) - database password--id
(string, optional) - clone ID--snapshot-id
(string, optional) - snapshot ID--protected
,-p
(boolean, default: false) - mark instance as protected from deletion--restricted
(boolean, default: false) - use database user with restricted permissions (not a superuser, DML and DDL allowed,CREATE EXTENSION
is not allowed)--async
,-a
(boolean, default: false) - run the command asynchronously--extra-config
(string, optional) set an extra database configuration for the clone. An example: statement_timeout='1s'--help
,-h
(boolean, default: false) - show help
Example
update
#
Subcommand Update the specified clone.
Usage
Arguments
CLONE_ID
(string, required) - an ID of the Database Lab clone to update parameters
Options
--protected
,-p
(boolean, optional) - mark instance as protected from deletion--help
,-h
(boolean, default: false) - show help
Example
reset
#
Subcommand Reset the clone's state.
Usage
Arguments
CLONE_ID
(string, required) - an ID of the Database Lab clone to reset state
Options
--async
,-a
(boolean, default: false) - run the command asynchronously--help
,-h
(boolean, default: false) - show help
Example
destroy
#
Subcommand Destroy the specified clone.
Usage
Arguments
CLONE_ID
(string, required) - an ID of the Database Lab clone to destroy.
Options
--async
,-a
(boolean, default: false) - run the command asynchronously.--help
,-h
(boolean, default: false) - show help.
Example
start-observation
#
Subcommand 🚧 Experimental
This is an experimental feature (its working title: "CI Observer"). If you have questions, suggestions, or bug reports, please open an issue in the Database Lab Engine issue tracker and/or raise a discussion in one of the Database Lab Community channels.
Start clone state monitoring.
The command runs the clone observation session and estimates results by defined criteria such as lock duration and whole session duration.
To get results, it is necessary to stop the observation session using the stop-observation
command.
Usage
Arguments
CLONE_ID
(string, required) - an ID of the Database Lab clone to destroy.
Options
--observation-interval
(integer, default: 0) - interval of metric gathering and output (in seconds). The environment variableDBLAB_OBSERVATION_INTERVAL
.--max-lock-duration
(integer, default: 0) - maximum allowed duration for locks (in seconds). The environment variableDBLAB_MAX_LOCK_DURATION
.--max-duration
(integer, default: 0) - maximum allowed duration for observation (in seconds). The environment variableDBLAB_MAX_DURATION
.--tags
(string, optional) - set tags for the observation session. An example: branch=patch-1.--help
,-h
(boolean, default: false) - show help.
Example
stop-observation
#
Subcommand 🚧 Experimental Summarize clone monitoring session and check results.
Usage
Arguments
CLONE_ID
(string, required) - an ID of the Database Lab clone to destroy.
Options
--help
,-h
(boolean, default: false) - show help.
Example
port-forward
#
Subcommand Start port forwarding to clone.
Usage
Arguments
CLONE_ID
(string, required) - an ID of the Database Lab clone for port forwarding.
Global options
--forwarding-server-url
(string, optional) - forwarding server URL of Database Lab instance. For example:ssh://[email protected]:22
--forwarding-local-port
(string, optional) - local port for forwarding to the Database Lab instance--identity-file
(string, optional) - a path to a file from which the identity (private key) for public key authentication is read
Example
help
, h
#
Subcommand Show help for the specified command.
Usage
instance
#
Command: Display the instance information.
Usage
Subcommands
status
- display instance's statusversion
- display instance's versionhelp
,h
- shows a list of commands or help for one command
status
#
Subcommand Get the status of the instance we are working with.
Usage
version
#
Subcommand Get the version of the instance we are working with.
Usage
help
, h
#
Subcommand Show help for the command.
Usage
snapshot
#
Command: Manage snapshots.
Usage
Subcommands
list
- list all existing snapshots.help
,h
- shows a list of commands or help for one command.
list
#
Subcommand Get the list of snapshots.
Usage
help
, h
#
Subcommand Show help for the command.
Usage
config
#
Command: Configure CLI environments.
Usage
Subcommands
create
- create new CLI environmentupdate
- update an existing CLI environmentview
- view status of CLI environmentlist
- display list of all available CLI environmentsswitch
- switch to another CLI environmentremove
- remove CLI environmenthelp
,h
- shows a list of commands or help for one command
create
#
Subcommand Create a new CLI environment.
Usage
Arguments
ENVIRONMENT_ID
(string, required) - an ID of the Database Lab CLI environment to create.
Options
--url
(string, required) - URL of Database Lab instance's API--token
(string, required) - verification token of Database Lab instance--insecure
(boolean, optional) - allow insecure server connections when using SSL--forwarding-server-url
(string, optional) - forwarding server URL of Database Lab instance. For example,ssh://[email protected]:22
--forwarding-local-port
(string, optional) - local port for forwarding to the Database Lab instance--identity-file
(string, optional) - a path to a file from which the identity (private key) for public key authentication is read
Example
update
#
Subcommand Update an existing CLI environment.
Usage
Arguments
ENVIRONMENT_ID
(string, required) - an ID of the Database Lab CLI environment to update
Options
--url
(string) - URL of Database Lab instance's API--token
(string) - verification token of Database Lab instance--insecure
(boolean, optional) - allow insecure server connections when using SSL--forwarding-server-url
(string, optional) - forwarding server URL of Database Lab instance. For example,ssh://[email protected]:22
--forwarding-local-port
(string, optional) - local port for forwarding to the Database Lab instance--identity-file
(string, optional) - a path to a file from which the identity (private key) for public key authentication is read
Example
view
#
Subcommand Display status of CLI environment.
Usage
Arguments
ENVIRONMENT_ID
(string) - an ID of the Database Lab CLI environment to view. By default, the current environment will be shown
list
#
Subcommand Display list of all available CLI environments.
Usage
switch
#
Subcommand Switch to another CLI environment.
Usage
Arguments
ENVIRONMENT_ID
(string, required) - an ID of the Database Lab CLI environment to switch
remove
#
Subcommand Remove CLI environment.
Usage
Arguments
ENVIRONMENT_ID
(string, required) - an ID of the Database Lab CLI environment to remove
help
, h
#
Subcommand Show help for the command.
Usage
help
#
Command: Show help for the Client CLI subcommands.
Usage
Subcommands
init
- initialize Database Lab CLIport-forward
- start port forwarding to the Database Lab instanceclone
- manage clonesinstance
- display instance infosnapshot
- manage snapshotsconfig
- configure CLI environmentshelp
,h
- show a list of commands or help for one command