JavaScript SDK: managed databases

api.databases manages Square Cloud’s managed databases (MongoDB, MySQL, PostgreSQL and Redis). Every method except create and statusAll takes the database id first. To list your databases, use api.account.me(): its databases array has every database the key can see. Database hosting needs a Standard, Pro or Enterprise plan. Examples use the api client from Creating the client. databaseId is the id of one of your databases: api.account.me() lists them.

Creating a database

const db = await api.databases.create({
    name: "my-db",
    type: "postgres", // "mongo" | "mysql" | "redis" | "postgres"
    version: "17",    // a full version or a prefix
    memory: 1024,     // MB, a whole number
});

console.log(db.id, db.connection_url, db.cluster);
console.log(db.password);    // shown only here: save it
console.log(db.certificate); // base64 PEM (private key, then certificate), or null

Field	Description
`name`	1 to 32 characters
`type`	`mongo`, `mysql`, `redis` or `postgres`
`version`	A full version or a prefix such as `"8"`
`memory`	MB, a whole number. At least 512 for Redis and 1024 for the others

The password and certificate are only returned by create() (and by resetCredentials()). The call waits at least 120 s before timing out.

Status	Code	When
400	`INVALID_NAME`	The name is not 1 to 32 characters
400	`INVALID_DATABASE_TYPE`, `INVALID_DATABASE_VERSION`	Unknown type or unsupported version
400	`INVALID_MEMORY`	`memory` is not a whole number (a fraction or a string)
400	`INSUFFICIENT_MEMORY`	`memory` is below the engine’s minimum or exceeds the available memory
400	`CLUSTER_SELECTION_FAILED`	No cluster had enough capacity
400 / 500	`DATABASE_CREATION_FAILED`	Provisioning failed
403	`UPGRADE_REQUIRED`	The plan has no database hosting
503	`CLUSTER_MAINTENANCE_TRY_LATER`	Provisioning is paused for maintenance

Getting a database

const db = await api.databases.get(databaseId);

console.log(db.id, db.name, db.type, db.ram, db.port, db.cluster, db.created_at);

Updating a database

update(databaseId, { name, ram }) renames or resizes a database. Pass at least one field (400 NO_UPDATE_DATA otherwise).

await api.databases.update(databaseId, { name: "orders", ram: 2048 });

Start and stop

await api.databases.start(databaseId);
await api.databases.stop(databaseId);

Like app lifecycle calls, they wait at least 120 s, and a refusal is 409 with a code and an empty message: CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT or ACTION_FAILED. While a snapshot restore runs, they are 403 RESTORE_IN_PROGRESS.

Status and metrics

status(databaseId) returns formatted values; { raw: true } returns numbers. statusAll() returns one summary per database. metrics(databaseId) returns the last 24 hours, one point every 5 minutes, newest first.

const status = await api.databases.status(databaseId);
console.log(status.running, status.cpu, status.ram); // true "0.5%" "120.4MB"

const raw = await api.databases.status(databaseId, { raw: true });
console.log(raw.cpu, raw.ram); // 0.5 120.4

for (const { id, running, cpu, ram } of await api.databases.statusAll()) {
    console.log(id, running, cpu, ram); // cpu and ram only while running
}

const [latest] = await api.databases.metrics(databaseId);
console.log(latest.date, latest.cpu, latest.ram);

The status fields are the same as app status.

Credentials

certificate(databaseId) returns the TLS certificate as base64-encoded PEM. resetCredentials(databaseId, type) rotates the password (and returns the new one) or the certificate (and returns ""). The database must be running (400 DATABASE_NOT_RUNNING).

const certificate = await api.databases.certificate(databaseId);
const pem = atob(certificate);

const password = await api.databases.resetCredentials(databaseId, "password");
await api.databases.resetCredentials(databaseId, "certificate"); // ""

Deleting a database

await api.databases.delete(databaseId);

Deletion is permanent. Take a snapshot first if you may need the data again.

Snapshots

api.databases.snapshots has the same list, create and restore as apps. See Snapshots.

Next steps

Workspaces

Share apps with your team.

Database API reference

The REST endpoints behind these methods.

Databases from the CLI

The same actions from the terminal.

CLI

VS Code

SDKs

JavaScript SDK: managed databases

Creating a database

Getting a database

Updating a database

Start and stop

Status and metrics

Credentials

Deleting a database

Snapshots

Next steps

Workspaces

Database API reference

Databases from the CLI

​Creating a database

​Getting a database

​Updating a database

​Start and stop

​Status and metrics

​Credentials

​Deleting a database

​Snapshots

​Next steps

Workspaces

Database API reference

Databases from the CLI

Creating a database

Getting a database

Updating a database

Start and stop

Status and metrics

Credentials

Deleting a database

Snapshots

Next steps