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 over 3 years ago