initdb y el Directorio de Datos

Q: ¿Qué es PGDATA y qué es una base de datos?

PGDATA es un clúster (instancia). Un clúster contiene muchas bases de datos (postgres, myapp, etc.). Un proceso postgres gestiona un PGDATA.

Q: ¿Dónde va WAL con --waldir?

Los segmentos WAL viven bajo la ruta que pasa a --waldir, enlazados simbólicamente desde $PGDATA/pg_wal. Ambas rutas deben estar disponibles al inicio.

initdb crea un nuevo clúster de PostgreSQL en disco. El directorio de datos (PGDATA) contiene todas las bases de datos, WAL y la configuración para esa única instancia.

Receta

sudo -u postgres mkdir -p /var/lib/postgresql/18/main
sudo -u postgres /usr/lib/postgresql/18/bin/initdb \
  -D /var/lib/postgresql/18/main \
  --encoding=UTF8 \
  --locale=C.UTF-8 \
  --data-checksums

Cuándo usar esto: Primer clúster en un host, restauración en un directorio de datos vacío, o construcción de un standby antes de pg_basebackup.

Ejemplo de Trabajo

# Crear puntos de montaje dedicados (patrón de producción)
sudo mkdir -p /data/pgdata /data/pgwal
sudo chown postgres:postgres /data/pgdata /data/pgwal
sudo chmod 700 /data/pgdata /data/pgwal
 
sudo -u postgres initdb \
  -D /data/pgdata \
  --waldir=/data/pgwal \
  --encoding=UTF8 \
  --locale=en_US.UTF-8 \
  --data-checksums
 
# Confirmar el diseño
sudo -u postgres ls -la /data/pgdata
sudo -u postgres ls -la /data/pgdata/base

Lo que esto demuestra:

Separación de PGDATA y WAL en diferentes volúmenes para aislamiento de IO.
Permisos 700 en los directorios de datos (acceso solo para el propietario).
--data-checksums habilita la verificación de sumas de comprobación de páginas en tiempo de lectura.
El subdirectorio base/ aparece después de init - un subdirectorio por OID de base de datos.

Análisis Profundo

Diseño del PGDATA (Rutas Clave)

Ruta	Propósito
`postgresql.conf`	Configuración principal del servidor
`pg_hba.conf`	Reglas de autenticación de clientes
`pg_ident.conf`	Mapas de nombres de usuario
`base/`	Archivos de datos por base de datos
`global/`	Catálogos a nivel de clúster
`pg_wal/`	Registro de escritura anticipada (a menos que se use `--waldir`)
`pg_xact/`	Estado de confirmación de transacciones
`PG_VERSION`	Marcador de versión principal

Modelo de Permisos

# Propiedad correcta
ls -ld /data/pgdata
# drwx------ postgres postgres
 
# Incorrecto: legible por grupo o por todos
chmod 750 /data/pgdata   # evitar - riesgo de fuga de metadatos del catálogo

Solo el usuario del sistema operativo postgres debe leer/escribir PGDATA.
Las herramientas de copia de seguridad se ejecutan como postgres o utilizan instantáneas del sistema de archivos con UID correcto.
Nunca ejecute initdb como root - el servidor se niega a iniciar en datos propiedad de root.

Localización y Codificación

-- Establecido en el momento de init; cambiarlo más tarde requiere re-init
SHOW server_encoding;  -- UTF8
SHOW lc_collate;         -- en_US.UTF-8
SHOW lc_ctype;

Prefiera la codificación UTF8 para todos los clústeres nuevos.
La ordenación C o C.UTF-8 proporciona un orden de clasificación predecible; la ordenación específica de la localización afecta el orden de los índices.
Las locales ICU (--locale-provider=icu) están disponibles en PostgreSQL 15+.

Separación del Directorio WAL

# postgresql.conf (si no se estableció en initdb)
# wal_directory se establece en init a través de --waldir; reubicar con cuidado con pg_resetwal solo en recuperación ante desastres

WAL es de escritura pesada (append-heavy); los archivos de datos son de IO aleatorio - separe pools de SSD/NVMe cuando la IO sea un cuello de botella.
Documente ambas rutas en su inventario - las restauraciones deben recrear el mismo diseño.

Trampas Comunes

Re-ejecutar initdb en un PGDATA existente - initdb falla si el directorio no está vacío. Solución: Use un directorio nuevo y vacío o pg_basebackup para réplicas.
Propiedad incorrecta después de la restauración - chown desde un tar de copia de seguridad como root deja archivos propiedad de root. Solución: chown -R postgres:postgres $PGDATA antes de iniciar.
Sumas de comprobación de datos faltantes - Los clústeres creados sin --data-checksums no pueden habilitarlas más tarde sin re-init. Solución: Habilite en init; planifique la monitorización consciente de sumas de comprobación.
Desajuste de localización entre réplicas - El init de standby con lc_collate diferente rompe las suposiciones del orden de los índices. Solución: Coincida con las banderas de initdb en todos los nodos de una topología.
Disco lleno en PGDATA - initdb necesita espacio temporal; el clúster en ejecución necesita margen para WAL y archivos temporales. Solución: Supervise el porcentaje de uso del sistema de archivos; mantenga WAL en un volumen separado.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
Init gestionado por paquete (Debian `pg_createcluster`)	Instalaciones apt estándar	Necesita rutas personalizadas desde el primer día
`pg_basebackup`	Semilla de standby o PITR	Primario nuevo y vacío sin fuente
"Crear instancia" en la nube gestionada	Sin acceso al host	Necesita control a nivel de sistema de archivos

Preguntas Frecuentes

¿Qué es PGDATA y qué es una base de datos?

PGDATA es un clúster (instancia). Un clúster contiene muchas bases de datos (postgres, myapp, etc.). Un proceso postgres gestiona un PGDATA.

¿Puedo mover PGDATA después de init?

Sí, con cuidado: detenga el servidor, mueva el directorio, actualice Environment=PGDATA= en systemd, o use pg_ctl -D. No mueva archivos en vivo mientras el servidor se ejecuta.

¿Por qué chmod 700?

Los archivos de catálogo contienen metadatos del esquema e información de conexión. Los directorios de datos legibles por todos son un hallazgo en auditorías de seguridad.

¿Debo usar --data-checksums?

Sí, para nuevos clústeres de producción. Un pequeño costo de CPU permite la detección temprana de corrupción silenciosa del almacenamiento.

¿Dónde va WAL con --waldir?

Los segmentos WAL viven bajo la ruta que pasa a --waldir, enlazados simbólicamente desde $PGDATA/pg_wal. Ambas rutas deben estar disponibles al inicio.

Relacionado

Conceptos Básicos de Instalación - instalaciones de paquetes antes de initdb
Esenciales de postgresql.conf - ajustar después del primer arranque
pg_hba.conf y Autenticación - permitir conexiones
Systemd y Gestión de Servicios - iniciar el nuevo clúster

Versiones de la Pila: Esta página fue escrita para PostgreSQL 18.4 (estable 18, mantenimiento 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, y PostGIS 3.5+.

initdb y el Directorio de Datos

initdb crea un nuevo clúster de PostgreSQL en disco. El directorio de datos (PGDATA) contiene todas las bases de datos, WAL y la configuración para esa única instancia.

Receta

sudo -u postgres mkdir -p /var/lib/postgresql/18/main
sudo -u postgres /usr/lib/postgresql/18/bin/initdb \
  -D /var/lib/postgresql/18/main \
  --encoding=UTF8 \
  --locale=C.UTF-8 \
  --data-checksums

Cuándo usar esto: Primer clúster en un host, restauración en un directorio de datos vacío, o construcción de un standby antes de pg_basebackup.

Ejemplo de Trabajo

# Crear puntos de montaje dedicados (patrón de producción)
sudo mkdir -p /data/pgdata /data/pgwal
sudo chown postgres:postgres /data/pgdata /data/pgwal
sudo chmod 700 /data/pgdata /data/pgwal
 
sudo -u postgres initdb \
  -D /data/pgdata \
  --waldir=/data/pgwal \
  --encoding=UTF8 \
  --locale=en_US.UTF-8 \
  --data-checksums
 
# Confirmar el diseño
sudo -u postgres ls -la /data/pgdata
sudo -u postgres ls -la /data/pgdata/base

Lo que esto demuestra:

Separación de PGDATA y WAL en diferentes volúmenes para aislamiento de IO.
Permisos 700 en los directorios de datos (acceso solo para el propietario).
--data-checksums habilita la verificación de sumas de comprobación de páginas en tiempo de lectura.
El subdirectorio base/ aparece después de init - un subdirectorio por OID de base de datos.

Análisis Profundo

Diseño del PGDATA (Rutas Clave)

Ruta	Propósito
`postgresql.conf`	Configuración principal del servidor
`pg_hba.conf`	Reglas de autenticación de clientes
`pg_ident.conf`	Mapas de nombres de usuario
`base/`	Archivos de datos por base de datos
`global/`	Catálogos a nivel de clúster
`pg_wal/`	Registro de escritura anticipada (a menos que se use `--waldir`)
`pg_xact/`	Estado de confirmación de transacciones
`PG_VERSION`	Marcador de versión principal

Modelo de Permisos

# Propiedad correcta
ls -ld /data/pgdata
# drwx------ postgres postgres
 
# Incorrecto: legible por grupo o por todos
chmod 750 /data/pgdata   # evitar - riesgo de fuga de metadatos del catálogo

Solo el usuario del sistema operativo postgres debe leer/escribir PGDATA.
Las herramientas de copia de seguridad se ejecutan como postgres o utilizan instantáneas del sistema de archivos con UID correcto.
Nunca ejecute initdb como root - el servidor se niega a iniciar en datos propiedad de root.

Localización y Codificación

-- Establecido en el momento de init; cambiarlo más tarde requiere re-init
SHOW server_encoding;  -- UTF8
SHOW lc_collate;         -- en_US.UTF-8
SHOW lc_ctype;

Prefiera la codificación UTF8 para todos los clústeres nuevos.
La ordenación C o C.UTF-8 proporciona un orden de clasificación predecible; la ordenación específica de la localización afecta el orden de los índices.
Las locales ICU (--locale-provider=icu) están disponibles en PostgreSQL 15+.

Separación del Directorio WAL

# postgresql.conf (si no se estableció en initdb)
# wal_directory se establece en init a través de --waldir; reubicar con cuidado con pg_resetwal solo en recuperación ante desastres

WAL es de escritura pesada (append-heavy); los archivos de datos son de IO aleatorio - separe pools de SSD/NVMe cuando la IO sea un cuello de botella.
Documente ambas rutas en su inventario - las restauraciones deben recrear el mismo diseño.

Trampas Comunes

Re-ejecutar initdb en un PGDATA existente - initdb falla si el directorio no está vacío. Solución: Use un directorio nuevo y vacío o pg_basebackup para réplicas.
Propiedad incorrecta después de la restauración - chown desde un tar de copia de seguridad como root deja archivos propiedad de root. Solución: chown -R postgres:postgres $PGDATA antes de iniciar.
Sumas de comprobación de datos faltantes - Los clústeres creados sin --data-checksums no pueden habilitarlas más tarde sin re-init. Solución: Habilite en init; planifique la monitorización consciente de sumas de comprobación.
Desajuste de localización entre réplicas - El init de standby con lc_collate diferente rompe las suposiciones del orden de los índices. Solución: Coincida con las banderas de initdb en todos los nodos de una topología.
Disco lleno en PGDATA - initdb necesita espacio temporal; el clúster en ejecución necesita margen para WAL y archivos temporales. Solución: Supervise el porcentaje de uso del sistema de archivos; mantenga WAL en un volumen separado.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
Init gestionado por paquete (Debian `pg_createcluster`)	Instalaciones apt estándar	Necesita rutas personalizadas desde el primer día
`pg_basebackup`	Semilla de standby o PITR	Primario nuevo y vacío sin fuente
"Crear instancia" en la nube gestionada	Sin acceso al host	Necesita control a nivel de sistema de archivos

Preguntas Frecuentes

¿Qué es PGDATA y qué es una base de datos?

PGDATA es un clúster (instancia). Un clúster contiene muchas bases de datos (postgres, myapp, etc.). Un proceso postgres gestiona un PGDATA.

¿Puedo mover PGDATA después de init?

Sí, con cuidado: detenga el servidor, mueva el directorio, actualice Environment=PGDATA= en systemd, o use pg_ctl -D. No mueva archivos en vivo mientras el servidor se ejecuta.

¿Por qué chmod 700?

Los archivos de catálogo contienen metadatos del esquema e información de conexión. Los directorios de datos legibles por todos son un hallazgo en auditorías de seguridad.

¿Debo usar --data-checksums?

Sí, para nuevos clústeres de producción. Un pequeño costo de CPU permite la detección temprana de corrupción silenciosa del almacenamiento.

¿Dónde va WAL con --waldir?

Los segmentos WAL viven bajo la ruta que pasa a --waldir, enlazados simbólicamente desde $PGDATA/pg_wal. Ambas rutas deben estar disponibles al inicio.

Relacionado

Conceptos Básicos de Instalación - instalaciones de paquetes antes de initdb
Esenciales de postgresql.conf - ajustar después del primer arranque
pg_hba.conf y Autenticación - permitir conexiones
Systemd y Gestión de Servicios - iniciar el nuevo clúster

Versiones de la Pila: Esta página fue escrita para PostgreSQL 18.4 (estable 18, mantenimiento 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, y PostGIS 3.5+.

initdb y el Directorio de Datos

Buscar en la documentación

initdb y el Directorio de Datos