Creating a cluster on the command line

Suggest edits

We'll be using the BigAnimal command line interface, which is a convenient wrapper to the BigAnimal API. To start, download the latest binary and move it to wherever your system finds executable files (somewhere on your PATH).

Linux and MacOS note

If you're on a Linux or MacOS system, you'll need to mark the biganimal file as executable by running chmod +x [/path/to/biganimal] before you can use it.

Example (for Linux or MacOS):

curl -LO "https://cli.biganimal.com/download/$(uname -s)/$(uname -m)/latest/biganimal"
mkdir -p $HOME/bin
export PATH=$HOME/bin:$PATH
mv ./biganimal $HOME/bin/biganimal
chmod +x $HOME/bin/biganimal

Next, you need to create a credential on BigAnimal. You can pick any username you prefer.

biganimal create-credential -a portal.biganimal.com -o 443 -n newuser

Output

First, copy your one-time code: 
         CODE-CODE
Then visit: https://auth.biganimal.com/activate 
press [Enter] to continue in the web browser... 

Credential "newuser" is created operation succeeded
Switched the context credential to "newuser".

Linux dependencies

The BigAnimal CLI uses the xdg-open utility to open a browser on Linux systems. On minimal systems, you might need to install this dependency before creating a credential.

The command will direct you to open a webpage and copy the randomly generated, one-time code. You’ll need to log in (or already be logged in) to activate the credentials. You can see the credentials you've verified on the command line.

biganimal show-credentials

Output

┌──────────────────────────────────────────────────────┐
│ Credentials                                          │
├─────────┬─────────────────────────────────────┬──────┤
│ name    │ address                             │ port │
├─────────┼─────────────────────────────────────┼──────┤
│ newuser │ portal.biganimal.com                │ 443  │
└─────────┴─────────────────────────────────────┴──────┘

Caution

If you add another credential, you’ll need to add --credential [newuser] to the following commands. If you have only one, the option isn't needed. You can change the default credential using biganimal config set context_credential [name] You can remove unneeded credentials using biganimal delete-credential [olduser]. Most users don't need to add multiple credentials.

In the free trial, the range of cluster options is somewhat limited but should be more than sufficient for demonstrating the capabilities of BigAnimal.

Pick the region closest to you from the list provided by BigAnimal:

biganimal show-regions

Output

Use the arrow keys to navigate: ↓ ↑
Provider ID?
    AWS
  ▸ Azure
┌───────────────────────────────────┐
│ Regions                           │
├────────────┬──────────────────────┤
│ Region Id  │ Region Name          │
├────────────┼──────────────────────┤
│ eastus2    │ (US) East US 2       │
│ westeurope │ (Europe) West Europe │
└────────────┴──────────────────────┘

Other options can be queried by using the CLI, but the only value we need to set for this demo is the region Id.

Edit a new file called create_cluster.yaml:

clusterName: test_cluster # Pick a more meaningful name!
password: mygoodpassword  # Please change this password!
postgresType: epas
postgresVersion: "14"
provider: azure
region: eastus2  # Select from the options given by show-regions
instanceType: azure:Standard_E2s_v3
volumeProperties: P1
volumeType: azurepremiumstorage
networking: public
highAvailability: false

Use the config file to create a new cluster:

biganimal create-cluster --cluster-config-file create_cluster.yaml

Output

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

If successful, create-cluster will give you the ID of your new cluster (you'll use this to manage it) as well as the command you can use to check the status of your new cluster:

biganimal show-clusters --id p-xxxxxxxxxx

Output

┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Clusters                                                                                                                                             │
├──────────────┬──────────────┬───────────────────────────────────┬──────────┬────────────────┬───────────────┬──────────────────────────────┬─────────┤
│ ID           │ Name         │ Status                            │ Provider │ Region         │ Instance Type │ Postgres Type                │ Version │
├──────────────┼──────────────┼───────────────────────────────────┼──────────┼────────────────┼───────────────┼──────────────────────────────┼─────────┤
│ p-xxxxxxxxxx │ test_cluster │ Cluster creation request received │ Azure    │ (US) East US 2 │ E2s v3        │ EDB Postgres Advanced Server │ 14      │
└──────────────┴──────────────┴───────────────────────────────────┴──────────┴────────────────┴───────────────┴──────────────────────────────┴─────────┘

It might take a few minutes to create your cluster. When it’s ready, the Status column will change to "Cluster in healthy state."

In the meantime, you can get the connection string for your cluster:

biganimal show-cluster-connection --id p-xxxxxxxxxxx

Output

┌──────────────────────────────────────────────────────────────────────────────────────────┐
│ Connection String                                                                        │
├──────────────────────────────────────────────────────────────────────────────────────────┤
│ postgres://edb_admin@p-xxxxxxxxxxx.pg.biganimal.io:5432/edb_admin?sslmode=require        │
└──────────────────────────────────────────────────────────────────────────────────────────┘

After the cluster is created, log in by way of psql. Use the password from the config file for edb_admin.

psql 'postgres://edb_admin@p-xxxxxxxxxx.pg.biganimal.io:5432/edb_admin?sslmode=require'

Other options for connecting

Sure, psql is great, but maybe you want to use another client. See Connect to your cluster for other options.

Next steps

Connect to your cluster.

Creating a cluster on the command line

Linux and MacOS note

Linux dependencies

Caution

Other options for connecting

Next steps

Further reading

← Prev

Next →