Compose Database-as-a-Service Help and Documentation

Everything you need to know about Compose, Hosted or Enterprise, is here in our help system. Whether you run one database for your businesses' sole application or six different databases to support an entire corporation, we've got the information you need.

Bach - the Compose Command-line

Bach is a command-line tool designed to be a simple route to accessing the Compose API. It provides the ability to create, monitor and delete Compose databases. Bach is written in Go and uses the GoComposeAPI package for API requests.

📘

Downloading Bach

You can download the latest release of Bach from the Bach latest release page.

The full source code is also available on Github in compose/bach.

Usage

Bach authenticates your access to the underlying Compose API by using a Compose API token. API tokens are provisioned and managed in the Compose console's Account page.

Compose API token management

Once you have your API token, set the environment variable COMPOSEAPITOKEN with it.
export COMPOSEAPITOKEN={your_api_token}

Each bach command is a subcommand. Where a command needs a parameter to identify a deployment, Bach can use either the deployment ID or the deployment name.

Available Commands

Help is available on all commands. The flags -h or --help will display help for the bach command or for any sub-command. For example bach create --help will display help specifically for the create sub-command.

create

Creates a deployment. This command takes a deployment name and database type. See the databases command to get available database types.

bach create <deployment name> <database type> [flags]

$ bach create newdb redis --datacenter aws:us-east-1 --ssl
             ID: 5b3b6098a8b1ad00116ae3eb
           Name: newdb
           Type: redis
        Version: 4.0.10
     Created At: 2018-07-03 11:40:08.884 +0000 UTC
          Notes: 
   Billing Code: 
     Cluster ID: 5601b2639d5a64f769000001
 Prov Recipe ID: 5b3b6098a8b1ad00116ae3ea
 CA Certificate: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t... (Use --fullca for certificate)
    Web UI Link: https://app.compose.io/compose-3/deployments/newdb
 Direct Connect: rediss://admin:[email protected]:16533
                 rediss://admin:[email protected]:16533
           Misc: {
                  "cli_readonly": [],
                  "direct_readonly": [],
                  "ssh_cli": []
                 }

The create command also needs either a --cluster {clusterid} or --datacenter {datacenter/region} to select where the deployment will be created.

The --ssl flag will enable TLS/SSL support on the deployment where available.

If a specific version is required, use the --version flag followed by a version number. See the databases command to get available versions.

MongoDB deployments can use the --wiredtiger flag to select the WiredTiger storage engine rather than the default mmapv1.

Once started, the create command will print all the relevant details of the new deployment. Note that some details may change as the database is still provisioning. To create and wait for completion add either the --wait flag (silent) or --watch flag (regular reports as the task status changes).

Flag

Parameter

Action

--cluster string

Cluster id

Sets cluster for new deployment

--datacenter string

Datacenter region

Sets datacenter/refion for new deployment

--ssl

Add TLS/SSL support to the deployment if available

--version string

Version number

Set database version for new deployment

--wiredtiger

For MongoDB, enable the wiredtiger storage engine.

list

Displays a list of deployment ids, database types and names for deployments attached to the current account. The -t flag allows the list to be filtered by database type. The -f flag allows a regular expression to be used, filtering the list to only names that match the regexp.

bach list [flags]
 
$ bach list
ID                       Type           Name
------------------------ -------------- ----------------------------------------
56aa59a641380c0010000000 mongodb        WiredForTigers
59258b8a272d78000f8665d4 mysql          MyOwnPrivateSQL
$ bach list -t mongodb
ID                       Type           Name
------------------------ -------------- ----------------------------------------
56aa59a641380c0010000000 mongodb        WiredForTigers
$

The deployments command is an alias

Flag

Parameter

Action

-t string

Database type

Filter the list to only matching database types

-f string

Regular expression

Filter the list to only names which match the regular expression

--sortname, -n

Sort by database deployment name (version 0.4.3+)

--sorttype, -d

Sort by database type (version 0.4.3+)

--sortid, -i

Sort by id (version 0.4.3+)

details

Displays details of a deployment. This includes CA Certificates for self-signed deployments, connection strings, notes, versions and database type.

bach details <deployment name or id>

$ bach details newdb
             ID: 5b3b6098a8b1ad00116ae3eb
           Name: newdb
           Type: redis
        Version: 4.0.10
     Created At: 2018-07-03 11:40:08.884 +0000 UTC
          Notes: 
   Billing Code: 
     Cluster ID: 5601b2639d5a64f769000001
    Web UI Link: https://app.compose.io/compose-3/deployments/newdb
 Direct Connect: rediss://admin:[email protected]:16533
                 rediss://admin:[email protected]:16533
           Misc: {
                  "cli_readonly": [],
                  "direct_readonly": [],
                  "ssh_cli": []
                 }

Certificates are truncated by default; use the --fullca flag to have them fully decoded (and --caescaped to wrap them as an escaped string for easier scripted reuse).

$ bach details WiredForTigers --fullca
             ID: 56aa59a641380c0010000000
           Name: WiredForTigers
           Type: mongodb
        Version: 3.2.10
     Created At: 2016-01-28 18:10:46.988 +0000 UTC
          Notes: Designed to hold the most feisty of data
   Billing Code: XXX001
     Cluster ID: 55889965e8e2b432ef000006
 CA Certificate:
-----BEGIN CERTIFICATE-----
MIIDZzCCAk+gAwIBAgIEWH6noDANBgkqhkiG9w0BAQ0FADA1MTMwMQYDVQQDDCpj
....
P9lmdxoukBpXLvg79FHw/pQL2zOchl4EjEC6PdMHo4MkR2i076SfcguM45v9pFO3
zJpYwXp1BQEnBNU=
-----END CERTIFICATE-----
    Web UI Link: https://app.compose.io/compose-3/deployments/WiredForTigers
    CLI Connect: mongo --ssl --sslAllowInvalidCertificates aws-eu-west-1-portal.0.dblayer.com:10980/compose -u admin -p XXXXXXXXXX --authenticationDatabase admin
 Direct Connect: mongodb://admin:[email protected]:10980,aws-eu-west-1-portal.2.dblayer.com:10165/compose?authSource=admin&ssl=true

cacert

The cacert command displays the decoded full CA certificate for self-signed TLS connections to deployments. Where there is no self-signed certificate, the command returns nothing.

bach cacert <deployment name or id>

$ bach cacert WiredForTigers
-----BEGIN CERTIFICATE-----
MIIDZzCCAk+gAwIBAgIEWH6noDANBgkqhkiG9w0BAQ0FADA1MTMwMQYDVQQDDCpj
....
P9lmdxoukBpXLvg79FHw/pQL2zOchl4EjEC6PdMHo4MkR2i076SfcguM45v9pFO3
zJpYwXp1BQEnBNU=
-----END CERTIFICATE-----

versions

The versions command displays information about the database versions a deployment can be upgraded to and the methods by which they can be upgraded.

bach versions <deployment name or id>

$ bach versions gentle-elastic_search-75
    Application: elastic_search
         Method: restore
   From Version: 2.4.6
     To Version: 5.6.9

recipes

The recipes command displays the list of recipes that have been run against a deployment. A recipe is a self-contained task which can, for example, provision, scale, add users or backup a deployment. Many commands in bach (and the API) resolve to a recipe as an ongoing task in the process of being completed. There are a number of options to monitor that task execution. This command, though, displays the complete history of recipes and starts with the deployment being provisioned.

In this example, we see a deployment first being created, then scaled up and then scaled down.

bach recipes <deployment name or id>


$ bach recipes newdb 
             ID: 5b3b6098a8b1ad00116ae3ea
       Template: Recipes::Deployment::Run
         Status: complete
  Status Detail: All operations have completed successfully!
     Account ID: 542da1926b9c7d465d00000a
  Deployment ID: 5b3b6098a8b1ad00116ae3eb
           Name: Provision
     Created At: 2018-07-03 11:40:08.842 +0000 UTC
     Updated At: 2018-07-03 11:43:44.525 +0000 UTC
  Child Recipes: 0

             ID: 5b3b7c7f14d08c001506c7b0
       Template: Recipes::Deployment::Run
         Status: complete
  Status Detail: All operations have completed successfully!
     Account ID: 542da1926b9c7d465d00000a
  Deployment ID: 5b3b6098a8b1ad00116ae3eb
           Name: Scale database to 1GB RAM
     Created At: 2018-07-03 13:39:11.595 +0000 UTC
     Updated At: 2018-07-03 13:39:16.606 +0000 UTC
  Child Recipes: 0

             ID: 5b3b7c922c93b300155a71e0
       Template: Recipes::Deployment::Run
         Status: complete
  Status Detail: All operations have completed successfully!
     Account ID: 542da1926b9c7d465d00000a
  Deployment ID: 5b3b6098a8b1ad00116ae3eb
           Name: Scale database to 256MB RAM
     Created At: 2018-07-03 13:39:30.363 +0000 UTC
     Updated At: 2018-07-03 13:39:35.202 +0000 UTC
  Child Recipes: 0

$

recipe

Each recipe has its own recipe id. The recipe command allows a single recipe to be examined using its id.

bach recipe <recipe id>

$ bach recipe 5b3b7c922c93b300155a71e0
             ID: 5b3b7c922c93b300155a71e0
       Template: Recipes::Deployment::Run
         Status: complete
  Status Detail: All operations have completed successfully!
     Account ID: 542da1926b9c7d465d00000a
  Deployment ID: 5b3b6098a8b1ad00116ae3eb
           Name: Scale database to 256MB RAM
     Created At: 2018-07-03 13:39:30.363 +0000 UTC
     Updated At: 2018-07-03 13:39:35.202 +0000 UTC
  Child Recipes: 0

If the recipe is not complete, adding the --watch flag will poll the recipe until it is complete (or has failed).

watch

The watch command is the equivalent of using bach recipe [recipe id] --watch. It allows for a recipe to be examined and then polled until it is complete (or has failed). If the recipe is already complete, the command returns after printing out the recipe details.

deprovision

The deprovision command shuts down a database deployment and sets off the process for it to be completely removed.

bach deprovision <deployment name or id>

$ bach deprovision gentle-elastic_search-75 
             ID: 5b3b84b814d08c001906c34f
       Template: Recipes::Deployment::Deprovision
         Status: complete
  Status Detail: no operations
     Account ID: 542da1926b9c7d465d00000a
  Deployment ID: 5b3b6d1c2c93b300195a74ab
           Name: Deprovision
     Created At: 2018-07-03 14:14:16.58 +0000 UTC
     Updated At: 2018-07-03 14:14:16.826 +0000 UTC
  Child Recipes: 0

databases

The databases command prints metadata about the types of database available and the versions of each of those databases. When provisioning a deployment, you can select a database type and the "preferred" version will be deployed. The "Type" value can be used in the bach create command to select the database.

$ bach databases
           Type: elastic_search
         Status: stable
        Version: 2.4.6 (stable)
        Version: 5.6.9 (stable)
        Version: 6.2.2 (stable) Preferred

           Type: etcd
         Status: stable
        Version: 3.2.18 (stable) Preferred
        Version: 3.3.3 (stable) Preferred
...

datacenters

The datacenters command prints metadata about the locations database deployments can be created in. Note that this is an abstracted datacenter - a location in this table is made of three actual datacenters in that region with the database deployment spread over those locations.

$ bach datacenters
         Region: eu-de-1
       Provider: softlayer
           Slug: softlayer:eu-de-1

         Region: us-washingtondc-1
       Provider: softlayer
           Slug: softlayer:us-washingtondc-1

         Region: frankfurt-2
       Provider: softlayer
           Slug: softlayer:frankfurt-2

         Region: london-02
       Provider: softlayer
           Slug: softlayer:london-02

         Region: us-east1
       Provider: gce
           Slug: gce:us-east1
...

alerts

The alerts command displays the health status, or relevant alerts, for a deployment. Each deployment can have a number of alerts associated with it or it can report as healthy.

$ bach alerts newdb
        Summary: healthy

backups start

The backups start command initiates an on-demand backup on a deployment. It returns the recipe that is running the backup. If you wish to monitor the progress of the backup, add the --watch flag.

bach backups start <deployment id or name>

$ bach backups start newdb     
             ID: 5b3c984d14d08c001106e32f
       Template: Recipes::Deployment::Backup
         Status: running
  Status Detail: Running clean_backups on aws-us-east-1-memory.28.
     Account ID: 542da1926b9c7d465d00000a
  Deployment ID: 5b3b6098a8b1ad00116ae3eb
           Name: Backup
     Created At: 2018-07-04 09:50:05.744 +0000 UTC
     Updated At: 2018-07-04 09:50:06.604 +0000 UTC
  Child Recipes: 0
  
$ bach backups start newdb --watch           
             ID: 5b3c98f0a8b1ad00156b1608
       Template: Recipes::Deployment::Backup
         Status: running
  Status Detail: Running clean_backups on aws-us-east-1-memory.28.
     Account ID: 542da1926b9c7d465d00000a
  Deployment ID: 5b3b6098a8b1ad00116ae3eb
           Name: Backup
     Created At: 2018-07-04 09:52:48.913 +0000 UTC
     Updated At: 2018-07-04 09:52:49.773 +0000 UTC
  Child Recipes: 0

         Status: complete
  Status Detail: All operations have completed successfully!
     Updated At: 2018-07-04 09:52:53.308 +0000 UTC

backups list

The backups list command lists all on-demand and scheduled backups available for a deployment. Each backup shows its backup id, associated deployment id, name, type (on-demand or scheduling) and status of that backup (in progress, complete or failed).

bach backups list <deployment id or name>

$ bach backups list newdb
      Backup ID: 5b3c98f246aa27000176a015
  Deployment ID: 5b3b6098a8b1ad00116ae3eb
    Backup Name: newdb_2018-07-04_09-52-48_utc_on_demand
           Type: on_demand
         Status: complete

Note that in the example above, the deployment is new and only has the one on-demand backup available. Also note that the date and time the backup was made in embedded in the backup name, after the name of the deployment.

backups get

The backups get command displays information about a particular backup. it requires both the deployment id or name and the id of the backup as parameters. The returned information includes a prepared URL to download the particular backup from its encrypted storage.

bach backups get <deployment id or name> <backup id>

$ bach backups get newdb 5b3c98f246aa27000176a015
      Backup ID: 5b3c98f246aa27000176a015
  Deployment ID: 5b3b6098a8b1ad00116ae3eb
    Backup Name: newdb_2018-07-04_09-52-48_utc_on_demand
           Type: on_demand
         Status: complete
  Download Link: https://dblayer-backups-redis.s3.amazonaws.com/compose-3/5b3b6098a8b1ad00116ae3eb/newdb_2018-07-04_09-52-48_utc_on_demand.tar.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256...X-Amz-Signature=c5578bb1b3120e4a4476b86771811a97186e21cb65e4db7453e77d60c0b53af0

The download link is only valid for a limited time and should be consumed as soon as possible.

backups restore

The backups restore command creates a new deployment and loads that deployment with the backup data selected. You need to use the --datacenter or --cluster flags (See the create command); it can restore into another location. The --ssl flag is also required if the new deployment should be configured for SSL. The command will return information about the new deployment.

bach backups restore <source deployment id or name> <backup id> <new deployment name> [--datacenter or --cluster] [--ssl]


$ bach backups restore newdb 5b3c98f246aa27000176a015 freddb --ssl --datacenter aws:eu-west-1 
             ID: 5b3ca14714d08c001906f885
           Name: freddb
           Type: redis
        Version: 4.0.10
     Created At: 2018-07-04 10:28:23.107 +0000 UTC
          Notes: 
   Billing Code: 
     Cluster ID: 55889965e8e2b432ef000006
 Prov Recipe ID: 5b3ca14714d08c001906f884
    Web UI Link: https://app.compose.io/compose-3/deployments/freddb
    CLI Connect: redis-cli -h aws-eu-west-1-portal.8.dblayer.com -p 19172 -a VHMMWSHHGYGCRXOV
 Direct Connect: redis://admin:[email protected]:19172
           Misc: {
                  "cli_readonly": [],
                  "direct_readonly": [],
                  "ssh_cli": []
                 }

If you wish to deploy the newly restored database into the same region as the original database use the cluster id of the original database with the --cluster flag. The restore command generally performs the same way as the create command.

scale

The scale command displays information about the scaling of resources for a deployment. The information is presented as a set of statements.

bach scale <deployment id or name>

$ bach scale newdb
This is a memory scaled deployment.
There is 1 unit of 256MB RAM allocated to it.
This means that each database node has of 256MB of RAM.
The allocated units give 1024MB of storage to the deployment.

scale set

The scale set command sets the resources available to a deployment. The resources are measured in units and the scale command explains how units map to the deployment's resources. The scale set command takes a deployment id and an integer number to be used as the new unit value. This value can be rejected by the underlying API if it is too small for the current database's data. The command returns a recipe which can be monitored using the --watched flag.

bach scale set <deployment id or name> <new integer units value>


$ bach scale set newdb 4
             ID: 5b3cc531a8b1ad00156b1afa
       Template: Recipes::Deployment::Run
         Status: running
  Status Detail: Running reconfig on aws-us-east-1-memory.28.
     Account ID: 542da1926b9c7d465d00000a
  Deployment ID: 5b3b6098a8b1ad00116ae3eb
           Name: Scale database to 1GB RAM
     Created At: 2018-07-04 13:01:37.767 +0000 UTC
     Updated At: 2018-07-04 13:01:38.105 +0000 UTC
  Child Recipes: 0

$ 


$ bach scale set newdb 1 --watch     
             ID: 5b3cc5772c93b300155aacc5
       Template: Recipes::Deployment::Run
         Status: running
  Status Detail: Running reconfig on aws-us-east-1-memory.28.
     Account ID: 542da1926b9c7d465d00000a
  Deployment ID: 5b3b6098a8b1ad00116ae3eb
           Name: Scale database to 256MB RAM
     Created At: 2018-07-04 13:02:47.796 +0000 UTC
     Updated At: 2018-07-04 13:02:48.156 +0000 UTC
  Child Recipes: 0


         Status: complete
  Status Detail: All operations have completed successfully!
     Updated At: 2018-07-04 13:02:52.719 +0000 UTC
$

account

The account command shows information about the account currently in use.

users

The users command displays the users associated with this account.

$ bach users          
             ID: 58854117670bcc001b000000
           Name: James Bond

             ID: 5a0c7b277f57a800136b1efd
           Name: Harry Fenning
           
             ID: 542da1946b9c7d465d00000f
           Name: Account Master

$

user show

The user show command displays information about the current user - that is the user to whom the API token was issued.

$ bach user show
             ID: 542da1946b9c7d465d00000f
           Name: Account Master

user add

The user add command takes a full name and email address and creates a new user associated with the current account. The email address will be used for the user's login and when they connect for the first time, they will need to reset their password to demonstrate ownership of the email address. If the email address is already in use with another account on Compose, the addition will fail.

user del

The user del command takes the user id of a user and deletes that user.

teams list

The teams list command displays the teams (access-control groups), team id and membership of each team. Each member's full name and user id is displayed.

teams create

The teams create takes a name parameter and creates a team with that name.

$ bach teams create "Example team"
        Team ID: 5b3cd2a4e8cb3f000ffc6ea0
      Team Name: Example team
$

teams get

The teams get command displays information about a specific team. It takes a team id as a parameter.

bach teams get <team id>

$ bach teams get 5b3cd2a4e8cb3f000ffc6ea0 
        Team ID: 5b3cd2a4e8cb3f000ffc6ea0
      Team Name: Example team
         Member: Account Master/542da1946b9c7d465d00000f

teams user add

The teams user add command takes a team id and a user id and adds the user id to the members of the specified team. Once added, the full details of the team are displayed.

bach teams user add <team id> <user id>

$ bach teams user add 5b3cd2a4e8cb3f000ffc6ea0 57c72b625df3780024000000
        Team ID: 5b3cd2a4e8cb3f000ffc6ea0
      Team Name: Example team
         Member: Account Master/542da1946b9c7d465d00000f
         Member: Rando Numbra/57c72b625df3780024000000

teams user rem

The teams user rem command takes a team id and a user id and removes the user id from the members of the specified team. Once removed, the full details of the team are displayed.

bach teams user rem <team id> <user id>

$ bach teams user rem 5b3cd2a4e8cb3f000ffc6ea0 57c72b625df3780024000000
        Team ID: 5b3cd2a4e8cb3f000ffc6ea0
      Team Name: Example team
         Member: Account Master/542da1946b9c7d465d00000f
$

clusters

The clusters command displays a list of clusters that are exclusively owned by the account. This command is therefore only useful to users with Compose Enterprise clusters.

about

The about command shows version information for the release of Bach you are using.

help

The help command displays a summary of Bach commands and flags.

Available Flags

Below are a list of globally available flags which can affect the behavior of commands.

Flag

Notes

--fullca

Where certificates are being displayed, decode the certificate and display the decoded results in line without escaping. Suitable for copy and pasting.

--caescaped

Used with --fullca. Display fully decoded certifcate as an escaped string. Suitable for ingestion into other scripts.

--nodecodeca

Used with --fullca. Display full certificate as a Base64 encoded string.

--json

Usable with most commands. Display results as formatted JSON with no post-processing.

--raw

Usable with many commands. Do not parse the returned JSON; display the raw results. Not supported for multi-step commands.

--token <string>

Always available. Use the given API token rather than the environment set token. Used when switching between accounts.

--wait

Available where a command returns a recipe. Silently monitor the returned recipe until complete then exit.

--watch

Available where a command returns a recipe. Monitor the returned recipe until complete, noting any changes and flagging when polling.

Updated about a year ago

Bach - the Compose Command-line


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.