pg_restore: restaure una base de datos PostgreSQL desde un archivo de almacenamiento creado por pg_dump

Sinopsis

pg_restore [connection-option…] [option…] [filename]

Descripción

pg_restore es una utilidad para restaurar una base de datos PostgreSQL a partir de un archivo creado por pg_dump en uno de los formatos que no son de texto sin formato. Emitirá los comandos necesarios para reconstruir la base de datos al estado en el que se encontraba en el momento en que se guardó. Los archivos de almacenamiento también permiten que pg_restore sea selectivo sobre lo que se restaura, o incluso que reordene los elementos antes de restaurarlos. Los archivos de almacenamiento están diseñados para ser portátiles entre arquitecturas.

pg_restore puede funcionar en dos modos. Si se especifica un nombre de base de datos, pg_restore se conecta a esa base de datos y restaura el contenido del archivo directamente en la base de datos. De lo contrario, se crea un script que contiene los comandos SQL necesarios para reconstruir la base de datos y se escribe en un archivo o salida estándar. Esta salida de script es equivalente al formato de salida de texto sin formato de pg_dump. Algunas de las opciones que controlan la salida son, por tanto, análogas a las opciones pg_dump.

Obviamente, pg_restore no puede restaurar información que no está presente en el archivo de almacenamiento. Por ejemplo, si el archivo se creó utilizando el volcar datos como INSERT comandos opción, pg_restore no podrá cargar los datos usando COPY declaraciones.

Opciones

pg_restore acepta los siguientes argumentos de línea de comando.

filename

Especifica la ubicación del archivo de almacenamiento (o directorio, para un archivo de formato de directorio) que se va a restaurar. Si no se especifica, se utiliza la entrada estándar.

-a--data-only

Restaurar solo los datos, no el esquema (definiciones de datos). Los datos de la tabla, los objetos grandes y los valores de secuencia se restauran, si están presentes en el archivo.

Esta opción es similar, pero por razones históricas no idénticas a, especificar --section=data.

-c--clean

Limpie (elimine) los objetos de la base de datos antes de volver a crearlos. (A no ser que --if-exists se utiliza, esto podría generar algunos mensajes de error inofensivos, si algún objeto no estuviera presente en la base de datos de destino).

-C--create

Cree la base de datos antes de restaurarla. Si --clean también se especifica, elimine y vuelva a crear la base de datos de destino antes de conectarse a ella.

Con --create, pg_restore también restaura el comentario de la base de datos, si lo hay, y cualquier configuración de variable de configuración que sea específica de esta base de datos, es decir, cualquier ALTER DATABASE ... SET ... y ALTER ROLE ... IN DATABASE ... SET ... comandos que mencionan esta base de datos. Los privilegios de acceso a la propia base de datos también se restauran, a menos que --no-acl está especificado.

Cuando se usa esta opción, la base de datos nombrada con -d se utiliza solo para emitir la inicial DROP DATABASE y CREATE DATABASE comandos. Todos los datos se restauran en el nombre de la base de datos que aparece en el archivo.

-d dbname--dbname=dbname

Conectarse a la base de datos dbname y restaurar directamente a la base de datos. los dbname puede ser un Cadena de conexión. Si es así, los parámetros de la cadena de conexión anularán cualquier opción de línea de comando en conflicto.

-e--exit-on-error

Salga si se encuentra un error al enviar comandos SQL a la base de datos. El valor predeterminado es continuar y mostrar un recuento de errores al final de la restauración.

-f filename--file=filename

Especifique el archivo de salida para la secuencia de comandos generada o para la lista cuando se usa con -l. Usar - por stdout.

-F format--format=format

Especifique el formato del archivo. No es necesario especificar el formato, ya que pg_restore determinará el formato automáticamente. Si se especifica, puede ser uno de los siguientes:

ccustom

El archivo tiene el formato personalizado de pg_dump.

ddirectory

El archivo es un archivo de directorio.

ttar

El archivo es un tar archivo.

-I index--index=index

Restaurar la definición del índice con nombre solamente. Se pueden especificar varios índices con múltiples -I interruptores.

-j number-of-jobs--jobs=number-of-jobs

Ejecute los pasos de pg_restore que consumen más tiempo (los que cargan datos, crean índices o crean restricciones) al mismo tiempo, utilizando hasta number-of-jobs sesiones concurrentes. Esta opción puede reducir drásticamente el tiempo necesario para restaurar una base de datos grande en un servidor que se ejecuta en una máquina multiprocesador. Esta opción se ignora cuando se emite un script en lugar de conectarse directamente a un servidor de base de datos.

Cada trabajo es un proceso o un subproceso, según el sistema operativo, y utiliza una conexión separada al servidor.

El valor óptimo para esta opción depende de la configuración del hardware del servidor, del cliente y de la red. Los factores incluyen el número de núcleos de CPU y la configuración del disco. Un buen lugar para comenzar es la cantidad de núcleos de CPU en el servidor, pero valores mayores que eso también pueden conducir a tiempos de restauración más rápidos en muchos casos. Por supuesto, los valores demasiado altos provocarán una disminución del rendimiento debido a la paliza.

Solo los formatos de archivo personalizados y de directorio son compatibles con esta opción. La entrada debe ser un archivo o directorio normal (no, por ejemplo, una tubería o una entrada estándar). Además, no se pueden utilizar varios trabajos junto con la opción --single-transaction.

-l--list

Enumere la tabla de contenido del archivo. La salida de esta operación se puede utilizar como entrada al -L opción. Tenga en cuenta que si se filtran conmutadores como -n o -t se usan con -l, restringirán los elementos enumerados.

-L list-file--use-list=list-file

Restaurar solo los elementos de archivo que se enumeran en list-filey restaurarlos en el orden en que aparecen en el archivo. Tenga en cuenta que si se filtran conmutadores como -n o -t se usan con -L, restringirán aún más los elementos restaurados.

list-file normalmente se crea editando la salida de una -l operación. Las líneas se pueden mover o eliminar, y también se pueden comentar colocando un punto y coma (;) al principio de la línea. Consulte los ejemplos a continuación.

-n schema--schema=schema

Restaurar solo los objetos que están en el esquema nombrado. Se pueden especificar varios esquemas con múltiples -n interruptores. Esto se puede combinar con el -t opción para restaurar solo una tabla específica.

-N schema--exclude-schema=schema

No restaure objetos que estén en el esquema nombrado. Se pueden especificar varios esquemas para excluir con múltiples -N interruptores.

Cuando ambos -n y -N se dan para el mismo nombre de esquema, los -N Switch gana y el esquema se excluye.

-O--no-owner

No genere comandos para establecer la propiedad de los objetos para que coincidan con la base de datos original. De forma predeterminada, problemas de pg_restore ALTER OWNER o SET SESSION AUTHORIZATION declaraciones para establecer la propiedad de los elementos de esquema creados. Estas declaraciones fallarán a menos que la conexión inicial a la base de datos la realice un superusuario (o el mismo usuario que posee todos los objetos en el script). Con -O, se puede utilizar cualquier nombre de usuario para la conexión inicial, y este usuario será el propietario de todos los objetos creados.

-P function-name(argtype [, ...])--function=function-name(argtype [, ...])

Restaurar solo la función nombrada. Tenga cuidado de escribir el nombre de la función y los argumentos exactamente como aparecen en la tabla de contenido del archivo de volcado. Se pueden especificar varias funciones con múltiples -P interruptores.

-R--no-reconnect

Esta opción es obsoleta pero aún se acepta por compatibilidad con versiones anteriores.

-s--schema-only

Restaure solo el esquema (definiciones de datos), no los datos, en la medida en que las entradas del esquema estén presentes en el archivo.

Esta opción es la inversa de --data-only. Es similar, pero por razones históricas no idénticas a, especificar --section=pre-data --section=post-data.

(No confunda esto con el --schema opción, que usa la palabra esquema en un significado diferente.)

-S username--superuser=username

Especifique el nombre de usuario de superusuario que se utilizará al deshabilitar los activadores. Esto es relevante solo si --disable-triggers se utiliza.

-t table--table=table

Restaurar la definición y / o los datos de solo la tabla nombrada. Para este propósito, mesa incluye vistas, vistas materializadas, secuencias y tablas externas. Se pueden seleccionar varias tablas escribiendo varias -t interruptores. Esta opción se puede combinar con la -n opción para especificar tablas en un esquema particular.

Nota

Cuando -t se especifica, pg_restore no intenta restaurar ningún otro objeto de la base de datos de los que puedan depender las tablas seleccionadas. Por lo tanto, no hay garantía de que la restauración de una tabla específica en una base de datos limpia se realice correctamente.

Nota

Esta bandera no se comporta de manera idéntica a la -t bandera de pg_dump. Actualmente no existe ninguna disposición para la coincidencia de comodines en pg_restore, ni puede incluir un nombre de esquema dentro de su -t. Y, mientras pg_dump’s -t flag también volcará objetos subsidiarios (como índices) de la (s) tabla (s) seleccionada (s), pg_restore’s -t bandera no incluye tales objetos subsidiarios.

Nota

En versiones anteriores a PostgreSQL 9.6, este indicador solo coincidía con tablas, no con ningún otro tipo de relación.

-T trigger--trigger=trigger

Restaurar solo el disparador con nombre. Se pueden especificar varios disparadores con varios -T interruptores.

-v--verbose

Especifica el modo detallado.

-V--version

Imprima la versión de pg_restore y salga.

-x--no-privileges--no-acl

Evitar la restauración de los privilegios de acceso (otorgar / revocar comandos).

-1--single-transaction

Ejecute la restauración como una sola transacción (es decir, envuelva los comandos emitidos en BEGIN/COMMIT). Esto asegura que todos los comandos se completen correctamente o que no se apliquen cambios. Esta opción implica --exit-on-error.

--disable-triggers

Esta opción es relevante solo cuando se realiza una restauración de solo datos. Indica a pg_restore que ejecute comandos para deshabilitar temporalmente los activadores en las tablas de destino mientras se recargan los datos. Use esto si tiene verificaciones de integridad referencial u otros activadores en las tablas que no desea invocar durante la recarga de datos.

Actualmente, los comandos emitidos por --disable-triggers debe hacerse como superusuario. Por lo tanto, también debe especificar un nombre de superusuario con -S o, preferiblemente, ejecute pg_restore como superusuario de PostgreSQL.

--enable-row-security

Esta opción es relevante solo cuando se restaura el contenido de una tabla que tiene seguridad de fila. De forma predeterminada, pg_restore desactivará row_security para garantizar que todos los datos se restauren en la tabla. Si el usuario no tiene suficientes privilegios para omitir la seguridad de la fila, se genera un error. Este parámetro indica a pg_restore que establezca row_security en on en su lugar, lo que permite al usuario intentar restaurar el contenido de la tabla con la seguridad de fila habilitada. Esto aún podría fallar si el usuario no tiene derecho a insertar las filas del volcado en la tabla.

Tenga en cuenta que esta opción actualmente también requiere que el volcado esté en INSERT formato, como COPY FROM no es compatible con la seguridad de filas.

--if-exists

Use comandos condicionales (es decir, agregue un IF EXISTS cláusula) para eliminar objetos de la base de datos. Esta opción no es válida a menos que --clean también se especifica.

--no-comments

No genere comandos para restaurar comentarios, incluso si el archivo los contiene.

--no-data-for-failed-tables

De forma predeterminada, los datos de la tabla se restauran incluso si el comando de creación de la tabla falla (por ejemplo, porque ya existe). Con esta opción, se omiten los datos de dicha tabla. Este comportamiento es útil si la base de datos de destino ya contiene el contenido de la tabla deseado. Por ejemplo, es posible que las tablas auxiliares para extensiones de PostgreSQL como PostGIS ya estén cargadas en la base de datos de destino; especificar esta opción evita que se carguen en ellos datos duplicados u obsoletos.

Esta opción es efectiva solo cuando se restaura directamente en una base de datos, no cuando se genera una salida de script SQL.

--no-publications

No genere comandos para restaurar publicaciones, incluso si el archivo los contiene.

--no-security-labels

No envíe comandos para restaurar etiquetas de seguridad, incluso si el archivo las contiene.

--no-subscriptions

No genere comandos para restaurar suscripciones, incluso si el archivo las contiene.

--no-tablespaces

No genere comandos para seleccionar espacios de tabla. Con esta opción, todos los objetos se crearán en el espacio de tabla que sea el predeterminado durante la restauración.

--section=sectionname

Solo restaure la sección nombrada. El nombre de la sección puede ser pre-data, data, o post-data. Esta opción se puede especificar más de una vez para seleccionar varias secciones. El valor predeterminado es restaurar todas las secciones.

La sección de datos contiene datos reales de la tabla, así como definiciones de objetos grandes. Los elementos posteriores a los datos consisten en definiciones de índices, desencadenantes, reglas y restricciones distintas de las restricciones de verificación validadas. Los elementos de datos previos constan de todos los demás elementos de definición de datos.

--strict-names

Exija que cada esquema (-n/--schema) y mesa (-t/--table) calificador coincide con al menos un esquema / tabla en el archivo de respaldo.

--use-set-session-authorization

Salida estándar SQL SET SESSION AUTHORIZATION comandos en lugar de ALTER OWNER comandos para determinar la propiedad del objeto. Esto hace que el volcado sea más compatible con los estándares, pero dependiendo del historial de los objetos en el volcado, es posible que no se restaure correctamente.

-?--help

Muestre ayuda sobre los argumentos de la línea de comando pg_restore y salga.

pg_restore también acepta los siguientes argumentos de línea de comando para los parámetros de conexión:

-h host--host=host

Especifica el nombre de host de la máquina en la que se ejecuta el servidor. Si el valor comienza con una barra, se usa como directorio para el socket de dominio Unix. El valor predeterminado se toma del PGHOST variable de entorno, si se establece, de lo contrario, se intentará una conexión de socket de dominio Unix.

-p port--port=port

Especifica el puerto TCP o la extensión del archivo del socket del dominio Unix local en el que el servidor está escuchando las conexiones. Por defecto es PGPORT variable de entorno, si se establece, o un valor predeterminado compilado.

-U username--username=username

Nombre de usuario para conectarse como.

-w--no-password

Nunca emita una solicitud de contraseña. Si el servidor requiere autenticación de contraseña y una contraseña no está disponible por otros medios, como .pgpass archivo, el intento de conexión fallará. Esta opción puede ser útil en trabajos por lotes y scripts donde no hay ningún usuario presente para ingresar una contraseña.

-W--password

Obligar a pg_restore a solicitar una contraseña antes de conectarse a una base de datos.

Esta opción nunca es esencial, ya que pg_restore solicitará automáticamente una contraseña si el servidor exige autenticación de contraseña. Sin embargo, pg_restore desperdiciará un intento de conexión al descubrir que el servidor quiere una contraseña. En algunos casos vale la pena escribir -W para evitar el intento de conexión adicional.

--role=rolename

Especifica un nombre de rol que se utilizará para realizar la restauración. Esta opción hace que pg_restore emita un SET ROLErolename comando después de conectarse a la base de datos. Es útil cuando el usuario autenticado (especificado por -U) carece de los privilegios necesarios para pg_restore, pero puede cambiar a un rol con los derechos necesarios. Algunas instalaciones tienen una política contra el inicio de sesión directamente como superusuario, y el uso de esta opción permite realizar restauraciones sin violar la política.

Medio ambiente

PGHOSTPGOPTIONSPGPORTPGUSER

Parámetros de conexión predeterminados

PG_COLOR

Especifica si se debe utilizar color en los mensajes de diagnóstico. Los valores posibles son always, auto y never.

Esta utilidad, como la mayoría de las otras utilidades de PostgreSQL, también usa las variables de entorno admitidas por libpq (consulte Sección 33.14). Sin embargo, no lee PGDATABASE cuando no se proporciona un nombre de base de datos.

Diagnósticos

Cuando se especifica una conexión de base de datos directa utilizando el -d opción, pg_restore ejecuta internamente sentencias SQL. Si tiene problemas para ejecutar pg_restore, asegúrese de poder seleccionar información de la base de datos utilizando, por ejemplo, psql. Además, se aplicarán las configuraciones de conexión predeterminadas y las variables de entorno utilizadas por la biblioteca front-end libpq.

Notas

Si su instalación tiene adiciones locales al template1 base de datos, tenga cuidado de cargar la salida de pg_restore en una base de datos realmente vacía; de lo contrario, es probable que obtenga errores debido a definiciones duplicadas de los objetos agregados. Para crear una base de datos vacía sin adiciones locales, copie de template0 no template1, por ejemplo:

CREATEDATABASE foo WITH TEMPLATE template0;

Las limitaciones de pg_restore se detallan a continuación.

  • Al restaurar datos a una tabla preexistente y la opción --disable-triggers se utiliza, pg_restore emite comandos para deshabilitar los activadores en las tablas de usuario antes de insertar los datos, luego emite comandos para volver a habilitarlos después de que se hayan insertado los datos. Si la restauración se detiene a la mitad, es posible que los catálogos del sistema se dejen en un estado incorrecto.

  • pg_restore no puede restaurar objetos grandes de forma selectiva; por ejemplo, solo los de una tabla específica. Si un archivo contiene objetos grandes, se restaurarán todos los objetos grandes, o ninguno de ellos si se excluyen mediante -L, -tu otras opciones.

Consulte también la documentación de pg_dump para obtener detalles sobre las limitaciones de pg_dump.

Una vez restaurado, es aconsejable ejecutar ANALYZE en cada tabla restaurada para que el optimizador tenga estadísticas útiles; consulte la Sección 24.1.3 y la Sección 24.1.6 para obtener más información.

Ejemplos de

Supongamos que hemos descargado una base de datos llamada mydb en un archivo de volcado de formato personalizado:

$ pg_dump -Fc mydb > db.dump

Para eliminar la base de datos y volver a crearla desde el volcado:

$ dropdb mydb
$ pg_restore -C -d postgres db.dump

La base de datos nombrada en el -d switch puede ser cualquier base de datos existente en el clúster; pg_restore solo lo usa para emitir el CREATE DATABASE comando para mydb. Con -C, los datos siempre se restauran en el nombre de la base de datos que aparece en el archivo de volcado.

Para volver a cargar el volcado en una nueva base de datos llamada newdb:

$ createdb -T template0 newdb
$ pg_restore -d newdb db.dump

Tenga en cuenta que no usamos -Cy, en su lugar, conéctese directamente a la base de datos en la que se restaurará. También tenga en cuenta que clonamos la nueva base de datos de template0 no template1, para asegurarse de que inicialmente esté vacío.

Para reordenar los elementos de la base de datos, primero es necesario volcar la tabla de contenido del archivo:

$ pg_restore -l db.dump > db.list

El archivo de listado consta de un encabezado y una línea para cada artículo, por ejemplo:

;; Archive created at Mon Sep 1413:55:392009;     dbname: DBDEMOS
;     TOC Entries: 81;     Compression: 9;Dump Version: 1.10-0;     Format: CUSTOM
;Integer: 4 bytes
;Offset: 8 bytes
;     Dumped fromdatabase version: 8.3.5;     Dumped by pg_dump version: 8.3.8;;; Selected TOC Entries:
;3;26152200SCHEMA-public pasha
1861;00COMMENT-SCHEMApublic pasha
1862;00 ACL -public pasha
317;124717715TYPEpublic composite pasha
319;124725899 DOMAIN public domain0 pasha

Los puntos y comas comienzan un comentario y los números al comienzo de las líneas se refieren al ID de archivo interno asignado a cada elemento.

Las líneas del archivo se pueden comentar, eliminar y reordenar. Por ejemplo:

10;145433TABLE map_resolutions postgres
;2;145344TABLE species postgres
;4;145359TABLE nt_header postgres
6;145402TABLE species_records postgres
;8;145416TABLE ss_old postgres

podría usarse como entrada para pg_restore y solo restauraría los elementos 10 y 6, en ese orden:

$ pg_restore -L db.list db.dump

Ver también

pg_dump, pg_dumpall, psql

Anterior Hasta próximo
pg_recvlogical Hogar pg_verifybackup