> ## 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 su Square Cloud: connessione, estensioni e limiti

> PostgreSQL gestito su Square Cloud: connection string, TLS con certificato client, permessi dell'utente, estensioni disponibili, pg_cron, impostazioni di memoria ed errori comuni.

Un'istanza PostgreSQL gestita con connessione TLS tramite certificato client, un database e un ruolo tutti tuoi, estensioni popolari pronte da attivare e `pg_cron` per i job pianificati. Le informazioni comuni a tutti i motori (limiti, snapshot, Insights) si trovano nella [panoramica dei database](https://docs.squarecloud.app/it/services/databases.md).

## Connettersi

Copia l'URL di connessione dalla pagina del database nella dashboard. Ha questa forma, con l'utente `squarecloud` e il database `squarecloud` creati per te:

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

PostgreSQL richiede **SSL/TLS e il certificato client**, oltre alla password. Scarica il `.pem` in **Connessione** → **Certificato SSL/TLS** e indicalo al client:

| Parametro | Valore |
| :- | :- |
| `sslmode` | `require`, oppure `verify-ca` / `verify-full` per verificare anche il server |
| `sslcert` | il `.pem` |
| `sslkey` | il `.pem` |
| `sslrootcert` | il `.pem` (necessario per `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]
>
> I client Go rifiutano `sslmode=verify-full` con questo certificato (`x509: certificate relies on legacy Common Name field`): indica l'host solo nel suo Common Name, che Go non verifica più. Usa `sslmode=verify-ca`, che convalida comunque il certificato.

ORM e altri client (Prisma, Drizzle, JDBC, strumenti grafici) sono trattati in [errori di connessione al database](https://docs.squarecloud.app/it/platform/troubleshooting/database-connection-errors.md).

## Connessioni

Ogni database accetta fino a 256 connessioni simultanee, di cui **253 disponibili per i tuoi client**. Oltre questo limite, le nuove connessioni falliscono con `remaining connection slots are reserved for roles with the SUPERUSER attribute` (oppure `sorry, too many clients already`). Crea **un solo pool per processo** all'avvio e riutilizzalo, dimensionato in modo che tutte le app, i worker e gli shard insieme restino sotto il limite. Una nuova connessione per ogni richiesta o query esaurisce rapidamente il limite. La scheda **Insights** mostra chi tiene aperte le connessioni.

## Il tuo utente e i permessi

Il ruolo `squarecloud` ha `LOGIN`, `CREATEDB`, `CREATEROLE` e `BYPASSRLS`, ed è proprietario del database `squarecloud`. Puoi creare database, schemi, ruoli e grant, e modificare le impostazioni che un utente normale può modificare, per una sessione o come valore predefinito:

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

Il ruolo **non è un superuser** e non ha diritti di replica. Questo esclude:

* `ALTER SYSTEM` e le impostazioni riservate ai superuser;
* `COPY ... TO/FROM 'file'` lato server (usa `\copy` in `psql`, che legge e scrive sulla tua macchina);
* linguaggi non attendibili come `plpython3u`;
* la replica logica e gli strumenti di change data capture che ne hanno bisogno.

## Estensioni

Già installate: `plpgsql`, più `pg_cron` e `pg_stat_statements` nel database `postgres`.

Puoi attivare queste in qualsiasi tuo database con `CREATE EXTENSION`, nel database che le userà:

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

Nessun'altra estensione è disponibile, e non se ne possono aggiungere su richiesta. PostGIS, per esempio, non è disponibile.

## Job pianificati con pg\_cron

`pg_cron` si trova nel database `postgres`. Connettiti a `postgres` (stesso URL, che termina con `/postgres`) e pianifica il job in modo che venga eseguito nel tuo database. Gli orari sono in **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');
```

Lo storico delle esecuzioni in `cron.job_run_details` non viene mai ripulito automaticamente. Pianifica una pulizia delle tue righe vecchie:

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

## Memoria e configurazione

* `shared_buffers` è il **25% della RAM del database** (almeno 128 MB). Cambiare la RAM riavvia il database per applicarlo.
* Per il resto PostgreSQL si affida alla cache dei file del sistema operativo, quindi la RAM mostrata nella dashboard sale e poi resta alta. È normale, non un memory leak.
* Una singola query può scrivere al massimo **1 GB di file temporanei** (ordinamenti, hash). Oltre questo limite la query fallisce con `temporary file size exceeds temp_file_limit`: aggiungi un indice o elabora i dati a blocchi.
* Il write-ahead log occupa da 256 a 512 MB dello storage del database.
* La configurazione del server è la stessa su ogni database e non può essere modificata per singolo database.

## Query lente

Le istruzioni che richiedono 100 ms o più vengono registrate, e la scheda **Insights** le elenca con il loro tempo medio. Per una tua analisi, connettiti al database `postgres`, interroga `pg_stat_statements` e usa `EXPLAIN ANALYZE` sull'istruzione:

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

## Snapshot

Uno snapshot di PostgreSQL contiene tutti i database e i ruoli dell'istanza. Oltre ai [casi generali](https://docs.squarecloud.app/it/services/databases.md#snapshot-e-ripristino), fallisce quando un database ha `ALLOW_CONNECTIONS false`, oppure quando un tuo lock (`LOCK TABLE`, un `ALTER TABLE` lungo) lo blocca per più di 5 minuti. L'esportazione è testo SQL semplice, quindi un database vicino ai suoi 10 GB di storage potrebbe non stare in uno snapshot.

## Errori comuni

| Messaggio | Cosa significa | Cosa fare |
| :- | :- | :- |
| `no pg_hba.conf entry for host ... no encryption` | Il client si è connesso senza SSL/TLS. | Attiva `sslmode` e carica il certificato. |
| `connection requires a valid client certificate` | SSL/TLS è attivo, ma il certificato client non è stato inviato. | Imposta `sslcert` e `sslkey` sul `.pem`. |
| `private key file ... has group or world access` | libpq (psql, psycopg2) rifiuta un file di chiave leggibile da altri. | Esegui `chmod 600` sul `.pem` (in Python, `os.chmod(path, 0o600)`). |
| `remaining connection slots are reserved for roles with the SUPERUSER attribute` / `sorry, too many clients already` | Tutte le 253 connessioni sono in uso. | Usa un solo pool condiviso per processo; vedi [Connessioni](#connessioni). |
| `must be superuser` / `permission denied to set parameter` | Il comando richiede un superuser. | Usa invece un'impostazione di sessione o di ruolo, oppure un altro approccio. |
| `extension "..." is not available` | L'estensione non è nell'elenco sopra. | Usa una delle estensioni disponibili. |
| `temporary file size exceeds temp_file_limit` | La query ha richiesto più di 1 GB di file temporanei. | Aggiungi un indice o lavora a blocchi. |
| `could not extend file ... No space left on device` | I 10 GB di storage sono pieni: le scritture falliscono. | Elimina dati; vedi [disco pieno](https://docs.squarecloud.app/it/platform/troubleshooting/database-performance.md#il-disco-è-pieno). |
| `the database system is not yet accepting connections` | Il database si sta ripristinando dopo un arresto forzato. | Attendi: accetta connessioni quando il ripristino termina. |

## Contattaci

Se continui a riscontrare **difficoltà tecniche**, il nostro **team di supporto specializzato** è disponibile ad assisterti. [**Contattaci**](https://squarecloud.app/it/support) e saremo felici di aiutarti a risolvere qualsiasi problema: la qualità del supporto è una parte importante del motivo per cui gli sviluppatori valutano Square Cloud [**4,9/5 su 402 recensioni**](https://www.trustpilot.com/review/squarecloud.app) su Google e Trustpilot.


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