> ## 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.

# Python SDK: managed databases

> Create, inspect, update, start, stop and delete managed databases, read their status and metrics, and manage their credentials with client.databases.

`client.databases` manages Square Cloud's managed databases (MongoDB, MySQL, PostgreSQL and Redis). Every method except `create` and `status_all` takes the database id first. To list your databases, use [`client.account.me()`](/en/sdks/py/client#account): its `databases` list has every database the key can see.

Database hosting needs a Standard, Pro or Enterprise plan.

Examples use the `client` from [Creating the client](/en/sdks/py/client#creating-the-client). `database_id` is the id of one of your databases: [`client.account.me()`](/en/sdks/py/client#account) lists them.

## Creating a database

`databases.create(name, type=, version=, memory=)` takes the name by position and the other fields as **keyword-only** arguments.

```python theme={"system"}
db = client.databases.create(
    "my-db",
    type="postgres",  # "mongo" | "mysql" | "redis" | "postgres"
    version="17",     # a full version or a prefix
    memory=1024,      # MB, an int
)

print(db["id"], db["connection_url"], db["cluster"])
print(db["password"])            # shown only here: save it
print(db.get("certificate"))     # base64 PEM (private key, then certificate), or None
```

| 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, an `int`. At least 512 for Redis and 1024 for the others |

The `password` and `certificate` are only returned by `create()` (and by [`reset_credentials()`](#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 an `int` (a `float` or a string) |
| 400 | `INSUFFICIENT_MEMORY` | `memory` is below the 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

```python theme={"system"}
db = client.databases.get(database_id)

print(db["id"], db["name"], db["type"], db["ram"], db["port"], db["cluster"], db["created_at"])
```

## Updating a database

`update(database_id, name=None, ram=None)` renames or resizes a database. Both arguments are keyword-only, and those left as `None` are not sent. Pass at least one (400 `NO_UPDATE_DATA` otherwise).

```python theme={"system"}
client.databases.update(database_id, name="orders", ram=2048)
```

## Start and stop

```python theme={"system"}
client.databases.start(database_id)
client.databases.stop(database_id)
```

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(database_id)` returns formatted values; `raw=True` (keyword-only) returns numbers. `status_all()` returns one summary per database. `metrics(database_id)` returns the last 24 hours, one point every 5 minutes, newest first.

```python theme={"system"}
status = client.databases.status(database_id)
print(status["running"], status["cpu"], status["ram"])  # True "0.5%" "120.4MB"

raw = client.databases.status(database_id, raw=True)
print(raw["cpu"], raw["ram"])  # 0.5 120.4

for item in client.databases.status_all():
    print(item["id"], item["running"], item.get("cpu"), item.get("ram"))  # cpu and ram only while running

latest = client.databases.metrics(database_id)[0]
print(latest["date"], latest["cpu"], latest["ram"])
```

The status fields are the same as [app status](/en/sdks/py/managing_application#status).

## Credentials

`certificate(database_id)` returns the TLS certificate as base64-encoded PEM. `reset_credentials(database_id, type)` rotates the password (and returns the new one) or the certificate (and returns `''`). The database must be running (400 `DATABASE_NOT_RUNNING`).

```python theme={"system"}
import base64

certificate = client.databases.certificate(database_id)
pem = base64.b64decode(certificate).decode()

password = client.databases.reset_credentials(database_id, "password")
client.databases.reset_credentials(database_id, "certificate")  # ''
```

## Deleting a database

```python theme={"system"}
client.databases.delete(database_id)
```

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

## Snapshots

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

## Next steps

<CardGroup cols={3}>
  <Card title="Workspaces" icon="users" href="/en/sdks/py/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.