pg_restore PostgreSQL: Restaurar Dumps y Errores

Restaurar una base de datos PostgreSQL es una operación crítica, a menudo subestimada hasta el momento de la necesidad. Un respaldo es efectivo solo si la restauración se realiza sin problemas y dentro de los plazos estipulados por los SLA. El comando pg_restore es la herramienta fundamental para gestionar los dumps creados con pg_dump, ofreciendo flexibilidad y control sobre el proceso. Ya sea una restauración completa después de un desastre, una recuperación granular de una sola tabla, o la migración de datos entre diferentes entornos, pg_restore es tu aliado. Sin embargo, no es raro encontrarse con errores comunes como ‘role does not exist’ o problemas de incompatibilidad de versión, que pueden transformar una operación rutinaria en una carrera contra el tiempo. Comprender los diferentes formatos de dump, las opciones de restauración y las estrategias para resolver los problemas más frecuentes es esencial para cualquier DBA o SysAdmin que gestione entornos PostgreSQL. Esta guía te proporcionará el conocimiento práctico para afrontar con seguridad la restauración de tus bases de datos.

Tested on: PostgreSQL 16.1 · Ubuntu 24.04 LTS · Octubre 2026

Requisitos Previos / Entorno de Prueba

Antes de empezar, asegúrate de tener:

• Un servidor PostgreSQL instalado y funcionando (versión 12 o superior recomendada).
• El cliente pg_restore instalado en la máquina desde la que ejecutas la restauración. Forma parte del paquete postgresql-client.
• Un dump de base de datos creado con pg_dump en formato custom, directory o tar. Los dumps en formato SQL (plain text) deben restaurarse con el comando psql.
• Credenciales de un usuario con privilegios suficientes para crear bases de datos y objetos (típicamente postgres o un superuser).

Formato custom, directory o SQL: qué se restaura con qué

pg_dump puede generar backups en diferentes formatos, cada uno con sus peculiaridades y su herramienta de restauración preferida:

• Formato custom (-Fc): Este es el formato más flexible y recomendado para pg_dump. Está comprimido por defecto y permite la restauración selectiva de tablas, esquemas u otros objetos. Requiere pg_restore.
• Formato directory (-Fd): Similar al formato custom, pero el backup se guarda como un directorio que contiene varios archivos. Es útil para backups muy grandes y soporta la restauración paralela. Requiere pg_restore.
• Formato tar (-Ft): Un archivo tar. También soporta la restauración selectiva, pero es menos flexible que el formato custom para la gestión de metadatos. Requiere pg_restore.
• Formato plain text (SQL): Este es un simple script SQL que recrea la base de datos. No está comprimido por defecto y no permite una restauración selectiva sin modificaciones manuales. Debe restaurarse con psql.

Para verificar el contenido de un dump (por ejemplo, para ver qué tablas o esquemas contiene), puedes usar la opción -l (list) con pg_restore:

pg_restore -l backup.dump | head

Esto te mostrará las primeras líneas del contenido del dump, útil para entender qué se ha guardado y cómo proceder con una restauración granular.

Restaurar en una base de datos nueva

La forma más limpia de restaurar un dump es crear una nueva base de datos vacía y luego restaurar el contenido en ella. Esto evita conflictos con objetos preexistentes.

Primero, crea una nueva base de datos. Asegúrate de especificar el propietario (-O) correcto, que será el usuario que utilizará la base de datos:

createdb -O app appdb

Ahora puedes ejecutar la restauración en la base de datos appdb. La opción -d especifica la base de datos de destino:

pg_restore -d appdb backup.dump

Lee también: Oracle RMAN: Recuperar Base de Datos Tras Fallo

Sobreescribir una base de datos existente (–clean –if-exists)

A veces es necesario sobrescribir una base de datos existente, por ejemplo, para actualizar un entorno de staging con datos de producción. En este caso, puedes usar las opciones --clean y --if-exists.

• --clean: Elimina todos los objetos (tablas, índices, funciones, etc.) dentro de la base de datos de destino antes de restaurar.
• --if-exists: Añadido a --clean, asegura que DROP se ejecute solo si el objeto existe, evitando errores. Es útil en combinación con --clean.

pg_restore -d appdb --clean --if-exists backup.dump

ATENCIÓN: Esta operación es destructiva. Asegúrate de tener un backup de la base de datos appdb antes de proceder, especialmente en entornos de producción.

Acelerar con la restauración paralela

Para bases de datos de gran tamaño, una restauración secuencial puede llevar horas. pg_restore soporta la restauración paralela mediante la opción -j (jobs), que especifica el número de hilos de trabajo a utilizar. Esto es particularmente efectivo con dumps en formato directory o custom.

Un buen punto de partida es establecer el número de jobs igual al número de núcleos de la CPU del servidor, o ligeramente inferior para no sobrecargarlo.

pg_restore -d appdb -j 4 backup.dump

Este comando usará 4 hilos para restaurar la base de datos appdb, reduciendo significativamente el tiempo total.

Restaurar una sola tabla o un solo esquema

Una de las mayores ventajas de los formatos custom y directory es la posibilidad de restaurar solo una parte de la base de datos. Esto es muy útil para recuperar datos específicos o para probar modificaciones en un subconjunto de la base de datos.

Para restaurar una sola tabla (ej. clientes):

pg_restore -d appdb -t clientes backup.dump

Para restaurar un esquema completo (ej. ventas):

pg_restore -d appdb -n ventas backup.dump

Puedes especificar múltiples opciones -t o -n para incluir más objetos.

Error ‘role does not exist’ y permisos

El error ERROR: role "nombre_usuario" does not exist es uno de los más comunes durante la restauración. Se produce cuando el dump incluye información sobre el propietario de la base de datos o de los objetos (tablas, funciones, etc.), pero el rol especificado no existe en el servidor de destino.

Las soluciones son dos:

1. Crear el rol faltante: Si el rol nombre_usuario debe existir, créalo en el servidor PostgreSQL de destino con CREATE ROLE nombre_usuario WITH LOGIN PASSWORD 'password';.
2. Ignorar propietarios y privilegios: Si no es crucial mantener los mismos propietarios y permisos de la base de datos original, puedes usar las opciones --no-owner y --no-privileges (o --no-acl).

pg_restore -d appdb --no-owner --no-privileges backup.dump

Esta solución es a menudo la más rápida para restauraciones en entornos de desarrollo o prueba, donde la réplica exacta de los permisos no es fundamental. Después de la restauración, deberás asignar los permisos correctos al nuevo propietario o a los roles deseados.

Error de versión entre dump y servidor

Otro problema frecuente es la incompatibilidad de versión entre el servidor desde el que se hizo el dump y aquel en el que se intenta la restauración. Por ejemplo, un dump de PostgreSQL 16 podría no ser restaurable en PostgreSQL 12 debido a diferencias en el esquema del catálogo o en las funcionalidades.

pg_restore es generalmente retrocompatible (un dump de una versión más antigua puede restaurarse en una más nueva), pero la compatibilidad inversa no está garantizada. Si encuentras errores relacionados con la versión, la mejor solución es:

1. Usar la misma versión: Ejecuta la restauración en un servidor PostgreSQL de la misma versión o más reciente que el servidor desde el que se generó el dump.
2. Ignorar la versión (con precaución): En casos específicos y no críticos, puedes probar la opción --ignore-version. Sin embargo, esta opción puede llevar a una base de datos inconsistente si las diferencias de versión son significativas.

pg_restore -d appdb --ignore-version backup.dump

Usa --ignore-version solo si has comprendido los riesgos y no es un entorno de producción. Siempre es preferible tener una correspondencia de versión o una ruta de actualización bien probada.

Verificar la restauración

Después de ejecutar pg_restore, es fundamental verificar que la restauración se haya realizado correctamente y que la base de datos esté íntegra y accesible. Algunos controles rápidos incluyen:

• Conexión a la base de datos: Intenta conectarte a la base de datos con psql o un cliente gráfico.
• Conteo de tablas/registros: Verifica que el número de tablas y, para algunas tablas clave, el número de registros coincida con las expectativas.

psql -d appdb -c '\dt+'

Este comando lista todas las tablas en la base de datos appdb con sus detalles. También puedes ejecutar consultas SELECT COUNT(*) en tablas específicas para verificar la presencia de los datos.

Errores Comunes y Resolución de Problemas

• Permisos insuficientes: Si pg_restore falla con errores de acceso o creación, asegúrate de que el usuario que ejecuta el comando tenga privilegios de superuser o al menos los permisos para crear bases de datos y objetos dentro de la base de datos de destino.
• Espacio en disco insuficiente: Una restauración puede fallar si el servidor de destino no tiene suficiente espacio en disco para contener la base de datos restaurada. Controla el espacio disponible antes de empezar.
• Archivo de dump corrupto: Si el archivo backup.dump está dañado o incompleto, pg_restore fallará. Asegúrate de que el archivo esté íntegro (por ejemplo, controlando el hash del archivo si está disponible).
• Conexión de red interrumpida: Para restauraciones en servidores remotos, una conexión inestable puede causar fallos. Asegúrate de tener una conexión de red estable.

FAQ — Preguntas Frecuentes

¿Puedo restaurar un dump pg_dump en una base de datos con un nombre diferente?

Sí, puedes restaurar un dump en una base de datos con un nombre diferente al de la base de datos original. Lo importante es especificar el nombre de la base de datos de destino con la opción -d (por ejemplo, pg_restore -d nueva_db_nombre backup.dump). Solo asegúrate de que la base de datos nueva_db_nombre haya sido creada previamente.

¿Es posible restaurar solo los datos sin el esquema?

Sí, pg_restore ofrece las opciones --data-only para restaurar solo los datos y --schema-only para restaurar solo el esquema. Estas son muy útiles para escenarios específicos como la carga de datos en un esquema preexistente o la creación de una base de datos de prueba vacía.

¿Cuál es la diferencia entre pg_restore y psql para la restauración?

pg_restore se utiliza para los dumps en formato custom, directory o tar, que son formatos binarios y comprimidos. Ofrece mayor flexibilidad como la restauración selectiva y paralela. psql se usa para restaurar dumps en formato plain text (SQL), que son simples scripts SQL. psql ejecuta el script secuencialmente y no ofrece las mismas opciones de restauración selectiva.

¿Debo detener la base de datos durante la restauración?

No es necesario detener todo el servidor PostgreSQL. Sin embargo, es buena práctica asegurarse de que no haya conexiones activas a la base de datos de destino durante la restauración, especialmente si estás sobrescribiendo una base de datos existente. Puedes bloquear las conexiones con ALTER DATABASE appdb CONNECTION LIMIT 0; y volver a habilitarlas después de la restauración.

¿Cómo puedo restaurar un solo registro o una fila específica?

pg_restore no soporta la restauración de registros individuales. Si necesitas restaurar un número limitado de filas, la mejor solución es restaurar la tabla completa en una base de datos temporal y luego extraer las filas deseadas mediante consultas SQL (INSERT INTO ... SELECT ... WHERE).

Conclusiones con Puntos Clave Operativos

La gestión efectiva de los backups y las restauraciones de PostgreSQL es una habilidad fundamental. pg_restore es una herramienta potente y flexible que, una vez comprendida, puede ahorrar horas de trabajo y reducir el downtime en situaciones críticas. Recuerda siempre:

1. Elegir el formato de dump correcto según tus necesidades de flexibilidad y rendimiento de restauración.
2. Probar regularmente tus restauraciones para asegurarte de que los backups sean válidos y que el procedimiento funcione como se espera. Cuando migré 300 VMs a Proxmox para una organización sanitaria pública, la validación de cada paso fue clave.
3. Utilizar la restauración paralela (-j N) para reducir los tiempos de recuperación en bases de datos de gran tamaño.
4. Ser consciente de las opciones --no-owner, --no-privileges e --ignore-version para resolver los errores comunes, pero úsalas con conocimiento de causa.
5. Verificar la integridad de la base de datos después de cada restauración con consultas de control y conteos de registros.

Implementando estas prácticas, podrás gestionar tus bases de datos PostgreSQL con mayor seguridad y reactividad, garantizando la continuidad operativa incluso frente a imprevistos.

Fuentes

• PostgreSQL Documentation: pg_restore

Actualizado: Octubre 2026