> ## 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 sur Square Cloud : connexion, extensions et limites

> PostgreSQL géré sur Square Cloud : chaîne de connexion, TLS avec certificat client, permissions de l'utilisateur, extensions disponibles, pg_cron, mémoire et erreurs courantes.

Une instance PostgreSQL gérée avec une connexion TLS par certificat client, une base de données et un rôle qui vous appartiennent, des extensions populaires prêtes à être activées et `pg_cron` pour les tâches planifiées. Les informations communes à tous les moteurs (limites, snapshots, Insights) se trouvent dans la [vue d'ensemble des bases de données](https://docs.squarecloud.app/fr/services/databases.md).

## Se connecter

Copiez l'URL de connexion depuis la page de la base de données dans le tableau de bord. Elle a cette forme, avec l'utilisateur `squarecloud` et la base de données `squarecloud` créés pour vous :

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

PostgreSQL exige **SSL/TLS et le certificat client**, en plus du mot de passe. Téléchargez le `.pem` sous **Connexion** → **Certificat SSL/TLS** et indiquez-le au client :

| Paramètre | Valeur |
| :- | :- |
| `sslmode` | `require`, ou `verify-ca` / `verify-full` pour vérifier aussi le serveur |
| `sslcert` | le `.pem` |
| `sslkey` | le `.pem` |
| `sslrootcert` | le `.pem` (requis par `verify-ca` et `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]
>
> Les clients Go rejettent `sslmode=verify-full` avec ce certificat (`x509: certificate relies on legacy Common Name field`) : il ne nomme l'hôte que dans son Common Name, que Go ne vérifie plus. Utilisez `sslmode=verify-ca`, qui valide quand même le certificat.

Les ORM et les autres clients (Prisma, Drizzle, JDBC, outils graphiques) sont traités dans [les erreurs de connexion aux bases de données](https://docs.squarecloud.app/fr/platform/troubleshooting/database-connection-errors.md).

## Connexions

Chaque base de données accepte jusqu'à 256 connexions simultanées, dont **253 sont disponibles pour vos clients**. Au-delà, les nouvelles connexions échouent avec `remaining connection slots are reserved for roles with the SUPERUSER attribute` (ou `sorry, too many clients already`). Créez **un seul pool par processus** au démarrage et réutilisez-le, dimensionné pour que l'ensemble des applications, workers et shards reste sous la limite. Une nouvelle connexion à chaque requête reçue ou à chaque requête SQL épuise vite la limite. L'onglet **Insights** montre qui détient les connexions ouvertes.

## Votre utilisateur et ses permissions

Le rôle `squarecloud` dispose de `LOGIN`, `CREATEDB`, `CREATEROLE` et `BYPASSRLS`, et possède la base de données `squarecloud`. Vous pouvez créer des bases de données, des schémas, des rôles et des droits (grants), et modifier les paramètres qu'un utilisateur ordinaire peut modifier, pour une session ou par défaut :

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

Le rôle **n'est pas superutilisateur** et n'a pas de droits de réplication. Cela exclut :

* `ALTER SYSTEM` et les paramètres réservés aux superutilisateurs ;
* `COPY ... TO/FROM 'file'` côté serveur (utilisez `\copy` dans `psql`, qui lit et écrit sur votre machine) ;
* les langages non fiables comme `plpython3u` ;
* la réplication logique et les outils de capture des changements (change data capture) qui en dépendent.

## Extensions

Déjà installées : `plpgsql`, ainsi que `pg_cron` et `pg_stat_statements` dans la base de données `postgres`.

Vous pouvez activer celles-ci dans n'importe laquelle de vos bases de données avec `CREATE EXTENSION`, dans la base de données qui les utilisera :

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

Aucune autre extension n'est disponible, et aucune ne peut être ajoutée sur demande. PostGIS, par exemple, n'est pas disponible.

## Tâches planifiées avec pg\_cron

`pg_cron` se trouve dans la base de données `postgres`. Connectez-vous à `postgres` (même URL, terminée par `/postgres`) et planifiez la tâche pour qu'elle s'exécute dans votre base de données. Les horaires sont en **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');
```

L'historique des exécutions dans `cron.job_run_details` n'est jamais purgé automatiquement. Planifiez le nettoyage de vos anciennes lignes :

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

## Mémoire et configuration

* `shared_buffers` vaut **25 % de la RAM de la base de données** (au moins 128 Mo). Modifier la RAM redémarre la base de données pour l'appliquer.
* Pour le reste, PostgreSQL s'appuie sur le cache de fichiers du système d'exploitation, donc la RAM affichée dans le tableau de bord monte puis reste élevée. C'est normal, ce n'est pas une fuite.
* Une seule requête peut écrire au plus **1 Go de fichiers temporaires** (tris, hachages). Au-delà, la requête échoue avec `temporary file size exceeds temp_file_limit` : ajoutez un index ou traitez les données par lots.
* Le journal d'écriture anticipée (write-ahead log) occupe de 256 à 512 Mo du stockage de la base de données.
* La configuration du serveur est la même sur chaque base de données et ne peut pas être modifiée base par base.

## Requêtes lentes

Les instructions qui prennent 100 ms ou plus sont enregistrées, et l'onglet **Insights** les liste avec leur temps moyen. Pour votre propre analyse, connectez-vous à la base de données `postgres`, interrogez `pg_stat_statements` et utilisez `EXPLAIN ANALYZE` sur l'instruction :

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

Un snapshot PostgreSQL contient toutes les bases de données et tous les rôles de l'instance. En plus des [cas généraux](https://docs.squarecloud.app/fr/services/databases.md#snapshots-et-restauration), il échoue quand une base de données a `ALLOW_CONNECTIONS false`, ou quand l'un de vos propres verrous (`LOCK TABLE`, un long `ALTER TABLE`) le bloque pendant plus de 5 minutes. L'export est du texte SQL brut, donc une base de données proche de ses 10 Go de stockage peut ne pas tenir dans un snapshot.

## Erreurs courantes

| Message | Ce que ça signifie | Que faire |
| :- | :- | :- |
| `no pg_hba.conf entry for host ... no encryption` | Le client s'est connecté sans SSL/TLS. | Activez `sslmode` et chargez le certificat. |
| `connection requires a valid client certificate` | SSL/TLS est activé, mais le certificat client n'a pas été envoyé. | Définissez `sslcert` et `sslkey` sur le `.pem`. |
| `private key file ... has group or world access` | libpq (psql, psycopg2) refuse un fichier de clé lisible par d'autres utilisateurs. | Appliquez `chmod 600` au `.pem` (en Python, `os.chmod(path, 0o600)`). |
| `remaining connection slots are reserved for roles with the SUPERUSER attribute` / `sorry, too many clients already` | Les 253 connexions sont toutes utilisées. | Utilisez un seul pool partagé par processus ; voir [Connexions](#connexions). |
| `must be superuser` / `permission denied to set parameter` | La commande exige un superutilisateur. | Utilisez plutôt un paramètre de session ou de rôle, ou une autre approche. |
| `extension "..." is not available` | L'extension ne figure pas dans la liste ci-dessus. | Utilisez l'une des extensions disponibles. |
| `temporary file size exceeds temp_file_limit` | La requête a eu besoin de plus de 1 Go de fichiers temporaires. | Ajoutez un index ou travaillez par lots. |
| `could not extend file ... No space left on device` | Les 10 Go de stockage sont pleins : les écritures échouent. | Supprimez des données ; voir [disque plein](https://docs.squarecloud.app/fr/platform/troubleshooting/database-performance.md#le-disque-est-plein). |
| `the database system is not yet accepting connections` | La base de données se rétablit après un arrêt forcé. | Patientez : elle accepte les connexions une fois la récupération terminée. |

## Contactez-nous

Si vous rencontrez toujours des **difficultés techniques**, notre **équipe de support spécialisée** est disponible pour vous aider. [**Contactez-nous**](https://squarecloud.app/fr/support) et nous serons ravis de vous aider à résoudre tout problème. La qualité du support compte pour beaucoup dans la note que les développeurs donnent à Square Cloud, [**4,9/5 sur 402 avis**](https://www.trustpilot.com/review/squarecloud.app) sur Google et Trustpilot.


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