> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript SDK: managed databases

> Create, inspect, update, start, stop and delete managed databases, read their status and metrics, and manage their credentials with api.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()`](/en/sdks/js/client#account): 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](/en/sdks/js/client#creating-the-client). `databaseId` is the id of one of your databases: [`api.account.me()`](/en/sdks/js/client#account) lists them.

## Creating a database

```typescript theme={"system"}
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()`](#credentials)). 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

```typescript theme={"system"}
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).

```typescript theme={"system"}
await api.databases.update(databaseId, { name: "orders", ram: 2048 });
```

## Start and stop

```typescript theme={"system"}
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.

```typescript theme={"system"}
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](/en/sdks/js/managing_application#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`).

```typescript theme={"system"}
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

```typescript theme={"system"}
await api.databases.delete(databaseId);
```

<Warning>
  Deletion is permanent. Take a [snapshot](/en/sdks/js/snapshots) first if you may need the data again.
</Warning>

## Snapshots

`api.databases.snapshots` has the same `list`, `create` and `restore` as apps. See [Snapshots](/en/sdks/js/snapshots).

## Next steps

<CardGroup cols={3}>
  <Card title="Workspaces" icon="users" href="/en/sdks/js/workspaces">
    Share apps with your team.
  </Card>

  <Card title="Database API reference" icon="code" href="/en/api-reference/endpoint/databases/create">
    The REST endpoints behind these methods.
  </Card>

  <Card title="Databases from the CLI" icon="terminal" href="/en/cli-reference/databases">
    The same actions from the terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.