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

# PostgreSQL na Square Cloud: conexão, extensões e limites

> PostgreSQL gerenciado na Square Cloud: connection string, TLS com certificado do cliente, permissões do usuário, extensões disponíveis, pg_cron, configurações de memória e erros comuns.

Uma instância PostgreSQL gerenciada com conexão TLS por certificado do cliente, um banco de dados e um role que são seus, extensões populares prontas para ativar e o `pg_cron` para tarefas agendadas. 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ê:

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

O PostgreSQL exige **SSL/TLS e o certificado do cliente**, além da senha. Baixe o `.pem` em **Conexão** → **Certificado SSL/TLS** e aponte o cliente para ele:

| Parâmetro | Valor |
| :- | :- |
| `sslmode` | `require`, ou `verify-ca` / `verify-full` para também verificar o servidor |
| `sslcert` | o `.pem` |
| `sslkey` | o `.pem` |
| `sslrootcert` | o `.pem` (necessário com `verify-ca` e `verify-full`) |

> [tab] Node.js
>
> ```javascript theme={"system"}
> import fs from "node:fs";
> import pg from "pg";
>
> const pem = fs.readFileSync("certificate.pem", "utf8");
>
> // One pool for the whole process, created once and reused.
> export const pool = new pg.Pool({
>   connectionString: process.env.DATABASE_URL,
>   ssl: { ca: pem, cert: pem, key: pem },
>   max: 10,
> });
>
> const { rows } = await pool.query("SELECT now()");
> ```

> [tab] Python
>
> ```python theme={"system"}
> import os
> import psycopg2
>
> # libpq refuses a key file that other users can read.
> os.chmod("certificate.pem", 0o600)
>
> conn = psycopg2.connect(
>     os.environ["DATABASE_URL"],
>     sslmode="verify-ca",
>     sslrootcert="certificate.pem",
>     sslcert="certificate.pem",
>     sslkey="certificate.pem",
> )
> ```

> [tab] psql
>
> ```bash theme={"system"}
> chmod 600 certificate.pem
> psql "postgresql://squarecloud:PASSWORD@HOST:PORT/squarecloud?sslmode=verify-ca&sslrootcert=certificate.pem&sslcert=certificate.pem&sslkey=certificate.pem"
> ```

> [!NOTE]
>
> Clientes em Go rejeitam `sslmode=verify-full` com este certificado (`x509: certificate relies on legacy Common Name field`): ele indica o host só no Common Name, que o Go não verifica mais. Use `sslmode=verify-ca`, que continua validando o certificado.

ORMs e outros clientes (Prisma, Drizzle, JDBC, ferramentas GUI) 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, das quais **253 ficam disponíveis para os seus clientes**. Passando disso, novas conexões falham com `remaining connection slots are reserved for roles with the SUPERUSER attribute` (ou `sorry, too many clients already`). 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. Uma conexão nova por requisição ou por query esgota o limite rapidamente. A aba **Insights** mostra quem está com as conexões abertas.

## Seu usuário e permissões

O role `squarecloud` tem `LOGIN`, `CREATEDB`, `CREATEROLE` e `BYPASSRLS`, e é dono do banco `squarecloud`. Você pode criar bancos de dados, schemas, roles e grants, e mudar as configurações que um usuário comum pode mudar, para uma sessão ou como padrão:

```sql theme={"system"}
ALTER ROLE squarecloud SET statement_timeout = '30s';
ALTER DATABASE squarecloud SET work_mem = '16MB';
```

O role **não é superusuário** e não tem direitos de replicação. Isso descarta:

* `ALTER SYSTEM` e as configurações reservadas a superusuários;
* `COPY ... TO/FROM 'file'` no lado do servidor (use o `\copy` do `psql`, que lê e escreve na sua máquina);
* linguagens não confiáveis, como `plpython3u`;
* replicação lógica e as ferramentas de change data capture que dependem dela.

## Extensões

Já instaladas: `plpgsql`, mais `pg_cron` e `pg_stat_statements` no banco `postgres`.

Você pode ativar estas em qualquer um dos seus bancos com `CREATE EXTENSION`, no banco que vai usá-las:

`vector` (pgvector), `pg_trgm`, `pgcrypto`, `uuid-ossp`, `citext`, `hstore`, `unaccent`, `ltree`, `btree_gin`, `btree_gist`, `cube`, `dict_int`, `fuzzystrmatch`, `intarray`, `isn`, `lo`, `seg`, `tablefunc`, `tcn`, `tsm_system_rows`, `tsm_system_time`.

```sql theme={"system"}
CREATE EXTENSION IF NOT EXISTS vector;
```

Nenhuma outra extensão está disponível, e nenhuma pode ser adicionada a pedido. O PostGIS, por exemplo, não está disponível.

## Tarefas agendadas com pg\_cron

O `pg_cron` fica no banco `postgres`. Conecte-se ao `postgres` (mesma URL, terminando em `/postgres`) e agende a tarefa para rodar no seu banco. Os horários são em **UTC**:

```sql theme={"system"}
SELECT cron.schedule_in_database(
  'refresh-stats',          -- job name
  '*/5 * * * *',            -- every 5 minutes
  'REFRESH MATERIALIZED VIEW stats',
  'squarecloud'             -- database the job runs in
);

SELECT jobid, jobname, schedule, database FROM cron.job;
SELECT cron.unschedule('refresh-stats');
```

O histórico de execuções em `cron.job_run_details` nunca é limpo automaticamente. Agende a limpeza das suas linhas antigas:

```sql theme={"system"}
SELECT cron.schedule_in_database('purge-cron-history', '0 3 * * *',
  $$DELETE FROM cron.job_run_details WHERE end_time < now() - interval '7 days'$$, 'postgres');
```

## Memória e configuração

* O `shared_buffers` é **25% da RAM do banco de dados** (no mínimo 128 MB). Mudar a RAM reinicia o banco para aplicá-lo.
* Para o resto, o PostgreSQL conta com o cache de arquivos do sistema operacional, então a RAM exibida no dashboard sobe e depois fica alta. Isso é normal, não é um vazamento.
* Uma única query pode escrever no máximo **1 GB de arquivos temporários** (ordenações, hashes). Passando disso, a query falha com `temporary file size exceeds temp_file_limit`: adicione um índice ou processe os dados em lotes.
* O write-ahead log ocupa de 256 a 512 MB do armazenamento do banco.
* A configuração do servidor é a mesma em todos os bancos e não pode ser mudada por banco.

## Consultas lentas

As instruções que levam 100 ms ou mais são registradas, e a aba **Insights** as lista com o tempo médio. Para a sua própria análise, conecte-se ao banco `postgres`, consulte o `pg_stat_statements` e use `EXPLAIN ANALYZE` na instrução:

```sql theme={"system"}
SELECT calls, round(mean_exec_time) AS mean_ms, query
FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;
```

## Snapshots

Um snapshot do PostgreSQL contém todos os bancos de dados e roles da instância. Além dos [casos gerais](https://docs.squarecloud.app/pt-br/services/databases.md#snapshots-e-restauração), ele falha quando um banco tem `ALLOW_CONNECTIONS false`, ou quando um lock seu (`LOCK TABLE`, um `ALTER TABLE` demorado) 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 |
| :- | :- | :- |
| `no pg_hba.conf entry for host ... no encryption` | O cliente se conectou sem SSL/TLS. | Ative o `sslmode` e carregue o certificado. |
| `connection requires a valid client certificate` | O SSL/TLS está ligado, mas o certificado do cliente não foi enviado. | Defina `sslcert` e `sslkey` com o `.pem`. |
| `private key file ... has group or world access` | A libpq (psql, psycopg2) recusa um arquivo de chave que outros usuários podem ler. | Rode `chmod 600` no `.pem` (no Python, `os.chmod(path, 0o600)`). |
| `remaining connection slots are reserved for roles with the SUPERUSER attribute` / `sorry, too many clients already` | As 253 conexões estão em uso. | Use um pool compartilhado por processo; veja [Conexões](#conexões). |
| `must be superuser` / `permission denied to set parameter` | O comando exige um superusuário. | Use uma configuração de sessão ou de role, ou outra abordagem. |
| `extension "..." is not available` | A extensão não está na lista acima. | Use uma das extensões disponíveis. |
| `temporary file size exceeds temp_file_limit` | A query precisou de mais de 1 GB de arquivos temporários. | Adicione um índice ou trabalhe em lotes. |
| `could not extend file ... No space left on device` | 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). |
| `the database system is not yet accepting connections` | O banco está se recuperando de uma parada forçada. | Aguarde: ele aceita conexões quando a recuperação termina. |

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