> ## 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 上的 MySQL：连接、权限与限制

> Square Cloud 上的托管 MySQL：连接字符串、强制 TLS、caching_sha2_password、用户权限、导入带 DEFINER 的转储、buffer pool、慢查询日志以及常见错误。

一个只接受 TLS 连接的托管 MySQL 实例，附带一个可以管理自己的数据库、用户、例程和事件的用户。所有引擎共有的信息（限制、snapshot、Insights）请参阅[数据库概览](https://docs.squarecloud.app/zh/services/databases.md)。

## 连接

从控制台中该数据库的页面复制连接 URL。它的形式如下，其中 `squarecloud` 用户和 `squarecloud` 数据库已为你创建好：

```
mysql://squarecloud:PASSWORD@HOST:PORT/squarecloud
```

MySQL 要求 **SSL/TLS**；不需要客户端证书。使用 `ssl-mode=REQUIRED`，或者使用 `VERIFY_CA` 并以 **连接** → **SSL/TLS 证书** 中的 `.pem` 作为 CA，以同时校验服务器。

服务器只接受 `caching_sha2_password` 身份验证。缺少这一支持的旧驱动（例如 npm 的 `mysql` 包）无法登录：在 Node.js 上请使用 `mysql2`，或使用最新的连接器。

> [tab] Node.js
>
> ```javascript theme={"system"}
> import fs from "node:fs";
> import mysql from "mysql2/promise";
>
> // One pool for the whole process, created once and reused.
> export const pool = mysql.createPool({
>   uri: process.env.DATABASE_URL,
>   ssl: { ca: fs.readFileSync("certificate.pem", "utf8") },
>   connectionLimit: 10,
> });
>
> const [rows] = await pool.query("SELECT NOW()");
> ```

> [tab] Python
>
> ```python theme={"system"}
> import os
> from urllib.parse import urlparse, unquote
> import pymysql
>
> url = urlparse(os.environ["DATABASE_URL"])
> conn = pymysql.connect(
>     host=url.hostname,
>     port=url.port,
>     user=unquote(url.username),
>     password=unquote(url.password),
>     database=url.path.lstrip("/"),
>     ssl={"ca": "certificate.pem"},
> )
> ```

> [tab] mysql CLI
>
> ```bash theme={"system"}
> mysql --host=HOST --port=PORT --user=squarecloud --password \
>   --ssl-mode=VERIFY_CA --ssl-ca=certificate.pem squarecloud
> ```

服务器不解析主机名：创建用户时，其主机部分应为 IP 地址或 `'%'`。

ORM 和图形界面工具（Prisma、MySQL Workbench、DBeaver、HeidiSQL）的配置请参阅[数据库连接错误](https://docs.squarecloud.app/zh/platform/troubleshooting/database-connection-errors.md)。

## 连接数

每个数据库最多接受 256 个同时连接；超过之后，新连接会失败并提示 `Too many connections`。请在启动时为**每个进程创建一个连接池**并重复使用，连接池的大小要保证所有应用、worker 和分片加在一起都低于上限。**Insights** 选项卡会显示是谁占用着这些打开的连接。

## 你的用户与权限

`squarecloud@'%'` 用户拥有除管理类权限之外的所有权限，并带有 `GRANT OPTION`。你可以创建数据库、用户和授权，创建例程、触发器和事件，还可以使用 `SET GLOBAL` 和 `SET PERSIST` 修改全局变量。

管理类权限所允许的操作不可用：

* 服务器端文件：`LOAD DATA INFILE` 和 `SELECT ... INTO OUTFILE`；
* `FLUSH PRIVILEGES`，会返回 `ERROR 1227`。它并不需要：`GRANT`、`CREATE USER` 和 `ALTER USER` 会立即生效；
* `SHOW ENGINE INNODB STATUS`；
* 复制。

## 导入转储

从其他服务器导出的转储，其视图、例程、触发器和事件上经常带有 `DEFINER=root@localhost`（或其他管理账户）。导入这类转储会失败并提示 `ERROR 1227 (42000): Access denied; you need (at least one of) the ... privilege(s)`。请在导入前删除这些子句，或将其设置为你自己的用户：

```bash theme={"system"}
sed -E 's/DEFINER=`[^`]+`@`[^`]+`//g' dump.sql > dump-clean.sql
mysql --host=HOST --port=PORT --user=squarecloud --password \
  --ssl-mode=REQUIRED squarecloud < dump-clean.sql
```

## 配置

* **没有二进制日志。** 复制、变更数据捕获（Debezium 等）和时间点恢复均不可用。
* **Buffer pool：** `innodb_buffer_pool_size` 保持 MySQL 默认的 **128 MB**；它不会随数据库的 RAM 增长。你可以在已分配的 RAM 范围内调高它，同时为连接和服务器本身留出空间（RAM 的一半左右是一个稳妥的起点）：
  ```sql theme={"system"}
  SET PERSIST innodb_buffer_pool_size = 536870912; -- 512 MB
  ```
  从 snapshot 恢复数据库或升级数据库后，持久化的值会丢失：之后请重新设置。
* **`max_allowed_packet`** 为 64 MB，即服务器接受的单条语句或单行的最大大小。
* 其余服务器配置在每个数据库上都相同。

## 慢查询

**Insights** 选项卡按平均耗时列出语句（任何一次运行达到 100 ms 或以上的语句）。如需原始的慢查询日志，请将其开启：它会以同样的 100 ms 阈值写入 `mysql.slow_log` 表，永不过期并占用数据库的存储，因此用完后请清空它：

```sql theme={"system"}
SET GLOBAL slow_query_log = ON;
SELECT start_time, query_time, sql_text FROM mysql.slow_log ORDER BY start_time DESC LIMIT 10;
TRUNCATE TABLE mysql.slow_log;
SET GLOBAL slow_query_log = OFF;
```

## Snapshot

MySQL 的 snapshot 包含你的 schema、例程、触发器、事件和用户，在单个事务中导出：对 InnoDB 表是一致的，对 MyISAM 表则不作保证。除了[通用情况](https://docs.squarecloud.app/zh/services/databases.md#snapshot-与恢复)之外，当你自己的 `LOCK TABLES` 阻塞它超过 5 分钟时，snapshot 也会失败。导出内容是纯 SQL 文本，因此接近 10 GB 存储上限的数据库可能无法放进一个 snapshot。

## 常见错误

| 信息 | 含义 | 处理方法 |
| :- | :- | :- |
| `Connections using insecure transport are prohibited while --require_secure_transport=ON` | 客户端未使用 SSL/TLS 连接。 | 启用 SSL/TLS（`ssl-mode=REQUIRED`）。 |
| `ER_NOT_SUPPORTED_AUTH_MODE` | 驱动不支持 `caching_sha2_password`。 | 换用 `mysql2` 或最新的连接器。 |
| `Too many connections` | 256 个连接已全部被占用。 | 每个进程使用一个共享连接池；参见[连接数](#连接数)。 |
| `ERROR 1227 (42000): Access denied; you need ... privilege(s)` | 该语句需要管理类权限，或转储中带有 `DEFINER=root`。 | 去掉 `FLUSH PRIVILEGES`；删除 `DEFINER` 子句。 |
| `Got a packet bigger than 'max_allowed_packet' bytes` | 某条语句或某行超过 64 MB。 | 拆分为更小的插入。 |
| `The table '...' is full` | 10 GB 存储已满：写入失败。 | 删除数据；参见[磁盘已满](https://docs.squarecloud.app/zh/platform/troubleshooting/database-performance.md#磁盘已满)。 |

强制停止后，MySQL 会在下次启动时执行崩溃恢复，数据库越大耗时越长：请等待它完成。

## 联系我们

如果你仍然遇到**技术问题**，我们的**专业支持团队**可以为你提供帮助。[**联系我们**](https://squarecloud.app/zh/support)，我们很乐意协助你解决任何问题，支持质量正是开发者给予 Square Cloud [**4.9/5 评分（共 402 条评价）**](https://www.trustpilot.com/review/squarecloud.app)（Google 与 Trustpilot）的重要原因之一。


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