pg_ctl — inicializa, inicia, detiene o controla un servidor de PostgreSQL
pg_ctl init[db] [-D datadir] [-s] [-o initdb-options]
pg_ctl start [-D datadir] [-l filename] [-W] [-t seconds] [-s] [-o options] [-p path] [-c]
pg_ctl stop [-D datadir] [-m
s[mart] | f[ast] | i[mmediate]
] [-W] [-t seconds] [-s]
pg_ctl restart [-D datadir] [-m
s[mart] | f[ast] | i[mmediate]
] [-W] [-t seconds] [-s] [-o options] [-c]
pg_ctl reload [-D datadir] [-s]
pg_ctl status [-D datadir]
pg_ctl promote [-D datadir] [-W] [-t seconds] [-s]
pg_ctl logrotate [-D datadir] [-s]
pg_ctl kill signal_name process_id
En Microsoft Windows, también:
pg_ctl register [-D datadir] [-N servicename] [-U username] [-P password] [-S
a[uto] | d[emand]
] [-e source] [-W] [-t seconds] [-s] [-o options]
pg_ctl unregister [-N servicename]
pg_ctl es una utilidad para inicializar un clúster de bases de datos PostgreSQL, iniciar, detener o reiniciar el servidor de bases de datos PostgreSQL (postgres), o mostrar el estado de un servidor en ejecución. Aunque el servidor se puede iniciar manualmente, pg_ctl encapsula tareas como redirigir la salida del registro y desvincularse correctamente de la terminal y del grupo de procesos. También proporciona opciones convenientes para un apagado controlado.
El modo init o initdb crea un nuevo
PostgreSQL base de datos clúster, es decir,
una colección de bases de datos que serán gestionadas por una sola
instancia de servidor. Este modo invoca el comando initdb.
Consulta initdb para obtener más detalles.
El modo start inicia un nuevo servidor. El
servidor se inicia en segundo plano y su entrada estándar se vincula
a /dev/null (o nul en Windows).
En sistemas tipo Unix, por defecto, la salida estándar y el error estándar
del servidor se envían a la salida estándar de pg_ctl
(no al error estándar). La salida estándar de
pg_ctl debe entonces redirigirse a un
archivo o enviarse a través de una tubería a otro proceso, como un programa
de rotación de registros como rotatelogs; de lo contrario, postgres
escribirá su salida en la terminal de control (desde el
segundo plano) y no abandonará el grupo de procesos de la consola. En
Windows, por defecto, la salida estándar y el error estándar del servidor
se envían a la terminal. Estos comportamientos predeterminados se pueden cambiar
utilizando -l para agregar la salida del servidor a un archivo de registro.
Se recomienda el uso de -l o de la redirección de salida.
El modo stop apaga el servidor que se está ejecutando en
el directorio de datos especificado. Se pueden seleccionar tres métodos de
apagado diferentes con la opción -m. El modo “Smart”
(inteligente) no permite nuevas conexiones, luego espera a que todos los clientes
existentes se desconecten. Si el servidor está en modo de espera activa (hot standby),
la recuperación y la replicación en flujo se terminarán una vez que todos los clientes
se hayan desconectado. El modo “Fast” (rápido, el predeterminado) no espera a
que los clientes se desconecten. Todas las transacciones activas se
revierten y los clientes son desconectados a la fuerza, luego se apaga el
servidor. El modo “Immediate” (inmediato) abortará todos los
procesos del servidor inmediatamente, sin un apagado limpio. Esta opción
conducirá a un ciclo de recuperación de fallos (crash-recovery) durante el próximo inicio del servidor.
El modo restart ejecuta efectivamente un stop seguido
de un start. Esto permite cambiar las opciones de línea de comandos de postgres,
o cambiar las opciones del archivo de configuración que no se pueden cambiar sin reiniciar el servidor.
Si se utilizaron rutas relativas en la línea de comandos durante el inicio del servidor,
restart podría fallar a menos que
pg_ctl se ejecute en el mismo directorio de trabajo
en el que estaba durante el inicio del servidor.
El modo reload simplemente envía al proceso del servidor
postgres una señal SIGHUP,
haciendo que vuelva a leer sus archivos de configuración
(postgresql.conf,
pg_hba.conf, etc.). Esto permite cambiar las
opciones del archivo de configuración que no requieren un reinicio completo del servidor
para tener efecto.
El modo status comprueba si un servidor se está ejecutando en
el directorio de datos especificado. Si es así, se muestra el PID
del servidor y las opciones de línea de comandos que se utilizaron para invocarlo.
Si el servidor no se está ejecutando, pg_ctl devuelve
un estado de salida de 3. Si no se especifica un directorio de datos accesible,
pg_ctl devuelve un estado de salida de 4.
El modo promote ordena al servidor en espera (standby) que se está
ejecutando en el directorio de datos especificado que termine el modo de espera
y comience las operaciones de lectura y escritura.
El modo logrotate rota el archivo de registro del servidor.
Para obtener detalles sobre cómo utilizar este modo con herramientas externas de rotación de registros, consulta
Section 24.3.
El modo kill envía una señal a un proceso especificado.
Esto es principalmente valioso en Microsoft Windows,
que no tiene un comando kill integrado. Utiliza
--help para ver una lista de nombres de señales compatibles.
El modo register registra el servidor PostgreSQL
como un servicio del sistema en Microsoft Windows.
La opción -S permite la selección del tipo de inicio del servicio,
ya sea “auto” (iniciar el servicio automáticamente al iniciar el sistema)
o “demand” (iniciar el servicio a demanda).
El modo unregister elimina el registro de un servicio del sistema
en Microsoft Windows. Esto deshace los efectos del comando
register.
-c--core-filesIntenta permitir que las caídas del servidor produzcan archivos core, en las plataformas donde esto sea posible, eliminando cualquier límite de recursos blando (soft limit) impuesto a los archivos core. Esto es útil para la depuración o el diagnóstico de problemas al permitir obtener un rastreo de la pila (stack trace) de un proceso de servidor fallido.
-D datadir--pgdata=datadir
Especifica la ubicación en el sistema de archivos de los archivos de configuración de la base de datos. Si
se omite esta opción, se utiliza la variable de entorno
PGDATA.
-l filename--log=filename
Agrega la salida del registro del servidor a
filename. Si el archivo no
existe, se crea. Por defecto, solo el propietario del clúster puede
acceder al archivo de registro. Si el acceso de grupo está habilitado en el clúster,
los usuarios del mismo grupo que el propietario del clúster también pueden leerlo.
-m mode--mode=mode
Especifica el modo de apagado. mode
puede ser smart, fast o
immediate, o la primera letra de uno de
estos tres. Si se omite esta opción, el valor predeterminado es
fast.
-o options--options=options
Especifica las opciones que se pasarán directamente al comando
postgres.
-o se puede especificar varias veces, y se pasarán
todas las opciones proporcionadas.
Las opciones normalmente deben estar rodeadas por comillas simples o
dobles para garantizar que se pasen como un grupo.
-o initdb-options--options=initdb-options
Especifica las opciones que se pasarán directamente al comando
initdb.
-o se puede especificar varias veces, y se pasarán
todas las opciones proporcionadas.
Las opciones de initdb normalmente deben estar rodeadas por comillas simples o
dobles para garantizar que se pasen como un grupo.
-p path
Especifica la ubicación del ejecutable postgres.
Por defecto, el ejecutable postgres se toma del mismo
directorio que pg_ctl, o en su defecto, del directorio de instalación
predefinido. No es necesario utilizar esta
opción a menos que estés haciendo algo inusual y obtengas errores de
que no se encontró el ejecutable postgres.
En el modo init, esta opción especifica de manera análoga
la ubicación del ejecutable initdb.
-s--silentImprime solo errores, no mensajes informativos.
-t seconds--timeout=seconds
Especifica el número máximo de segundos a esperar cuando se espera que se complete
una operación (ver opción -w). El valor predeterminado es
el valor de la variable de entorno PGCTLTIMEOUT o, si
no está configurada, 60 segundos.
-V--versionImprime la versión de pg_ctl y termina.
-w--wait
Espera a que se complete la operación. Esto es compatible con los
modos start, stop,
restart, promote,
y register, y es el valor predeterminado para esos modos.
Al esperar, pg_ctl comprueba repetidamente el
archivo PID del servidor, durmiendo durante un corto período
de tiempo entre las comprobaciones. El inicio se considera completo cuando
el archivo PID indica que el servidor está listo para
aceptar conexiones. El apagado se considera completo cuando el servidor
elimina el archivo PID.
pg_ctl devuelve un código de salida basado en el
éxito del inicio o del apagado.
Si la operación no se completa dentro del tiempo de espera (ver
opción -t), entonces pg_ctl termina con
un estado de salida distinto de cero. Pero ten en cuenta que la operación podría continuar en
segundo plano y tener éxito finalmente.
-W--no-wait
No espera a que se complete la operación. Esto es lo opuesto a
la opción -w.
Si la espera está deshabilitada, se activa la acción solicitada, pero no hay información sobre su éxito. En ese caso, se tendría que utilizar el archivo de registro del servidor o un sistema de monitoreo externo para comprobar el progreso y el éxito de la operación.
En versiones anteriores de PostgreSQL, este era el comportamiento predeterminado excepto para
el modo stop.
-?--helpMuestra ayuda sobre los argumentos de línea de comandos de pg_ctl y termina.
Si se especifica una opción que es válida, pero no es relevante para el modo de operación seleccionado, pg_ctl la ignora.
-e source
Nombre de la fuente de eventos que utilizará pg_ctl
para registrar en el registro de eventos cuando se ejecute como un servicio de Windows. El
valor predeterminado es PostgreSQL. Ten en cuenta que esto solo controla
los mensajes enviados desde el propio pg_ctl; una vez
iniciado, el servidor utilizará la fuente de eventos especificada
por su parámetro event_source. En caso de que el servidor
falle muy temprano en el inicio, antes de que se haya establecido ese parámetro,
también podría registrar utilizando el nombre de fuente de eventos predeterminado
PostgreSQL.
-N servicename
Nombre del servicio del sistema a registrar. Este nombre se utilizará
tanto como el nombre del servicio como el nombre para mostrar.
El valor predeterminado es PostgreSQL.
-P passwordContraseña del usuario con el que se ejecutará el servicio.
-S start-type
Tipo de inicio del servicio del sistema. start-type puede
ser auto o demand, o
la primera letra de uno de estos dos. Si se omite esta opción,
auto es el valor predeterminado.
-U username
Nombre de usuario con el que se ejecutará el servicio. Para usuarios de dominio, utiliza el
formato DOMINIO\usuario.
PGCTLTIMEOUTLímite predeterminado del número de segundos a esperar cuando se espera que se complete el inicio o el apagado. Si no está configurada, el valor predeterminado es 60 segundos.
PGDATAUbicación predeterminada del directorio de datos.
La mayoría de los modos de pg_ctl requieren conocer la ubicación del directorio de datos;
por lo tanto, se requiere la opción -D
a menos que PGDATA esté configurada.
Para variables adicionales que afectan al servidor, consulta postgres.
postmaster.pidpg_ctl examina este archivo en el directorio de datos para determinar si el servidor se está ejecutando actualmente.
postmaster.optsSi este archivo existe en el directorio de datos,
pg_ctl (en modo restart)
pasará el contenido del archivo como opciones a
postgres, a menos que sea anulado
por la opción -o. El contenido de este archivo
también se muestra en el modo status.
Para iniciar el servidor, esperando hasta que el servidor acepte conexiones:
$pg_ctl start
Para iniciar el servidor utilizando el puerto 5433, y
ejecutándose sin fsync, utiliza:
$pg_ctl -o "-F -p 5433" start
Para detener el servidor, utiliza:
$pg_ctl stop
La opción -m permite controlar
cómo se apaga el servidor:
$pg_ctl stop -m smart
Reiniciar el servidor es casi equivalente a detener el
servidor e iniciarlo de nuevo, excepto que, por defecto,
pg_ctl guarda y reutiliza las opciones de línea de comandos que
se pasaron a la instancia que se ejecutaba anteriormente. Para reiniciar
el servidor utilizando las mismas opciones que antes, utiliza:
$pg_ctl restart
Pero si se especifica -o, eso reemplaza cualquier opción anterior.
Para reiniciar utilizando el puerto 5433, desactivando fsync al reiniciar:
$pg_ctl -o "-F -p 5433" restart
Aquí hay un ejemplo de salida de estado de pg_ctl:
$pg_ctl statuspg_ctl: server is running (PID: 13718) /usr/local/pgsql/bin/postgres "-D" "/usr/local/pgsql/data" "-p" "5433" "-B" "128"
La segunda línea es el comando que se invocaría en el modo de reinicio.