Cuando encuentres un error en PostgreSQL, queremos saberlo. Tus reportes de errores juegan un papel importante para hacer que PostgreSQL sea más confiable, porque incluso el mayor cuidado no puede garantizar que cada parte de PostgreSQL funcione en cada plataforma bajo cualquier circunstancia.
Las siguientes sugerencias están destinadas a ayudarte a redactar reportes de errores que puedan ser manejados de manera efectiva. Nadie está obligado a seguirlas, pero hacerlo suele ser beneficioso para todos.
No podemos prometer solucionar cada error de inmediato. Si el error es obvio, crítico o afecta a muchos usuarios, hay muchas probabilidades de que alguien lo investigue. También podría suceder que te indiquemos que actualices a una versión más reciente para ver si el error ocurre allí. O podríamos decidir que el error no se puede solucionar antes de realizar alguna reescritura importante que estemos planeando. O tal vez sea simplemente demasiado difícil y haya cosas más importantes en la agenda. Si necesitas ayuda inmediata, considera la posibilidad de obtener un contrato de soporte comercial.
Antes de reportar un error, por favor lee y vuelve a leer la documentación para verificar que realmente puedes hacer lo que sea que estés intentando. Si no queda claro en la documentación si puedes hacer algo o no, por favor repórtalo también; es un error en la documentación. Si resulta que un programa hace algo diferente a lo que dice la documentación, eso es un error. Eso podría incluir, pero no se limita a, las siguientes circunstancias:
Un programa termina con una señal fatal o un mensaje de error del sistema operativo que apuntaría a un problema en el programa. (Un contraejemplo sería un mensaje de “disco lleno”, ya que eso tienes que solucionarlo tú mismo).
Un programa produce una salida incorrecta para cualquier entrada dada.
Un programa se rehúsa a aceptar una entrada válida (tal como se define en la documentación).
Un programa acepta entrada no válida sin un aviso o mensaje de error. Pero ten en cuenta que tu idea de entrada no válida podría ser nuestra idea de una extensión o compatibilidad con la práctica tradicional.
PostgreSQL falla al compilar, construir o instalar de acuerdo con las instrucciones en plataformas soportadas.
Aquí “programa” se refiere a cualquier ejecutable, no solo al proceso del backend.
Ser lento o consumir muchos recursos no es necesariamente un error. Read the documentation or ask on one of the mailing lists for help in tuning your applications. El no cumplir con el estándar SQL tampoco es necesariamente un error, a menos que se afirme explícitamente el cumplimiento de la característica específica.
Antes de continuar, revisa la lista de TODO y en las FAQ para ver si tu error ya es conocido. Si no puedes decodificar la información de la lista de TODO, reporta tu problema. Lo menos que podemos hacer es aclarar la lista de TODO.
Lo más importante que debes recordar sobre el reporte de errores es exponer todos los hechos y solo los hechos. No especules sobre lo que crees que salió mal, lo que “parecía hacer” o qué parte del programa tiene un fallo. Si no estás familiarizado con la implementación, probablemente adivinarás mal y no nos ayudarás en nada. E incluso si lo estás, las explicaciones fundamentadas son un gran complemento pero no un sustituto de los hechos. Si vamos a solucionar el error, primero tenemos que verlo ocurrir por nosotros mismos. Reportar los hechos puros es relativamente sencillo (probablemente puedas copiarlos y pegarlos de la pantalla), pero con demasiada frecuencia se omiten detalles importantes porque alguien pensó que no importaba o que el reporte se entendería de todos modos.
Los siguientes elementos deberían incluirse en cada reporte de error:
La secuencia exacta de pasos desde el inicio del
programa necesaria para reproducir el problema. Esto
debería ser autosuficiente; no es suficiente enviar una sentencia
SELECT sin los comandos previos
CREATE TABLE e INSERT,
si la salida depende de los datos en las
tablas. No tenemos tiempo para hacer ingeniería inversa de tu
esquema de base de datos, y si se supone que debemos inventar nuestros propios datos,
probablemente no detectemos el problema.
El mejor formato para un caso de prueba para problemas relacionados con SQL es un
archivo que pueda ejecutarse a través de la herramienta psql
que muestre el problema. (Asegúrate de no tener nada
en tu archivo de inicio ~/.psqlrc). Una forma
sencilla de crear este archivo es usar pg_dump
para volcar las declaraciones de tabla y los datos necesarios para preparar la
escena, y luego agregar la consulta del problema. Te animamos a
minimizar el tamaño de tu ejemplo, pero esto no es absolutamente
necesario. Si el error es reproducible, lo encontraremos de
cualquier manera.
Si tu aplicación utiliza alguna otra interfaz de cliente, como PHP, por favor intenta aislar las consultas infractoras. Probablemente no configuraremos un servidor web para reproducir tu problema. En cualquier caso, recuerda proporcionar los archivos de entrada exactos; no adivines que el problema ocurre para “archivos grandes” o “bases de datos medianas”, etc., ya que esta información es demasiado inexacta para ser de utilidad.
La salida que obtuviste. Por favor, no digas que “no funcionó” o que “se cayó” (crashed). Si hay un mensaje de error, muéstralo, incluso si no lo entiendes. Si el programa termina con un error del sistema operativo, di cuál. Si no ocurre nada en absoluto, dilo. Encluso si el resultado de tu caso de prueba es una caída del programa u otra cosa obvia, podría no ocurrir en nuestra plataforma. Lo más fácil es copiar la salida de la terminal, si es posible.
Si estás reportando un mensaje de error, por favor obtén la forma más
detallada (verbose) del mensaje. En psql, di \set
VERBOSITY verbose de antemano. Si estás extrayendo el mensaje
del registro del servidor, establece el parámetro de ejecución
log_error_verbosity en verbose para que se
registren todos los detalles.
En caso de errores fatales, el mensaje de error reportado por el cliente podría no contener toda la información disponible. Por favor, mira también la salida del registro del servidor de la base de datos. Si no conservas el registro de tu servidor, este sería un buen momento para comenzar a hacerlo.
Es muy importante indicar la salida que esperabas. Si solo escribes “Este comando me da esa salida.” o “Esto no es lo que esperaba.”, podríamos ejecutarlo nosotros mismos, revisar la salida y pensar que se ve bien y es exactamente lo que esperábamos. No deberíamos tener que pasar tiempo decodificando la semántica exacta detrás de tus comandos. Evita especialmente limitarte a decir que “Esto no es lo que dice SQL/hace Oracle.” Investigar el comportamiento correcto en SQL no es una tarea divertida, ni todos sabemos cómo se comportan todas las demás bases de datos relacionales del mercado. (Si tu problema es una caída del programa, obviamente puedes omitir este elemento).
Cualquier opción de línea de comandos y otras opciones de inicio, incluyendo cualquier variable de entorno relevante o archivos de configuración que hayas cambiado con respecto al valor predeterminado. Nuevamente, por favor proporciona información exacta. Si estás usando una distribución empaquetada que inicia el servidor de la base de datos en el momento del arranque, deberías intentar averiguar cómo se hace eso.
Cualquier cosa que hayas hecho de manera diferente a las instrucciones de instalación.
La versión de PostgreSQL. Puedes ejecutar el comando
SELECT version(); para
saber la versión del servidor al que estás conectado. La mayoría de los programas
ejecutables también admiten una opción --version; al menos
postgres --version and psql --version
deberían funcionar.
Si la función o las opciones no existen, entonces tu versión es
lo suficientemente antigua como para justificar una actualización.
Si ejecutas una versión empaquetada, como RPMs, dilo, incluyendo cualquier
subversión que pueda tener el paquete. Si estás hablando de un instantánea de Git,
menciónalo, incluyendo el hash de confirmación (commit hash).
Si tu versión es anterior a la 18.4, casi seguro que te diremos que actualices. Hay muchas correcciones de errores y mejoras en cada nueva versión, por lo que es muy posible que un error que hayas encontrado en una versión anterior de PostgreSQL ya haya sido corregido. Solo podemos proporcionar soporte limitado para sitios que usan versiones anteriores de PostgreSQL; si necesitas más de lo que podemos proporcionar, considera adquirir un contrato de soporte comercial.
Información de la plataforma. Esto incluye el nombre y la versión del núcleo (kernel), biblioteca C, procesador, información de memoria, etc. En la mayoría de los casos es suficiente con reportar el proveedor y la versión, pero no asumas que todos saben qué contiene exactamente “Debian” o que todos ejecutan en x86_64. Si tienes problemas de instalación, también es necesaria la información sobre la cadena de herramientas de tu máquina (compilador, make, etc.).
No temas si tu reporte de error se vuelve bastante extenso. Esa es la realidad. Es mejor reportar todo la primera vez que tener que sacarte los hechos a la fuerza. Por otro lado, si tus archivos de entrada son enormes, es justo preguntar primero si alguien está interesado en echarle un vistazo. Aquí tienes un artículo que describe algunos consejos más sobre cómo reportar errores.
No dediques todo tu tiempo a averiguar qué cambios en la entrada hacen que el problema desaparezca. Probablemente esto no ayude a resolverlo. Si resulta que el error no se puede solucionar de inmediato, aún tendrás tiempo para buscar y compartir tu solución alternativa. Además, una vez más, no pierdas tu tiempo adivinando por qué existe el error. Nosotros lo descubriremos lo suficientemente pronto.
Al escribir un reporte de error, por favor evita terminología confusa. El paquete de software en su totalidad se llama “PostgreSQL”, a veces “Postgres” para abreviar. Si estás hablando específicamente del proceso de backend, menciónalo, no digas simplemente “PostgreSQL se cae”. Una caída de un solo proceso de backend es bastante diferente de la caída del proceso principal “postgres”; por favor, no digas “el servidor se cayó” cuando quieras decir que un solo proceso de backend falló, ni viceversa. Además, los programas cliente como la herramienta interactiva “psql” son completamente independientes del backend. Por favor, intenta ser específico sobre si el problema está en el lado del cliente o del servidor.
En general, envía los reportes de errores a la lista de correo de reportes de errores en
<[email protected]>.
Se te solicita utilizar un asunto descriptivo para tu mensaje de correo
electrónico, tal vez partes del mensaje de error.
Otro método es completar el formulario web de reporte de errores disponible
en el sitio web del proyecto.
Ingresar un reporte de errores de esta manera hace que se envíe por correo a la
lista de correo <[email protected]>.
Si tu reporte de error tiene implicaciones de seguridad y prefieres que
no sea visible de inmediato en archivos públicos, no lo envíes a
pgsql-bugs. Los problemas de seguridad se pueden
reportar de forma privada a <[email protected]>.
No envíes reportes de errores a ninguna de las listas de correo de usuarios, como
<[email protected]> o
<[email protected]>.
Estas listas de correo son para responder
preguntas de los usuarios, y sus suscriptores normalmente no desean recibir
reportes de errores. Lo que es más importante, es poco por parte de ellos resolverlos.
Además, por favor no envíes reportes a
la lista de correo de los desarrolladores <[email protected]>.
Esta lista es para discutir el desarrollo de
PostgreSQL, y sería genial
si pudiéramos mantener los reportes de errores separados. Podríamos optar por llevar a cabo una
discusión sobre tu reporte de error en pgsql-hackers,
si el problema necesita más revisión.
Si tienes un problema con la documentación, the best place to report it
is the documentation mailing list <[email protected]>.
Por favor, sé específico sobre qué parte de la documentación no estás satisfecho.
Si tu error es un problema de portabilidad en una plataforma no soportada,
envía un correo a <[email protected]>,
para que nosotros (y tú) podamos trabajar en la
portabilidad de PostgreSQL a tu plataforma.
Debido a la desafortunada cantidad de correo no deseado (spam) que circula, todas las listas anteriores estarán moderadas a menos que estés suscrito. Eso significa que habrá cierto retraso antes de que se entregue el correo electrónico. Si deseas suscribirte a las listas, por favor visita https://lists.postgresql.org/ para obtener instrucciones.