Using the BigAnimal CLI

Use the command line interface (CLI) for BigAnimal management activities such as cluster provisioning and getting cluster status from your terminal. The CLI is an efficient way to integrate with BigAnimal and enables system administrators and developers to script and automate the BigAnimal administrative operations.

Installing the CLI

The CLI is available for Linux, MacOS, and Windows operating systems.

Download the binary executable

  • For Linux operating systems, use the following command to get the latest version of the binary executable:

    curl -LO "https://cli.biganimal.com/download/$(uname -s)/$(uname -m)/latest/biganimal"
  • For all operating systems, download the executable binary here. After downloading, move the binary executable under a directory on your executable search path.

(Optional) Validate the download

  • For Linux users:

    1. Copy the SHA256 checksum code for Linux distribution from the BigAnimal CLI page and store it as a local file such as biganimal_linux_amd64.sha256. Alternatively, click on the SHA256 code to download it as a file directly and verify the content of the downloaded file is identical to the checksum code showed on the page.
    2. From your local shell, validate the binary executable file against the checksum file:
      echo "$(<biganimal_linux_amd64.sha256) biganimal" | sha256sum --check
  • For Windows users:

    1. Download the SHA256 checksum code for Windows distribution from the BigAnimal CLI page and store it as a local file such as biganimal_windows_amd64.sha256. Alternatively, click on the SHA256 code to download it as a file directly and verify the content of the downloaded file is identical to the checksum code showed on the page.
    2. Validate the binary executable file against the checksum file using CertUtil:
      CertUtil -hashfile biganimal.exe SHA256 type biganiml_windows_amd64.sha256
  • For MacOS users:

    1. Download the SHA256 checksum code for MacOS distribution from the BigAnimal CLI page and store it as a local file such as biganimal_darwin_amd64.sha256. Alternatively, click on the SHA256 code to download it as a file directly and verify the content of the downloaded file is identical to the checksum code showed on the page.
    2. From MacOS terminal, validate the binary executable file against the checksum file:
      echo "$(<biganimal_darwin_amd64.sha256)  biganimal" | shasum -a256 -c

Make the CLI command executable within Cloud Shell

Change the permissions of the CLI to make it executable within Cloud Shell:

chmod +x biganimal

Authenticate as a valid user

Before using the CLI to manage BigAnimal, you need to authenticate as a valid BigAnimal user. Use the create-credential command to authenticate through the BigAnimal website and assign a refresh token and an access token to a local credential. For example:

biganimal create-credential \
  --name ba-user1 \
  --address portal.biganimal.com \
  --port 443
Output
Querying Authentication Endpoint for 'portal.biganimal.com
First, copy your one-time code:
         CWWG-SMXC
Then visit: https://auth.biganimal.com/activate
press [Enter] to continue in the web browser...

Credential "ba-user1" created!

Refresh tokens expire after 30 days. To continue using the credential to access the CLI, use the reset-credential command to authenticate through the BigAnimal website and receive a new refresh token.

biganimal reset-credential ba-user1
Output
Visit this URL to login: https://auth.biganimal.com/activate?user_code=****-****
or press [Enter] to continue in the web browser 

Credential "ba-user1" reset operation succeeded

You can create multiple credentials for different BigAnimal accounts and then set one as context of your current management session. Use show-credentials to list all available credentials and use config set context_credential to set a default credential for the current context. For example:

biganimal show-credentials
Output
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Credentials                                                             ┃
┣━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃ name     ┃ address                     ┃ port ┃  context credential     ┃
┃━━━━━━━━━━┃━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┃━━━━━━┃━━━━━━━━━━━━━━━━━━━━━━━━━┃
┃ ba-user1 ┃ portal.biganimal.com        ┃ 443  ┃ x                       ┃
┃ ba-user2 ┃ portal.biganimal.com        ┃ 443  ┃                         ┃
┗━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━┛
The credential ba-user1 has been set up
biganimal config set context_credential ba-user1
Note

If you are a free trial account user, add the --free-trial flag in the create-credential command.

Configuring

The initial running of the CLI creates a hidden configuration folder in your user root directory. For example, for Linux it’s ${HOME}/.edb-cli. The CLI persists the configuration file in this directory as well as the credentials.

Don’t edit files in this directory directly. Instead, use the config subcommand to list and update the configuration settings of the CLI. Use the following command to get detailed usage and available configurations information:

biganimal config

Available configuration settings

SettingDescription
context_credentialThe default credential used in the following commands.
output_modeThe command line output format: table, json, xml, or yaml.
confirm_modeIf enabled, create/update/delete commands require user confirmation.
interactive_modeIf enabled, CLI prompts for missing flags and available options. See Interactive mode for more information.
check_update_modeIf enabled, CLI detects new updates automatically and prompts for download.
warning_modeIf enabled, CLI displays warning messages.

Usability features

Online command reference and help

Use the -h or --help flags for more information on the CLI commands. You can use these flags on the biganimal command to get a listing of all the available subcommands (biganimal -h) or on a subcommand to get information on that particular command (for example, biganimal create-cluster -h).

Auto completion

You can enable command line auto completion for bash, fish, powershell, and zsh. To set up auto completion:

biganimal completion

Interactive mode

In interactive mode, the CLI prompts you for any missing mandatory flags and lists any available options for your current context. To enable interactive mode:

biganimal config set interactive_mode on

Sample use cases

These examples show Azure as the cloud provider unless indicated otherwise. The functionality is the same when using AWS.

Create a cluster in interactive mode

The default mode for the create-cluster command is an interactive mode that guides you through the required cluster configuration by providing you with the valid values.

Tip

You can turn off prompting using the biganimal config set interactive_mode off command. With prompting disabled, if there are any missing required flags, the CLI exits with an error.

biganimal create-cluster
Output
Cluster architecture: High Availability
Number of standby replicas: 2 Replicas
Enable read-only workloads: No
Provider: Azure
Cluster Name: my-biganimal-cluster
Password: ****************
PostgreSQL type: Oracle Compatible
PostgreSQL version: 14
Region: (US) East US
Instance type: E2s v3(2vCPU, 16GB RAM)
Volume type: Azure Premium Storage
Volume properties: P1 (4 Gi, 120 Provisioned IOPS, 25 Provisioned MB/s)
Networking: Public
By default your cluster allows all inbound communications, add IP allowed list to restrict the access: Yes
Add CIDR blocks "192.168.1.1/16=Sample Description" leave empty to stop adding: 
Add database config in the format "application_name=sample_app&array_nulls=true", Leave empty for default configuration: 
Backup Retention Period, note backups will incur storage charges from the cloud provider directly. e.g. "7d", "2w" or "3m": 30d
 

You are prompted to confirm you want to create the cluster. After the cluster creation process is completed, it generates a cluster ID.

biganimal create-cluster
Output
........
Are you sure you want to Create Cluster ? [y|n]: y
Create Cluster operation is started
Cluster ID is "p-gxhkfww1fe"
To check current state, run: biganimal show-clusters --id p-gxhkfww1fe

Check your cluster was created successfully using the show-clusters command shown in the return message:

biganimal show-clusters --id p-gxhkfww1fe
Output
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────------───────────────────┐
│ Clusters                                                                                                                                          │
├──────────────┬──────────────────────┬────────────────────------┬──────────┬──────────────┬───────-───────┬──────────────────────────────┬─────────┤
│ ID           │ Name                 │ Status                   │ Provider │ Region       │ Instance Type │ Postgres Type                │ Version │
├──────────────┼──────────────────────┼─────────────────------───┼──────────┼──────────────┼───────────────┼──────────────────────────────┼─────────┤
│ p-gxhkfww1fe │ my-biganimal-cluster │ Cluster in healthy state │ Azure    │ (US) East US │ E2s v3        │ Oracle Compatible            │ 14      │
└──────────────┴──────────────────-───┴──────────────────------──┴──────────┴──────────────┴───────────────┴──────────────────────────────┴─────────┘

Create a cluster using a configuration file

You can use the --clusterConfigFile command to create one or more clusters with the same configuration in a noninteractive mode.

Here is a sample configuration file in YAML format with Azure specified as the provider:

  # config_file.yaml
  ---
  clusterArchitecture: ha                     # <string:  cluster architecture, valid values ["single" | "ha" | "eha"]>
  haStandbyReplicas: 2                        # <number:  Number of standby replicas. Field must be specified if user has selected high availability cluster type. Default value is 2, valid values [1, 2].>
  provider: azure                             # <string:  cloud provider id>
  clusterName: my-biganimal-cluster           # <string:  cluster name>
  password: ************                      # <string:  cluster password (must be at least 12 characters)>
  iamAuthentication: false                    # <bool:    Identity and Access Management, enabling IAM authentication will allow database users to authenticate to Postgres using your cloud provider's IAM(currently supported only for AWS). You can set up IAM authentication after your cluster is provisioned.>
  postgresType: epas                          # <string:  postgresType id, valid values ["postgres" | "epas" | "pgextended"]>
  postgresVersion: "14"                       # <string:  postgres version>
  region: eastus                              # <string:  provider region id>
  instanceType: azure:Standard_E2s_v3         # <string:  instance type id>
  volumeType: azurepremiumstorage             # <string:  volume type id>
  volumeProperties: P1                        # <string:  Applicable to Azure only, volume properties id>
  volumePropertySize: "4Gi"                   # <string:  Applicable to AWS gp3 only and Azure Ultradisk, volume size in Byte, you may append unit suffix 'Gi' or 'G'.>
  volumePropertyIOPS: 3000                    # <number>: Applicable to AWS gp3 and Azure Ultradisk, volume Input/Output Operations Per Second> 
  networking: public                          # <string:  input "private" or "public" network>
  allowIpRangeMap:                            # <list:    IP Range to allow network traffic to your cluster from the public Internet>
    - cidr: 9.9.9.9/28                        # <string:  CIDR of allowed source IP range>
      description: Allow traffic from App A   # <string:  The description of this allowed ip range>
    - cidr: 10.10.10.10/27                    # <string:  CIDR of allowed source IP range>
      description: Allow traffic from App B   # <string:  The description of this allowed ip range>
  pgConfigMap:                                # <Object:  Postgres configuration>
    application_name: test_app                # <string:  set the database "application_name" property to "test_app">
    array_nulls: true                         # <bool:    set the database "array_nulls" property to True>
  backupRetentionPeriod: 30d                  # <string:  Use strings like “7d“ or “2w“ or “3m” to specify days (1-180), weeks (1-25) or months (1-6) to set retention period>
  readOnlyWorkloads:                          # <bool:    Set True to enable read-only connection and route all read-only queries to standby replicas and reduce the workload on primary>
  ---
Note

For backward compatibility, allowIpRangeMap and pgConfigMap properties also support embedded JSON format.

allowIpRangeMap: [["9.9.9.9/28", "Allow traffic from App A"],["10.10.10.10/27", "Allow traffic from App B"]]
pgConfigMap: [["application_name","test_app"],["array_nulls","true"]] 

To create the cluster using the sample configuration file config_file.yaml:

biganimal create-cluster --clusterConfigFile ./config_file.yaml

To query an enumeration of valid values for above BigAnimal and cloud service provider related properties, CLI provides you a series of subcommands, for example: you can use show-cluster-architecture to list all available cloud architecture to your current login account.

biganimal show-cluster-architectures
Output
┌──────────────────────────────────────────────┐
│ Architecture                                 │
├────────┬───────────────────────────┬─────────┤
│ ID     │ Name                      │ Status  │
├────────┼───────────────────────────┼─────────┤
│ eha    │ Extreme High Availability │ enabled │
│ ha     │ High Availability         │ enabled │
│ single │ Single Node               │ enabled │
└────────┴───────────────────────────┴─────────┘
Note

"Extreme High Availability" architecture is not enabled by default, to get access to this offering, contact your sales representative or Support.

For more information

Tip

You can turn off the confirmation step with the biganimal disable-confirm command.

Get cluster connection information

To use your BigAnimal cluster, you first need to get your cluster's connection information. To get your cluster's connection information, use the show-cluster-connection command:

biganimal show-cluster-connection \
  --name my-biganimal-cluster \
  --provider azure \
  --region eastus
Output
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Connection String                                                                              ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃ postgres://edb_admin@p-gxhkfww1fe.30glixgayvwhtmn3.biganimal.io:5432/edb_admin?sslmode=require ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
Tip

You can query the complete connection information with other output formats, like JSON or YAML. For example:

biganimal show-cluster-connection \
  --name my-biganimal-cluster \
  --provider azure \
  --region eastus \
  --output json

Update cluster

After the cluster is created, you can update attributes of the cluster including both the cluster’s profile and its deployment architecture. You can update the following attributes:

  • Cluster name
  • Password of administrator account
  • Cluster Architecture
  • Instance type of cluster
  • Instance volume properties
  • Networking
  • Allowed IP list
  • Postgres database configuration
  • Retention period
  • Read-only workloads
  • IAM authentication

For example, to set the public allowed IP range list, use the --cidr-blocks flag:

./biganimal update-cluster --name my-biganimal-cluster --provider azure \
  --region eastus \
  --cidr-blocks "9.9.9.9/28=Traffic from App A"

To check whether the setting took effect, use the show-clusters command and view the detailed cluster information output in JSON format. For example,

biganimal show-clusters --name my-biganimal-cluster --provider azure \
  --region eastus \
  --output json \
| jq '.[0].allowIpRangeMap'
Output
[
  [
    "9.9.9.9/28",
    "Traffic from App A"
  ]
]

Update the Postgres configuration of a cluster

To update the Postgres configuration of a BigAnimal cluster directly from the CLI:

biganimal update-cluster --id p-gxhkfww1fe \
  --pg-config "application_name=ba_test_app,array_nulls=false"
Output
Update Cluster operation is started
Cluster ID is "p-gxhkfww1fe"

To specify multiple configurations, you can use multiple --pg-config flags or include multiple configuration settings as a key-value array string separated by commas in one --pg-config flag. If a Postgres setting contains a comma, you need to specify it with a separate --pg-config flag.

Note

You can update "Cluster Architecture" with the --cluster-architecture flag. The only supported scenario is to update a “Single Node” cluster to a “High Availability” cluster.

Restore a cluster

Biganimal continuously backs up your PostgrSQL clusters. Using CLI you can restore a cluster from its backup to any point in time as long as the backups are retained in the backup storage. The restored cluster can be a in another region and with different configurations, you can specify new configurations in restore command. For example:

biganimal restore-cluster \
  --name "my-biganimal-cluster" \
  --provider "azure" \
  --region "eastus" \
  --password "mypassword@123" \
  --new-name "my-biganimal-cluster-restored" \
  --new-region="eastus2" \
  --cluster-architecture "single" \
  --instance-type "azure:Standard_E2s_v3" \
  --volume-type "azurepremiumstorage" \
  --volume-property "P1" \
  --networking "public" \
  --cidr-blocks="10.10.10.10/27=Traffic from App B" \
  --restore-point "2022-01-26T15:04:05+0800" \
  --backup-retention-period "2w" \
  --read-only-workloads: "true"

The password for the restored cluster is a mandatory. The other parameters, if not specified, inherit the source database's settings. In interactive mode, the source database's settings appear as the default input, or appear as the first option in a selection list.

To restore a deleted cluster, use --from-deleted flag in the command.

Note

You can restore a cluster in a "Single" cluster to a "High Availability" cluster and vice versa. You can only restore an "Extreme High Availability" cluster to a cluster in using the same architecture.

Delete a cluster

To delete a cluster you no longer need, use the delete-cluster command. For example:

biganimal delete-cluster \
  --name my-biganimal-cluster \
  --provider azure \
  --region eastus

You can list all deleted clusters with the show-deleted-clusters command and restore them from their history backups as needed.

Using IAM authentication on AWS

To create a cluster that is enabled for IAM authentication, set the --iam-authentication flag on the create-cluster command or in the configuration file to Yes or true, respectively.

To change the IAM authentication setting after creating a cluster, use the --iam-authentication flag on the update-cluster command.

To change the IAM authentication setting when restoring a cluster, use the --iam-authentication flag on the restore-cluster command.