Database Lab Client CLI reference (dblab)

Description

The 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 started

Before you run any commands, install Database Lab CLI and initialize configuration. For more information, see Install and initialize Database Lab CLI.

Synopsis

dblab [global options] command [command options] [arguments...]

Use 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

dblab --url "127.0.0.1:2345" --token "SECRET_TOKEN" --insecure clone list
DBLAB_INSTANCE_URL="example.com" DBLAB_VERIFICATION_TOKEN="SECRET_TOKEN" dblab clone list
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 Overview

COMMANDS:
init initialize Database Lab CLI.
port-forward start port forwarding to the Database Lab instance.
clone manages clones.
instance displays instance info.
snapshot manage snapshots.
config configure CLI environments.
help, h shows a list of commands or help for one command.

Command: init

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

dblab init [command options] [arguments...]

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

dblab init --environment-id dev --url "http://127.0.0.1:2345" --token "SECRET_TOKEN" --insecure

Command: port-forward

Start port forwarding to the Database Lab instance.

Usage

dblab [global options] port-forward

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

dblab --forwarding-server-url "ssh://[email protected]:22" --forwarding-local-port 8888 port-forward

Command: clone

Manage Database Lab clones.

Usage

dblab clone command [command options] [arguments...]

Subcommands

  • list - list all existing clones
  • status - display clone's information
  • create - create new clone
  • update - update existing clone
  • reset - reset clone's state
  • destroy - destroy clone
  • port-forward - start port forwarding
  • help , h - shows a list of commands or help for one command

Subcommand list

List all existing clones.

Usage

dblab clone list

Subcommand status

Display the clone's information.

Usage

dblab clone status CLONE_ID

Arguments

  • CLONE_ID (string, required) - an ID of the Database Lab clone to display information

Subcommand create

Create a new clone. Usage

dblab clone create [command options]

Options

  • --username (string, required) - database username
  • --password (string, required) - database password
  • --id (string, optional) - clone ID
  • --snapshot-id (string, optional) - snapshot ID
  • --project (string, default: "") - project name
  • --protected , -p (boolean, default: false) - mark instance as protected from deletion
  • --async , -a (boolean, default: false) - run the command asynchronously
  • --help , -h (boolean, default: false) - show help

Example

dblab clone create --username someuser --password somepassword

Subcommand update

Update the specified clone.

Usage

dblab clone update [command options] CLONE_ID

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

dblab clone update --name newName --protected TestCloneID

Subcommand reset

Reset the clone's state.

Usage

dblab clone reset [command options] CLONE_ID

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

dblab clone reset TestCloneID

Subcommand destroy

Destroy the specified clone.

Usage

dblab clone destroy [command options] CLONE_ID

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

dblab clone destroy TestCloneID

Subcommand port-forward

Start port forwarding to clone.

Usage

dblab [global options] clone port-forward CLONE_ID

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

dblab \
--forwarding-server-url "ssh://[email protected]:22" \
--forwarding-local-port 8888 \
clone port-forward TestCloneID

Subcommand help , h

Show help for the specified command.

Usage

dblab clone help

Command: instance

Display the instance information.

Usage

dblab instance command [command options] [arguments...]

Subcommands

  • status - display instance's status
  • help , h - shows a list of commands or help for one command

Subcommand status

Get the status of the instance we are working with.

Usage

dblab instance status

Subcommand help , h

Show help for the command.

Usage

dblab instance help

Command: snapshot

Manage snapshots.

Usage

dblab snapshot command [command options] [arguments...]

Subcommands

  • list - list all existing snapshots.
  • help , h - shows a list of commands or help for one command.

Subcommand list

Get the list of snapshots.

Usage

dblab snapshot list

Subcommand help , h

Show help for the command.

Usage

dblab snapshot help

Command: config

Configure CLI environments.

Usage

dblab config command [command options] [arguments...]

Subcommands

  • create - create new CLI environment
  • update - update an existing CLI environment
  • view - view status of CLI environment
  • list - display list of all available CLI environments
  • switch - switch to another CLI environment
  • remove - remove CLI environment
  • help , h - shows a list of commands or help for one command

Subcommand create

Create a new CLI environment.

Usage

dblab config create [command options] ENVIRONMENT_ID

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

dblab config create --url "http://127.0.0.1:2345" --token SECRET_TOKEN --insecure=true dev

Subcommand update

Update an existing CLI environment.

Usage

dblab config update [command options] ENVIRONMENT_ID

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

dblab config update --url "http://127.0.0.1:2345" --token SECRET_TOKEN --insecure=true dev

Subcommand view

Display status of CLI environment.

Usage

dblab config view [ENVIRONMENT_ID]

Arguments

  • ENVIRONMENT_ID (string) - an ID of the Database Lab CLI environment to view. By default, the current environment will be shown

Subcommand list

Display list of all available CLI environments.

Usage

dblab config list

Subcommand switch

Switch to another CLI environment.

Usage

dblab config switch ENVIRONMENT_ID

Arguments

  • ENVIRONMENT_ID (string, required) - an ID of the Database Lab CLI environment to switch

Subcommand remove

Remove CLI environment.

Usage

dblab config remove ENVIRONMENT_ID

Arguments

  • ENVIRONMENT_ID (string, required) - an ID of the Database Lab CLI environment to remove

Subcommand help , h

Show help for the command.

Usage

dblab config help

Command: help

Show help for the Client CLI subcommands.

Usage

dblab help command [command options] [arguments...]

Subcommands

  • init - initialize Database Lab CLI
  • port-forward - start port forwarding to the Database Lab instance
  • clone - manage clones
  • instance - display instance info
  • snapshot - manage snapshots
  • config - configure CLI environments
  • help , h - show a list of commands or help for one command
Edit this page