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

# MySQL na Square Cloud: conexão, permissões e limites

> MySQL gerenciado na Square Cloud: connection string, TLS obrigatório, caching_sha2_password, privilégios do usuário, importação de dumps com DEFINER, buffer pool, slow query log e erros comuns.

Uma instância MySQL gerenciada que só aceita conexões TLS, com um usuário que gerencia os próprios bancos de dados, usuários, rotinas e eventos. O que vale para todos os engines (limites, snapshots, Insights) está na [visão geral de Bancos de dados](https://docs.squarecloud.app/pt-br/services/databases.md).

## Conectar

Copie a URL de conexão da página do banco de dados no dashboard. Ela tem este formato, com o usuário `squarecloud` e o banco `squarecloud` já criados para você:

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

O MySQL exige **SSL/TLS**; não é preciso certificado do cliente. Use `ssl-mode=REQUIRED`, ou `VERIFY_CA` com o `.pem` de **Conexão** → **Certificado SSL/TLS** como CA para também verificar o servidor.

O servidor aceita só a autenticação `caching_sha2_password`. Drivers antigos que não a têm, como o pacote `mysql` do npm, não conseguem fazer login: use o `mysql2` no Node.js ou um conector atual.

> [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
> ```

O servidor não resolve nomes de host: ao criar usuários, a parte do host é um endereço IP ou `'%'`.

ORMs e ferramentas GUI (Prisma, MySQL Workbench, DBeaver, HeidiSQL) estão em [erros de conexão com banco de dados](https://docs.squarecloud.app/pt-br/platform/troubleshooting/database-connection-errors.md).

## Conexões

Cada banco de dados aceita até 256 conexões simultâneas; passando disso, as novas falham com `Too many connections`. Crie **um pool por processo** na inicialização e reutilize-o, dimensionado para que todas as aplicações, workers e shards juntos fiquem abaixo do limite. A aba **Insights** mostra quem está com as conexões abertas.

## Seu usuário e permissões

O usuário `squarecloud@'%'` tem todos os privilégios, com `GRANT OPTION`, exceto os administrativos. Você pode criar bancos de dados, usuários e grants, rotinas, triggers e eventos, e mudar variáveis globais com `SET GLOBAL` e `SET PERSIST`.

O que os privilégios administrativos permitiriam não está disponível:

* arquivos no lado do servidor: `LOAD DATA INFILE` e `SELECT ... INTO OUTFILE`;
* `FLUSH PRIVILEGES`, que responde `ERROR 1227`. Ele não é necessário: `GRANT`, `CREATE USER` e `ALTER USER` valem na hora;
* `SHOW ENGINE INNODB STATUS`;
* replicação.

## Importar um dump

Dumps feitos em outro servidor costumam trazer `DEFINER=root@localhost` (ou outra conta administrativa) em views, rotinas, triggers e eventos. A importação falha com `ERROR 1227 (42000): Access denied; you need (at least one of) the ... privilege(s)`. Remova essas cláusulas antes de importar, ou troque-as pelo seu próprio usuário:

```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
```

## Configuração

* **Sem binary log.** Replicação, change data capture (Debezium e similares) e recuperação point-in-time não estão disponíveis.
* **Buffer pool:** o `innodb_buffer_pool_size` mantém o padrão do MySQL, de **128 MB**; ele não cresce com a RAM do banco. Você pode aumentá-lo dentro da RAM que alocou, deixando espaço para as conexões e para o próprio servidor (cerca de metade da RAM é um começo seguro):
  ```sql theme={"system"}
  SET PERSIST innodb_buffer_pool_size = 536870912; -- 512 MB
  ```
  Um valor persistido se perde quando o banco é restaurado de um snapshot ou atualizado: defina-o de novo depois.
* **`max_allowed_packet`** é 64 MB, a maior instrução ou linha que o servidor aceita.
* O resto da configuração do servidor é igual em todos os bancos.

## Consultas lentas

A aba **Insights** lista as instruções por tempo médio (qualquer instrução com uma execução de 100 ms ou mais). Para o slow query log bruto, ative-o: ele é gravado na tabela `mysql.slow_log` com o mesmo limite de 100 ms, nunca expira e usa o armazenamento do banco, então esvazie-o quando terminar:

```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;
```

## Snapshots

Um snapshot do MySQL contém seus schemas, rotinas, triggers, eventos e usuários, exportados em uma única transação: consistente para tabelas InnoDB, sem garantia para MyISAM. Além dos [casos gerais](https://docs.squarecloud.app/pt-br/services/databases.md#snapshots-e-restauração), ele falha quando um `LOCK TABLES` seu o bloqueia por mais de 5 minutos. A exportação é texto SQL puro, então um banco perto dos 10 GB de armazenamento pode não caber em um snapshot.

## Erros comuns

| Mensagem | O que significa | O que fazer |
| :- | :- | :- |
| `Connections using insecure transport are prohibited while --require_secure_transport=ON` | O cliente se conectou sem SSL/TLS. | Ative o SSL/TLS (`ssl-mode=REQUIRED`). |
| `ER_NOT_SUPPORTED_AUTH_MODE` | O driver não tem `caching_sha2_password`. | Troque para o `mysql2` ou um conector atual. |
| `Too many connections` | As 256 conexões estão em uso. | Use um pool compartilhado por processo; veja [Conexões](#conexões). |
| `ERROR 1227 (42000): Access denied; you need ... privilege(s)` | A instrução exige um privilégio administrativo, ou um dump traz `DEFINER=root`. | Tire o `FLUSH PRIVILEGES`; remova as cláusulas `DEFINER`. |
| `Got a packet bigger than 'max_allowed_packet' bytes` | Uma instrução ou linha passa de 64 MB. | Divida-a em inserts menores. |
| `The table '...' is full` | Os 10 GB de armazenamento estão cheios: as escritas falham. | Apague dados; veja [disco cheio](https://docs.squarecloud.app/pt-br/platform/troubleshooting/database-performance.md#o-disco-está-cheio). |

Depois de uma parada forçada, o MySQL roda a recuperação de falhas no próximo início, o que demora mais em bancos grandes: aguarde até ela terminar.

## Contate-nos

Se você continuar enfrentando **dificuldades técnicas**, nossa **equipe de suporte especializada** está disponível para auxiliá-lo. [**Entre em contato conosco**](https://squarecloud.app/pt-br/support) e teremos prazer em ajudá-lo a resolver qualquer questão: a qualidade do suporte é uma grande parte do motivo pelo qual desenvolvedores avaliam a Square Cloud com [**4,9/5 em 402 avaliações**](https://www.trustpilot.com/review/squarecloud.app) no Google e Trustpilot.


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