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

# 数据库

> 置备、监控和管理 Square Cloud 数据库，包括凭据轮换和 snapshot。

<Info>
  数据库由内嵌在 `rest.Rest` 中的 `Databases` 接口暴露。它们在 **Standard、Pro 和 Enterprise** 套餐上可用。
</Info>

```go theme={null}
client := rest.NewClient(os.Getenv("SQUARECLOUD_API_KEY"))
defer client.Close()

api := rest.New(client)
```

## 创建数据库

`api.CreateDatabase(opts)` 依据 `squarecloud.DatabaseCreateOptions` 置备一个新数据库。

```go theme={null}
created, err := api.CreateDatabase(squarecloud.DatabaseCreateOptions{
	Name:    "my-mongo",
	Memory:  1024,
	Type:    squarecloud.DatabaseTypeMongo,
	Version: "8",
})
if err != nil {
	panic(err)
}

fmt.Println(created.ID)
fmt.Println(created.ConnectionURL) // ready to use — password already embedded
fmt.Println(created.Password)      // shown once — store securely
fmt.Println(created.Certificate)   // shown once — only for engines that issue a TLS cert
```

| 字段        | 类型                         | 说明                                                                                                                                 |
| --------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `Name`    | `string`                   | 显示名称，1–32 个字符                                                                                                                      |
| `Memory`  | `int`                      | 分配的内存（MB）                                                                                                                          |
| `Type`    | `squarecloud.DatabaseType` | 引擎：`DatabaseTypeMongo`、`DatabaseTypeMySQL`、`DatabaseTypeRedis` 或 `DatabaseTypePostgres`（slug 为 `mongo`、`mysql`、`redis`、`postgres`） |
| `Version` | `string`                   | 引擎版本                                                                                                                               |

<Warning>
  `Password`（以及适用时的 `Certificate`）**仅出现在创建响应中**，之后无法找回 —— 请立即保存。`ConnectionURL` 已嵌入密码，开箱即用。
</Warning>

不受支持的类型会失败，报错代码为 `INVALID_DATABASE_TYPE`；内存对该套餐来说过小会失败，报错代码为 `INSUFFICIENT_MEMORY`；置备过程中出现故障会失败，报错代码为 `DATABASE_CREATION_FAILED`。

## 列出你的数据库

`api.GetDatabases()` 以精简的 `squarecloud.UserDatabase` 描述符列出你拥有的每个数据库：

```go theme={null}
dbs, err := api.GetDatabases()
if err != nil {
	panic(err)
}

for _, db := range dbs {
	fmt.Printf("%s (%s)\n", db.Name, db.ID)
}
```

## 获取单个数据库

```go theme={null}
db, err := api.GetDatabase("abc123def456abc123def456")
if err != nil {
	panic(err)
}

fmt.Println(db.ID, db.Name, db.Type, db.RAM, db.Cluster, db.CreatedAt)
```

## 生命周期

```go theme={null}
err := api.StartDatabase("abc123def456abc123def456")
if err != nil {
	panic(err)
}

err = api.StopDatabase("abc123def456abc123def456")
```

## 状态与指标

数据库的状态和指标 endpoint 与应用的共享同样的结构（它们是类型别名）—— 逐字段说明参见[管理应用](/zh/sdks/go/managing_application)。

```go theme={null}
status, err := api.GetDatabaseStatus("abc123def456abc123def456")
if err != nil {
	panic(err)
}
fmt.Println(status.Status, status.CPU, status.RAM) // formatted strings

raw, err := api.GetDatabaseStatusRaw("abc123def456abc123def456") // numeric values
if err != nil {
	panic(err)
}

metrics, err := api.GetDatabaseMetrics("abc123def456abc123def456")
if err != nil {
	panic(err)
}
fmt.Println(len(metrics), "metric points (up to 288 over 24h)")
```

### 每个数据库的摘要状态

```go theme={null}
list, err := api.GetDatabaseListStatus()
if err != nil {
	panic(err)
}

for _, summary := range list {
	fmt.Printf("%s → running=%v\n", summary.ID, summary.Running)
}
```

## 更新

`api.UpdateDatabase(dbID, opts)` 修改显示名称和/或内存分配。至少必须提供一个字段。

```go theme={null}
err := api.UpdateDatabase("abc123def456abc123def456", squarecloud.DatabaseUpdateOptions{
	Name: "primary-db",
	RAM:  1024,
})
if err != nil {
	panic(err)
}
```

## 凭据

`api.GetDatabaseCertificate(dbID)` 返回 TLS 证书（base64 编码的 PEM）：

```go theme={null}
cert, err := api.GetDatabaseCertificate("abc123def456abc123def456")
if err != nil {
	panic(err)
}
fmt.Println("certificate length:", len(cert))
```

`api.ResetDatabaseCredentials(dbID, reset)` 使用 `squarecloud.DatabaseReset*` 常量轮换密码或证书：

```go theme={null}
// Rotate the password — the new value is shown only once
result, err := api.ResetDatabaseCredentials("abc123def456abc123def456", squarecloud.DatabaseResetPassword)
if err != nil {
	panic(err)
}
fmt.Println("new password:", result.Password)

// Rotate the certificate — fetch the new one via GetDatabaseCertificate
_, err = api.ResetDatabaseCredentials("abc123def456abc123def456", squarecloud.DatabaseResetCertificate)
```

<Warning>
  新密码**仅在密码重置响应中**返回，且只显示一次 —— 请立即保存。
</Warning>

## Snapshots

数据库 snapshot 与应用的 snapshot API 相对应 —— 参见 [Snapshots](/zh/sdks/go/snapshots)。

```go theme={null}
snapshots, err := api.GetDatabaseSnapshots("abc123def456abc123def456")
if err != nil {
	panic(err)
}

created, err := api.CreateDatabaseSnapshot("abc123def456abc123def456")
if err != nil {
	panic(err)
}
fmt.Println("download URL:", created.URL)
```

## 删除数据库

<Warning>
  删除数据库不可逆。如果你日后可能需要恢复数据，请确保你有一个近期的 [snapshot](/zh/sdks/go/snapshots)。
</Warning>

```go theme={null}
err := api.DeleteDatabase("abc123def456abc123def456")
if err != nil {
	panic(err)
}
```