> ## 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 auf Square Cloud: Verbindung, Erweiterungen und Limits

> Verwaltetes PostgreSQL auf Square Cloud: Connection String, TLS mit Client-Zertifikat, Benutzerrechte, verfügbare Erweiterungen, pg_cron, Speichereinstellungen und häufige Fehler.

Eine verwaltete PostgreSQL-Instanz mit TLS-Verbindung per Client-Zertifikat, einer Datenbank und einer Rolle, die dir gehören, beliebten Erweiterungen, die du nur noch aktivieren musst, und `pg_cron` für geplante Jobs. Was für alle Engines gilt (Limits, Snapshots, Insights), steht in der [Datenbank-Übersicht](https://docs.squarecloud.app/de/services/databases.md).

## Verbinden

Kopiere die Verbindungs-URL von der Seite der Datenbank im Dashboard. Sie hat diese Form, mit dem Benutzer `squarecloud` und der Datenbank `squarecloud`, die für dich angelegt werden:

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

PostgreSQL verlangt **SSL/TLS und das Client-Zertifikat**, zusätzlich zum Passwort. Lade die `.pem` unter **Verbindung** → **SSL/TLS-Zertifikat** herunter und gib sie im Client an:

| Parameter | Wert |
| :- | :- |
| `sslmode` | `require`, oder `verify-ca` / `verify-full`, um auch den Server zu prüfen |
| `sslcert` | die `.pem` |
| `sslkey` | die `.pem` |
| `sslrootcert` | die `.pem` (nötig für `verify-ca` und `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]
>
> Go-Clients lehnen `sslmode=verify-full` mit diesem Zertifikat ab (`x509: certificate relies on legacy Common Name field`): Es nennt den Host nur in seinem Common Name, den Go nicht mehr prüft. Verwende `sslmode=verify-ca`, das das Zertifikat trotzdem validiert.

ORMs und andere Clients (Prisma, Drizzle, JDBC, GUI-Tools) werden unter [Datenbankverbindungsfehler](https://docs.squarecloud.app/de/platform/troubleshooting/database-connection-errors.md) behandelt.

## Verbindungen

Jede Datenbank akzeptiert bis zu 256 gleichzeitige Verbindungen, davon sind **253 für deine Clients verfügbar**. Darüber hinaus schlagen neue Verbindungen mit `remaining connection slots are reserved for roles with the SUPERUSER attribute` (oder `sorry, too many clients already`) fehl. Erstelle beim Start **einen Pool pro Prozess** und verwende ihn wieder, so bemessen, dass alle Apps, Worker und Shards zusammen unter dem Limit bleiben. Eine neue Verbindung pro Request oder pro Query erschöpft das Limit schnell. Der Tab **Insights** zeigt, wer die offenen Verbindungen hält.

## Dein Benutzer und seine Berechtigungen

Die Rolle `squarecloud` hat `LOGIN`, `CREATEDB`, `CREATEROLE` und `BYPASSRLS` und ist Eigentümerin der Datenbank `squarecloud`. Du kannst Datenbanken, Schemas, Rollen und Grants erstellen und Einstellungen ändern, die ein normaler Benutzer ändern darf, für eine Sitzung oder als Standard:

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

Die Rolle ist **kein Superuser** und hat keine Replikationsrechte. Das schließt aus:

* `ALTER SYSTEM` und Einstellungen, die Superusern vorbehalten sind;
* serverseitiges `COPY ... TO/FROM 'file'` (verwende `\copy` in `psql`, das auf deinem Rechner liest und schreibt);
* nicht vertrauenswürdige Sprachen wie `plpython3u`;
* logische Replikation und Change-Data-Capture-Tools, die sie brauchen.

## Erweiterungen

Bereits installiert: `plpgsql`, dazu `pg_cron` und `pg_stat_statements` in der Datenbank `postgres`.

Diese kannst du in jeder deiner Datenbanken mit `CREATE EXTENSION` aktivieren, und zwar in der Datenbank, die sie nutzen wird:

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

Keine andere Erweiterung ist verfügbar, und es können auch auf Anfrage keine hinzugefügt werden. PostGIS zum Beispiel ist nicht verfügbar.

## Geplante Jobs mit pg\_cron

`pg_cron` liegt in der Datenbank `postgres`. Verbinde dich mit `postgres` (dieselbe URL, endend auf `/postgres`) und plane den Job so, dass er in deiner Datenbank läuft. Zeitpläne sind 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');
```

Der Ausführungsverlauf in `cron.job_run_details` wird nie automatisch bereinigt. Plane eine Bereinigung deiner alten Zeilen:

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

## Arbeitsspeicher und Konfiguration

* `shared_buffers` beträgt **25 % des RAM der Datenbank** (mindestens 128 MB). Eine Änderung des RAM startet die Datenbank neu, um ihn zu übernehmen.
* Für den Rest verlässt sich PostgreSQL auf den Datei-Cache des Betriebssystems, daher steigt der im Dashboard angezeigte RAM und bleibt dann hoch. Das ist normal, kein Leak.
* Eine einzelne Abfrage kann höchstens **1 GB temporäre Dateien** schreiben (Sortierungen, Hashes). Darüber hinaus schlägt die Abfrage mit `temporary file size exceeds temp_file_limit` fehl: Füge einen Index hinzu oder verarbeite die Daten in Batches.
* Das Write-Ahead-Log belegt 256 bis 512 MB des Speicherplatzes der Datenbank.
* Die Serverkonfiguration ist auf jeder Datenbank gleich und kann nicht pro Datenbank geändert werden.

## Langsame Abfragen

Anweisungen, die 100 ms oder länger dauern, werden aufgezeichnet, und der Tab **Insights** listet sie mit ihrer mittleren Zeit auf. Für deine eigene Analyse verbinde dich mit der Datenbank `postgres`, frage `pg_stat_statements` ab und nutze `EXPLAIN ANALYZE` für die Anweisung:

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

Ein PostgreSQL-Snapshot enthält jede Datenbank und jede Rolle der Instanz. Neben den [allgemeinen Fällen](https://docs.squarecloud.app/de/services/databases.md#snapshots-und-wiederherstellung) schlägt er fehl, wenn eine Datenbank `ALLOW_CONNECTIONS false` hat oder wenn deine eigene Sperre (`LOCK TABLE`, ein langes `ALTER TABLE`) ihn länger als 5 Minuten blockiert. Der Export ist reiner SQL-Text, daher passt eine Datenbank nahe an ihren 10 GB Speicherplatz eventuell nicht in einen Snapshot.

## Häufige Fehler

| Meldung | Bedeutung | Was zu tun ist |
| :- | :- | :- |
| `no pg_hba.conf entry for host ... no encryption` | Der Client hat sich ohne SSL/TLS verbunden. | Aktiviere `sslmode` und lade das Zertifikat. |
| `connection requires a valid client certificate` | SSL/TLS ist aktiv, aber das Client-Zertifikat wurde nicht gesendet. | Setze `sslcert` und `sslkey` auf die `.pem`. |
| `private key file ... has group or world access` | libpq (psql, psycopg2) lehnt eine für andere lesbare Schlüsseldatei ab. | `chmod 600` auf die `.pem` anwenden (in Python `os.chmod(path, 0o600)`). |
| `remaining connection slots are reserved for roles with the SUPERUSER attribute` / `sorry, too many clients already` | Alle 253 Verbindungen sind belegt. | Nutze einen gemeinsamen Pool pro Prozess; siehe [Verbindungen](#verbindungen). |
| `must be superuser` / `permission denied to set parameter` | Der Befehl erfordert einen Superuser. | Nutze stattdessen eine Sitzungs- oder Rolleneinstellung oder einen anderen Ansatz. |
| `extension "..." is not available` | Die Erweiterung steht nicht in der Liste oben. | Nutze eine der verfügbaren Erweiterungen. |
| `temporary file size exceeds temp_file_limit` | Die Abfrage brauchte mehr als 1 GB temporäre Dateien. | Füge einen Index hinzu oder arbeite in Batches. |
| `could not extend file ... No space left on device` | Die 10 GB Speicherplatz sind voll: Schreibvorgänge schlagen fehl. | Lösche Daten; siehe [Speicherplatz voll](https://docs.squarecloud.app/de/platform/troubleshooting/database-performance.md#der-speicherplatz-ist-voll). |
| `the database system is not yet accepting connections` | Die Datenbank erholt sich nach einem erzwungenen Stopp. | Warte: Sie nimmt Verbindungen an, sobald die Recovery abgeschlossen ist. |

## Kontaktiere uns

Falls du weiterhin **technische Schwierigkeiten** hast, steht dir unser **spezialisiertes Support-Team** zur Verfügung. [**Kontaktiere uns**](https://squarecloud.app/de/support) und wir helfen dir gerne, jedes Problem zu lösen: die Qualität unseres Supports ist ein wichtiger Grund, warum Entwickler Square Cloud mit [**4,9/5 bei 402 Bewertungen**](https://www.trustpilot.com/review/squarecloud.app) auf Google und Trustpilot bewerten.


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