> ## 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 en Square Cloud: conexión, extensiones y límites

> PostgreSQL gestionado en Square Cloud: cadena de conexión, TLS con certificado de cliente, permisos del usuario, extensiones disponibles, pg_cron, memoria y errores comunes.

Una instancia de PostgreSQL gestionada con conexión TLS por certificado de cliente, una base de datos y un rol que son tuyos, extensiones populares listas para activar y `pg_cron` para tareas programadas. Lo que comparten todos los motores (límites, snapshots, Insights) está en la [visión general de bases de datos](https://docs.squarecloud.app/es/services/databases.md).

## Conectarse

Copia la URL de conexión desde la página de la base de datos en el dashboard. Tiene esta forma, con el usuario `squarecloud` y la base de datos `squarecloud` creados para ti:

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

PostgreSQL exige **SSL/TLS y el certificado de cliente**, además de la contraseña. Descarga el `.pem` en **Conexión** → **Certificado SSL/TLS** y apunta el cliente a él:

| Parámetro | Valor |
| :- | :- |
| `sslmode` | `require`, o `verify-ca` / `verify-full` para verificar también el servidor |
| `sslcert` | el `.pem` |
| `sslkey` | el `.pem` |
| `sslrootcert` | el `.pem` (necesario para `verify-ca` y `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]
>
> Los clientes de Go rechazan `sslmode=verify-full` con este certificado (`x509: certificate relies on legacy Common Name field`): nombra el host solo en su Common Name, que Go ya no verifica. Usa `sslmode=verify-ca`, que sigue validando el certificado.

Los ORM y otros clientes (Prisma, Drizzle, JDBC, herramientas gráficas) se tratan en [errores de conexión a bases de datos](https://docs.squarecloud.app/es/platform/troubleshooting/database-connection-errors.md).

## Conexiones

Cada base de datos acepta hasta 256 conexiones simultáneas, de las cuales **253 están disponibles para tus clientes**. A partir de ahí, las conexiones nuevas fallan con `remaining connection slots are reserved for roles with the SUPERUSER attribute` (o `sorry, too many clients already`). Crea **un pool por proceso** al iniciar y reutilízalo, dimensionado para que todas las aplicaciones, workers y shards juntos queden por debajo del límite. Una conexión nueva por petición o por consulta agota el límite rápidamente. La pestaña **Insights** muestra quién mantiene las conexiones abiertas.

## Tu usuario y permisos

El rol `squarecloud` tiene `LOGIN`, `CREATEDB`, `CREATEROLE` y `BYPASSRLS`, y es dueño de la base de datos `squarecloud`. Puedes crear bases de datos, esquemas, roles y permisos, y cambiar los ajustes que un usuario normal puede cambiar, para una sesión o como valor por defecto:

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

El rol **no es superusuario** y no tiene permisos de replicación. Eso descarta:

* `ALTER SYSTEM` y los ajustes reservados a superusuarios;
* `COPY ... TO/FROM 'file'` del lado del servidor (usa `\copy` en `psql`, que lee y escribe en tu máquina);
* lenguajes no confiables como `plpython3u`;
* la replicación lógica y las herramientas de captura de cambios (change data capture) que la necesitan.

## Extensiones

Ya instaladas: `plpgsql`, además de `pg_cron` y `pg_stat_statements` en la base de datos `postgres`.

Puedes activar estas en cualquiera de tus bases de datos con `CREATE EXTENSION`, en la base de datos que las va a usar:

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

No hay ninguna otra extensión disponible, y no se pueden añadir por solicitud. PostGIS, por ejemplo, no está disponible.

## Tareas programadas con pg\_cron

`pg_cron` vive en la base de datos `postgres`. Conéctate a `postgres` (la misma URL, terminada en `/postgres`) y programa la tarea para que se ejecute en tu base de datos. Los horarios están 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');
```

El historial de ejecuciones en `cron.job_run_details` nunca se limpia automáticamente. Programa una limpieza de tus filas antiguas:

```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 y configuración

* `shared_buffers` es el **25% de la RAM de la base de datos** (al menos 128 MB). Cambiar la RAM reinicia la base de datos para aplicarlo.
* Para el resto, PostgreSQL depende de la caché de archivos del sistema operativo, así que la RAM que muestra el dashboard sube y luego se mantiene alta. Es normal, no una fuga.
* Una sola consulta puede escribir como máximo **1 GB de archivos temporales** (ordenaciones, hashes). Si lo supera, la consulta falla con `temporary file size exceeds temp_file_limit`: añade un índice o procesa los datos por lotes.
* El write-ahead log ocupa de 256 a 512 MB del almacenamiento de la base de datos.
* La configuración del servidor es la misma en todas las bases de datos y no se puede cambiar por base de datos.

## Consultas lentas

Las sentencias que tardan 100 ms o más se registran, y la pestaña **Insights** las lista con su tiempo medio. Para tu propio análisis, conéctate a la base de datos `postgres`, consulta `pg_stat_statements` y usa `EXPLAIN ANALYZE` en la sentencia:

```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 de PostgreSQL contiene todas las bases de datos y roles de la instancia. Además de los [casos generales](https://docs.squarecloud.app/es/services/databases.md#snapshots-y-restauración), falla cuando una base de datos tiene `ALLOW_CONNECTIONS false`, o cuando un bloqueo tuyo (`LOCK TABLE`, un `ALTER TABLE` largo) lo impide durante más de 5 minutos. La exportación es texto SQL plano, así que una base de datos cerca de sus 10 GB de almacenamiento puede no caber en un snapshot.

## Errores comunes

| Mensaje | Qué significa | Qué hacer |
| :- | :- | :- |
| `no pg_hba.conf entry for host ... no encryption` | El cliente se conectó sin SSL/TLS. | Activa `sslmode` y carga el certificado. |
| `connection requires a valid client certificate` | SSL/TLS está activado, pero no se envió el certificado de cliente. | Configura `sslcert` y `sslkey` con el `.pem`. |
| `private key file ... has group or world access` | libpq (psql, psycopg2) rechaza un archivo de clave legible por otros. | Aplica `chmod 600` al `.pem` (en Python, `os.chmod(path, 0o600)`). |
| `remaining connection slots are reserved for roles with the SUPERUSER attribute` / `sorry, too many clients already` | Las 253 conexiones están en uso. | Usa un solo pool compartido por proceso; consulta [Conexiones](#conexiones). |
| `must be superuser` / `permission denied to set parameter` | El comando necesita un superusuario. | Usa un ajuste de sesión o de rol, u otro enfoque. |
| `extension "..." is not available` | La extensión no está en la lista de arriba. | Usa una de las extensiones disponibles. |
| `temporary file size exceeds temp_file_limit` | La consulta necesitó más de 1 GB de archivos temporales. | Añade un índice o trabaja por lotes. |
| `could not extend file ... No space left on device` | Los 10 GB de almacenamiento están llenos: las escrituras fallan. | Elimina datos; consulta [disco lleno](https://docs.squarecloud.app/es/platform/troubleshooting/database-performance.md#el-disco-está-lleno). |
| `the database system is not yet accepting connections` | La base de datos se está recuperando tras una detención forzada. | Espera: acepta conexiones cuando termina la recuperación. |

## Contáctanos

Si continúas enfrentando **dificultades técnicas**, nuestro **equipo de soporte especializado** está disponible para ayudarte. [**Contáctanos**](https://squarecloud.app/es/support) y estaremos encantados de ayudarte a resolver cualquier problema: la calidad del soporte es una gran parte de por qué los desarrolladores califican a Square Cloud con [**4.9/5 en 402 reseñas**](https://www.trustpilot.com/review/squarecloud.app) en Google y Trustpilot.


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