Compose API Documentation

Compose's API gives developers and users programmatic control over the database deployment capabilities of the database-as-a-service platform. Here you'll find the information you need to take the controls.

Guides

Compose deployment's resources are determined by a property known as scale. This property is expressed in units, and the process of changing the number of units associate with a deployment is called scaling.

Scale and billing

Adjusting the scale of a deployment will change the rate you are billed at for the database deployment in many cases.

What is a unit?

We bundle together RAM and Storage allocations into more easily managed blocks that we call units. A database deployment's size is determined by the number of units allocated to it. Because each database technology has different requirements, each database type has it's own unit with its own RAM and storage allocations. For example, a MongoDB database unit has 1024MB of disk and 102MB of RAM; that 10:1 ratio between disk and RAM allocation is common for most database's units.

Units define the granularity of how you can scale a deployment up or down. Databases do not necessarily start with one unit. When we bring a database to Compose, we also calculate the minimum number of units a database needs to operate efficiently. We then stop users from scaling under that minimum. It varies from database to database; PostgreSQL's minimum is 1 unit while Elasticsearch needs 2 and Scylla needs 10 units.

To find out about a deployment's current allocated and used units along with the starting and mininmum units, use the /2016-07/deployments/:id/scalings endpoint.

Scaling up and down

Compose database deployments are responsive to resource needs and, through autoscaling algorithms, will detect when units should be added or removed to a deployment to keep it running effectively and efficiently.

There are situations where it is preferable to pre-empt the algorithms though; for example in the case of a massive bulk upload to ensure the database isn't always autoscaling as you import data, or after a bulk purge of old data. For that, we have ability in the API to set the new number of units that a deployment uses through the scalings endpoint.

The new number of units must be more than the minimum for that database type and not equal to the current number of units allocated - these will generate error responses from the API. Also, be sure not to set the number of units to less than the amount of resources actually in use; this can cause various databases to have problems as they attempt to handle the under-resourcing.

To adjust a deployment's scale, use the /2016-07/deployments/:id/scalings endpoint.

Updated 3 years ago


What's Next

Alerts

Scaling


Suggested Edits are limited on API Reference Pages

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