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

# Bancos de dados

> Provisione, monitore e gerencie bancos de dados da Square Cloud, incluindo rotação de credenciais e snapshots.

<Info>
  Bancos de dados são expostos pelo módulo `api.databases`. Disponível nos planos **Standard, Pro e Enterprise**.
</Info>

## Criando um banco

`api.databases.create(options)` provisiona um novo banco. A `password` e o `certificate` são retornados **apenas no momento da criação** — armazene-os agora.

```typescript theme={null}
const created = await api.databases.create({
    name: "meu-mongo",
    memory: 1024,
    type: "mongo",
    version: "8",
});

console.log(created.id);
console.log(created.name);
console.log(created.memory);
console.log(created.cpu);
console.log(created.type);
console.log(created.cluster);
console.log(created.connection_url);
console.log(created.password);     // exibido uma única vez — guarde com segurança
console.log(created.certificate);  // exibido uma única vez — guarde com segurança, presente apenas em engines que emitem certificado TLS
```

| Campo     | Tipo     | Descrição                                               |
| --------- | -------- | ------------------------------------------------------- |
| `name`    | `string` | Nome de exibição                                        |
| `memory`  | `number` | Memória alocada em MB                                   |
| `type`    | `string` | Slug do engine: `mongo`, `mysql`, `redis` ou `postgres` |
| `version` | `string` | Versão do engine                                        |

Versões atuais por engine:

| Engine     | Versão |
| ---------- | ------ |
| `postgres` | `17`   |
| `mysql`    | `9`    |
| `mongo`    | `8`    |
| `redis`    | `7`    |

A resposta de `create()` retorna `{ id, name, memory, cpu, type, password, certificate?, connection_url, cluster }`. `cpu` é a CPU alocada (shares); `password` e `certificate` só estão presentes nesta resposta de criação, não em buscas posteriores.

Um `type` não suportado falha com `code: "INVALID_DATABASE_TYPE"`; `memory` insuficiente para o plano falha com `code: "INSUFFICIENT_MEMORY"`; uma falha durante o provisionamento falha com `code: "DATABASE_CREATION_FAILED"`.

## Listando seus bancos

`api.user.get()` popula `user.databases` com uma `Collection` contendo todos os bancos da conta:

```typescript theme={null}
const user = await api.user.get();

for (const [id, db] of user.databases) {
    console.log(`${db.name} (${id}) — ${db.type} ${db.ram}MB`);
}
```

## Buscando um banco específico

```typescript theme={null}
const db = await api.databases.fetch(created.id);

console.log(db.id);
console.log(db.name);
console.log(db.owner);
console.log(db.type);
console.log(db.ram);
console.log(db.cluster);
console.log(db.port);
console.log(db.createdAt);
```

## Ciclo de vida

```typescript theme={null}
await db.start();
await db.stop();
```

## Status e métricas

```typescript theme={null}
const status = await db.getStatus();
console.log(`${status.status} • CPU ${status.usage.cpu} • RAM ${status.usage.ram}`);

const metrics = await db.getMetrics();
console.log(`${metrics.length} pontos (até 288 em 24h)`);
```

### Status resumido de todos os bancos

```typescript theme={null}
const all = await api.databases.statusAll();

for (const summary of all) {
    console.log(`${summary.databaseId} → ${summary.running ? "running" : "stopped"}`);

    // Promova para o status completo com .fetch()
    if (summary.running) {
        const full = await summary.fetch();
        console.log(full.usage);
    }
}
```

## Atualizando

`db.update(options)` altera o nome de exibição e/ou a memória alocada. Pelo menos um campo deve ser fornecido.

```typescript theme={null}
await db.update({ name: "primary-db", ram: 1024 });
```

## Credenciais

`db.credentials.certificate()` retorna o certificado TLS (PEM codificado em base64):

```typescript theme={null}
const cert = await db.credentials.certificate();
console.log(`Tamanho do certificado: ${cert.length}`);
```

`db.credentials.reset(type)` rotaciona a senha ou o certificado.

```typescript theme={null}
// Rotaciona a senha — o novo valor é exibido apenas uma vez
const { password } = await db.credentials.reset("password");
console.log(`Nova senha: ${password}`);

// Rotaciona o certificado — busque o novo via .certificate()
await db.credentials.reset("certificate");
const newCert = await db.credentials.certificate();
```

<Warning>
  `db.credentials.certificate()` e `db.credentials.reset()` exigem que o banco esteja **rodando**.
</Warning>

## Snapshots

`db.snapshots` espelha a API de snapshots de aplicações.

```typescript theme={null}
import { writeFile } from "node:fs/promises";

const snapshots = await db.snapshots.list();
console.log(`${snapshots.length} snapshots armazenados`);

const fresh = await db.snapshots.create();
console.log(`URL de download: ${fresh.url}`);

const buffer = await db.snapshots.download();
await writeFile("./db-backup.tar.gz", buffer);

await db.snapshots.restore(
    "00000000-0000-4000-8000-000000000000_mongo",
    "v1",
);
```

<Note>
  Diferente de `app.snapshots.restore({ snapshotId, versionId })`, `db.snapshots.restore(snapshotId, versionId)` usa argumentos posicionais.
</Note>

## Excluindo um banco

<Warning>
  Excluir um banco é irreversível. Garanta um snapshot recente caso precise recuperar os dados.
</Warning>

```typescript theme={null}
await db.delete();
```