Quando for encontrado algum erro no PostgreSQL desejamos ser informados. Seus relatórios de erro são importantes para tornar o PostgreSQL mais confiável, porque mesmo o cuidado mais extremo não pode garantir que todas as partes do PostgreSQL funcionam em todas as plataformas sob qualquer circunstância.
As sugestões abaixo têm por objetivo ajudá-lo a preparar relatórios de erro que possam ser tratados de forma eficaz. Ninguém é obrigado a segui-las, mas são feitas para serem vantajosas para todos.
Não podemos prometer corrigir todos os erros imediatamente. Se o erro for óbvio, crítico, ou afetar muitos usuários, existe uma boa chance de alguém investigá-lo. Pode acontecer, também, nós solicitarmos que você atualize para uma nova versão, para ver se o erro também acontece na nova versão. Também podemos decidir que o erro não poderá ser corrigido antes de ser feita uma importante reescrita planejada ou, talvez, simplesmente esta correção seja muito difícil e existem assuntos mais importantes na agenda. Se for necessária ajuda imediata, deve ser levada em consideração a contratação de um suporte comercial.
Antes de informar um erro, por favor leia e releia a documentação para verificar se realmente pode ser feito o que está se tentando fazer. Se não estiver claro na documentação se pode ou não ser feito, por favor informe isto também; é uma falha na documentação. Se for visto que o programa faz algo diferente do que está especificado na documentação, isto também é um erro. Pode incluir, sem estar restrito, as seguintes circunstâncias:
O programa termina com um erro fatal, ou com uma mensagem de erro do sistema operacional que aponta para um problema no programa (um exemplo oposto seria uma mensagem de "disco cheio", porque o próprio usuário deve corrigir este problema).
O programa produz uma saída errada para uma determinada entrada.
O programa não aceita uma entrada válida (conforme definido na documentação).
O programa aceita uma entrada inválida sem enviar uma mensagem de erro. Porém, tenha em mente que a sua idéia de entrada inválida pode ser a nossa idéia de uma extensão, ou de compatibilidade com a prática tradicional.
Em uma plataforma suportada, a compilação, montagem ou instalação do PostgreSQL, de acordo com as instruções, falha.
Aqui "programa" se refere a qualquer executável, e não apenas ao processo servidor.
Estar lento ou consumir muitos recursos não é necessariamente um erro. Leia a documentação ou faça perguntas em uma lista de discussão pedindo ajuda para ajustar seus aplicativos. Não agir em conformidade com o padrão SQL também não é necessariamente um erro, a não ser que a conformidade com a funcionalidade específica esteja explicitamente informada.
Antes de prosseguir, verifique a lista TODO (a fazer) e a FAQ para ver se o erro já não é conhecido. Se você não conseguir decodificar a informação da lista TODO, relate seu problema. O mínimo que podemos fazer é tornar a lista TODO mais clara.
O mais importante a ser lembrado sobre informar erros é declarar todos os fatos, e somente os fatos. Não especule sobre o que você pensa que deu errado, o que "parece que deve ser feito", ou em que parte do programa está o erro. Se não estiver familiarizado com a implementação você provavelmente vai supor errado, e não vai nos ajudar nem um pouco. E, mesmo que você esteja familiarizado, uma explicação educada é um grande suplemento, mas não substitui os fatos. Se formos corrigir o erro, temos que vê-lo acontecer primeiro. Informar meramente os fatos é relativamente direto (provavelmente pode ser copiado e colado a partir da tela), mas geralmente são deixados de fora detalhes importantes porque se pensou que não tinham importância, ou que o relatório seria entendido de qualquer maneira.
Todo relatório de erro deve conter os seguintes itens:
A seqüência exata dos passos, desde o início do programa, necessários para reproduzir o problema. Isto deve estar autocontido; não é suficiente enviar meramente o comando SELECT, sem enviar os comandos CREATE TABLE e INSERT que o precederam, caso a saída dependa dos dados contidos nas tabelas. Não temos tempo para realizar a engenharia reversa do esquema do seu banco de dados e, se tivermos que criar nossos próprios dados, provavelmente não vamos conseguir reproduzir o problema.
O melhor formato para um caso de teste, para problemas relacionados com a linguagem SQL, é um arquivo mostrando o problema que possa ser executado a partir do utilitário psql (certifique-se não existir nada em seu arquivo de inicialização ~/.psqlrc). Um modo fácil de começar este arquivo é usar o pg_dump para gerar as declarações da tabela e dos dados necessários para montar o cenário, e depois adicionar o comando com problema. Incentivamos você a minimizar o tamanho do exemplo, mas isto não é absolutamente necessário. Se o erro for reproduzível, nós o encontraremos de qualquer maneira.
Se o seu aplicativo utiliza alguma outra interface cliente, tal como o PHP, então, por favor, tente isolar o comando com problema. Provavelmente não iremos configurar um servidor Web para reproduzir o seu problema. De qualquer maneira, lembre-se de fornecer os arquivos de entrada exatos, e não suponha que o problema aconteça com "arquivos grandes" ou "bancos de dados de tamanho médio", etc., porque estas informações são muito pouco precisas para serem úteis.
A saída recebida. Por favor, não diga que "não funcionou" ou que "deu pau". Se houver uma mensagem de erro mostre-a, mesmo que você não a entenda. Se o programa terminar com um erro do sistema operacional, diga qual. Se nada acontecer, informe. Mesmo que o resultado do seu caso de teste seja o término anormal do programa, ou seja óbvio de alguma outra forma, pode ser que não aconteça na nossa plataforma. O mais fácil a ser feito é copiar a saída do terminal, se for possível.
Nota: Se estiver sendo informada uma mensagem de erro, por favor obtenha a forma mais verbosa da mensagem. No psql execute antes \set VERBOSITY verbose. Se a mensagem estiver sendo extraída do log do servidor, defina o parâmetro em tempo de execução log_error_verbosity como verbose, para serem registrados todos os detalhes.
Nota: No caso de erros fatais, a mensagem de erro informada pelo cliente pode não conter toda a informação disponível. Por favor, olhe também a saída do log do servidor de banco de dados. Se você não mantém a saída do log do servidor, esta é uma boa hora para começar.
A saída esperada é uma informação importante a ser declarada. Se for escrito apenas "Este comando produz esta saída" ou "Isto não é o esperado", poderemos executar, olhar a saída, e achar que está tudo correto, exatamente o que esperávamos que fosse. Não devemos perder tempo decodificando a semântica exata por trás de seus comandos. Abstenha-se, especialmente, de dizer meramente "Isto não é o que o SQL diz ou o que o Oracle faz". Pesquisar o comportamento correto do SQL não é uma tarefa divertida, nem sabemos como todos os outros bancos de dados relacionais existentes se comportam (se o problema for o término anormal do programa, este item obviamente pode ser omitido).
Todas as opções de linha de comando e outras opções de inicialização, incluindo as variáveis de ambiente relevantes e os arquivos de configuração que foram alterados em relação ao padrão. Novamente, forneça a informação exata. Se estiver sendo utilizada uma distribuição pré-configurada, que inicializa o servidor de banco de dados durante o boot, deve-se tentar descobrir como isto é feito.
Qualquer coisa feita que seja diferente das instruções de instalação.
A versão do PostgreSQL. Pode ser executado o comando SELECT version(); para descobrir a versão do servidor ao qual se está conectado. A maioria dos programas executáveis suportam a opção --version; pelo menos postmaster --version e psql --version devem funcionar. Se a função ou as opções não existirem, então a versão sendo usada é antiga o suficiente para merecer uma atualização. Se estiver sendo usada uma versão pré-configurada, como RPMs, informe, incluindo qualquer sub-versão que o pacote possa ter. Se estiver se referindo a um instantâneo do CVS isto deve ser mencionado, incluindo a data e a hora.
Se a sua versão for anterior a 8.0.0, quase certamente lhe pediremos para atualizar. Existem muitas correções de erro e melhorias a cada nova liberação e, portanto, é bem possível que o erro encontrado em uma versão antiga do PostgreSQL já esteja corrigido. Só podemos oferecer suporte limitado às instalações usando versões antigas do PostgreSQL; se for desejado mais do que pode ser fornecido, deve ser levado em consideração a contratação de um suporte comercial.
Informações da plataforma. Isto inclui o nome e a versão do núcleo, a biblioteca C, o processador e a memória. Na maioria dos casos é suficiente informar o fornecedor e a versão, mas não se deve supor que todo mundo sabe exatamente o que o "Debian" contém, ou que todo mundo use Pentium. Havendo problemas de instalação, então também são necessárias informações sobre as ferramentas empregadas (compilador, make, etc.).
Não tenha medo que seu relatório de erro fique muito longo. Este é um fato da vida. É melhor informar tudo da primeira vez do que termos que extrair os fatos de você. Por outro lado, se seus arquivos de entrada são enormes, é justo perguntar primeiro se alguém está interessado em vê-los.
Não perca seu tempo tentando descobrir que mudanças na entrada fazem o problema desaparecer. Isto provavelmente não vai ajudar a solucionar o problema. Se for visto que o erro não pode ser corrigido imediatamente, você vai ter tempo para descobrir e compartilhar sua descoberta. Também, novamente, não perca seu tempo adivinhando porque o erro existe, nós o descobriremos em breve.
Ao escrever o relatório de erro, por favor escolha uma terminologia que não confunda. O pacote de software em seu todo é chamado de "PostgreSQL" e, algumas vezes, de "Postgres" para encurtar. Se estiver se referindo especificamente ao processo servidor mencione isto, não diga apenas "o PostgreSQL caiu". A queda de um único processo servidor é bem diferente da queda do processo "postmaster" pai; por favor não diga "o postmaster caiu" quando um único processo servidor caiu, nem o contrário. Além disso os programas cliente, como o cliente interativo "psql", são completamente separados do servidor. Por favor, tente especificar se o problema está no lado cliente ou no lado servidor.
De modo geral, envie relatórios de erro para a lista de discussão de relatórios de erros em <pgsql-bugs@postgresql.org> . É necessário utilizar um assunto descritivo para a mensagem de correio eletrônico, talvez partes da própria mensagem de erro.
Outra forma é preencher o relatório de erro disponível no sítio do projeto na Web em http://www.postgresql.org/. Preencher o relatório de erro desta forma faz com que seja enviado para a lista de discussão <pgsql-bugs@postgresql.org> .
Não envie o relatório de erro para nenhuma lista de discussão dos usuários, tal como <pgsql-sql@postgresql.org> ou <pgsql-general@postgresql.org> . Estas listas de discussão são para responder as perguntas dos usuários, e seus assinantes normalmente não desejam receber relatórios de erro. Mais importante ainda, eles provavelmente não vão conseguir corrigir o erro.
Por favor, também não envie relatórios para a lista de discussão dos desenvolvedores em <pgsql-hackers@postgresql.org> . Esta lista é para discutir o desenvolvimento do PostgreSQL, e gostamos de manter os relatórios de erro em separado. Podemos decidir discutir seu relatório de erro em pgsql-hackers, se o problema necessitar uma melhor averiguação.
Se você tiver problema com a documentação, o melhor lugar para informar é na lista de discussão da documentação em <pgsql-docs@postgresql.org> . [1] Por favor seja específico sobre qual parte da documentação você não está satisfeito.
Se seu erro for um problema de portabilidade em uma plataforma não suportada, envie uma mensagem de correio eletrônico para <pgsql-ports@postgresql.org> , para que nós (e você) possamos trabalhar para portar o PostgreSQL para esta plataforma.
Nota: Por causa da grande quantidade de spam na Internet, todos os endereços de correio eletrônico acima são de listas de discussão fechadas, ou seja, primeiro é necessário assinar a lista para depois poder enviar mensagens (entretanto, não é necessário assinar nenhuma lista para utilizar o formulário de relatório de erro da Web). Se você deseja enviar uma mensagem de correio eletrônico, mas não deseja receber o tráfego da lista, você pode subscrever e configurar sua opção de subscrição com nomail. Para maiores informações envie uma mensagem para <majordomo@postgresql.org> contendo apenas a palavra help no corpo da mensagem.
| [1] |
Por favor, informe os erros de tradução encontrados nesta documentação para <halleypo@users.sourceforge.net> . (N. do T.) |
