Como relatar erros ou problemas

Nosso banco de dados de bugs ´e publico e pode ser pesquisado por qualquer um em http://bugs.mysql.com/. Se vocˆe logar no sistema, vocˆe poder´a entrar novos relat´orios.

Escrever um bom relat´orio de erro exige paciˆencia, e fazˆe-lo de forma apropriada economiza tempo para n´os e para vocˆe. Um bom relat´orio de erros contendo um teste de caso para o bug ir´a torn´a-lo muito mais f´acil para corrig´i-lo no pr´oximo release. Esta se¸c˜ao ir´a ajud´a-lo a escrever seu relat´orio corretamente para que vocˆe n˜ao perca seu tempo fazendo coisas que n˜ao ir˜ao ajudar-nos muito ou nada.

N´os encorajamos todo mundo a usar o scriptmysqlbugpara gerar um relato de erros (ou um relato sobre qualquer problema), se poss´ivel. mysqlbug pode ser encontrado no diret´orio

‘scripts’ na distribui¸c˜ao fonte, ou, para uma distribui¸c˜ao bin´aria, no diret´orio ‘bin’ no diret´orio de instala¸c˜ao do MySQL. Se vocˆe n˜ao puder utilizar o mysqlbug (por exemplo, se vocˆe o estiver executando no Windows), ´e ainda de vital importˆancia que vocˆe incluia todas as informa¸c˜oes necess´arias listadas nesta se¸c˜ao (o mais importante ´e uma descri¸c˜ao do sistema operacional e a vers˜ao do MySQL).

O script mysqlbug lhe ajudar´a a gerar um relat´orio determinando muitas das seguintes informa¸c˜oes automaticamente, mas se alguma coisa importante estiver faltando, por favor forne¸ca-o junto de sua mensagem! Por favor leita esta se¸c˜ao com cuidado e tenha certeza que todas as informa¸c˜oes descritas aquie est˜ao inclu´idas no seu relat´orio.

De preferˆencia, vocˆe deve testar o problema usando a ´ultima vers˜ao de produ¸c˜ao ou desen-volvimento do Servidro MySQL antes do envio. Qualquer um deve estar apto a repetir o erro apenas usando ’mysql test < script’ no caso de teste incluido ou executando o script sheel ou Perl que ´e inclu´ido no relat´orio de erros.

Todos os erros enviados para o banco de dados dem bugs em http://bugs.mysql.com/

ser˜ao corrigidos ou documentados na pr´oxma distribui¸c˜ao do MySQL. Se apenas pequenas mudan¸cas de c´odigo forem necess´arias enviaremos um patch para corrigir o problema.

O lugar comum para relatar erros e problemas ´ehttp://bugs.mysql.com.

Se vocˆe encontrar um erro de seguran¸ca no MySQL, envie um email para [email protected].

Se vocˆe tiver um relat´orio de erro que possa ser repetido, relate-o no banco de dados de bugs emhttp://bugs.mysql.com. Note que mesmo neste caso ´e bom executar o scriptmysqlbug primeiro para ter informa¸c˜oes sobre o sistema. Qualquer erro que pudermos repetir tem uma grande chance de ser corrigido na pr´oxima distribui¸c˜ao do MySQL.

Para relatar outros problemas, vocˆe pode usar a lista de email do MySQL.

Lembre-se que ´e poss´ivel responder a uma mensagem contendo muita informa¸c˜ao, mas n˜ao a uma contendo muito pouca. Frequentemente pessoas omitem fatos porque acreditam que conhecem a causa do problema e assumem que alguns detalhes n˜ao importam. Um bom principio ´e: Se vocˆe est´a em d´uvida sobre declarar alguma coisa, declare-a ! ´E milhares de vezes mais r´apido e menos problem´atico escrever um pouco de linhas a mais no seu relat´orio do que ser for¸cado a perguntar de novo e esperar pela resposta porque vocˆe n˜ao forneceu informa¸c˜ao sufiente da primeira vez.

Os erros mais comuns acontecem porque as pessoas n˜ao indicam o n´umero da vers˜ao da distribui¸c˜ao do MySQL que est˜ao usando, ou n˜ao indicam em qual plataforma elas tem o MySQL instalado (Incluindo o n´umero da vers˜ao da plataforma). Essa informa¸c˜ao ´e muito relevante, e em 99% dos casos o relato de erro ´e in´util sem ela! Frequentemente n´os recebemos quest˜oes como, “Por que isto n˜ao funciona para mim?” ent˜ao n´os vemos que aquele recurso requisitado n˜ao estava implementado naquela vers˜ao do MySQL, ou que o erro descrito num relat´orio foi resolvido em uma vers˜ao do MySQL mais nova. Algumas vezes o erro ´e dependente da plataforma; nesses casos, ´e quase imposs´ivel corrigir alguma coisa sem conhecimento do sistema operacional e o n´umero da vers˜ao da plataforma.

Lembre-se tamb´em de fornecer informa¸c˜oes sobre seu compilador, se isto for relacionado ao problema. Frequentemente pessoas encontram erros em compiladores e acreditam que o problema ´e relacionado ao MySQL. A maioria dos compiladores est˜ao sobre desenvolvimento todo o tempo e tornam-se melhores a cada vers˜ao. Para determinar se o seu problema depende ou n˜ao do compilador, n´os precisamos saber qual compilador foi usado. Note que todo problema de compila¸c˜ao deve ser estimado como relato de erros e, consequentemente publicado.

E de grande ajuda quando uma boa descri¸c˜ao do problema ´e inclu´ida no relato do erro. Isto´

´e, um bom exemplo de todas as coisas que o levou ao problema e a correta descri¸c˜ao do problema. Os melhores relat´orios s˜ao aqueles que incluem um exemplo completo mostrando como reproduzir o erro ou o problema Veja Se¸c˜ao D.1.6 [Casos de teste reproduz´iveis], P´agina 1075.

Se um programa produz uma mensagem de erro, ´e muito importante incluir essas mensagens no seu relat´orio! Se n´os tentarmos procurar por algo dos arquivos usando programas, ´e melhor que as mensagens de erro relatadas sejam exatamente iguais a que o programa produziu. (At´e o caso deve ser observado!) Vocˆe nunca deve tentar lembrar qual foi a mensagem de erro; e sim, copiar e colar a mensagem inteira no seu relat´orio!

Se vocˆe tem um problema com o MyODBC, vocˆe deve tentar gerar um arquivo para rastremento de erros (trace) do MyODBC. Veja Se¸c˜ao 12.2.7 [MyODBC bug report], P´agina 875.

Por favor lembre-se que muitas das pessoas que ler˜ao seu relat´orio podem usar um v´ideo de 80 colunas. Quando estiver gerando relat´orios ou exemplos usando a ferramenta de linha de comandomysql, ent˜ao dever´a usar a op¸c˜ao--vertical(ou a instru¸c˜ao terminadora\G) para sa´ida que ir´a exceder a largura dispon´ivel para este tipo de v´ideo (por exemplo, com a instru¸c˜ao EXPLAIN SELECT; veja exemplo abaixo).

Por favor inclua a seguinte informa¸c˜ao no seu relat´orio:

• O n´umero da vers˜ao da distribui¸c˜ao do MySQL que est´a em uso (por exemplo, MySQL Version 3.22.22). Vocˆe poder´a saber qual vers˜ao vocˆes est´a executando, usando o

comando mysqladmin version. mysqladmin pode ser encontrado no diret´orio ‘bin’

sob sua instala¸c˜ao do MySQL.

• O fabricante e o modelo da m´aquina na qual vocˆe est´a trabalhando.

• O nome do sistema operacional e a vers˜ao. Para a maioria dos sistemas operacionais, vocˆe pode obter esta informa¸c˜ao executando o comando Unix uname -a. Se vocˆe tra-balho no Windows, vocˆe pode normalmente conseguir o nome e o n´umero da vers˜ao com um duplo clique sobre o ´icone ”Meu Computador” e em seguida no menu ”Ajuda/Sobre o Windows”.

• Algumas vezes a quantidade de mem´oria (real e virtual) ´e relevante. Se estiver em d´uvida, inclua esses valores.

• Se vocˆe estiver usando uma distribui¸c˜ao fonte do MySQL, ´e necess´ario o nome e n´umero da vers˜ao do compilador usado. Se vocˆe estiver usando uma distribui¸c˜ao bin´aria, ´e necess´ario o nome da distribui¸c˜ao.

• Se o problema ocorre durante a compila¸c˜ao, inclua a(s) exata(s) mensagem(s) de erro(s) e tamb´em algumas linhas do contexto envolvendo o c´odigo no arquivo onde o erro ocorreu.

• Se o mysqld finalizou, vocˆe dever´a relatar tamb´em a consulta que travou o mysqld.

Normalmente vocˆe pode encontrar isto executandomysqldcom o log habilitado. Veja Se¸c˜ao D.1.5 [Using log files], P´agina 1074.

• Se alguma tabela do banco de dados estiver relacionado ao problema, inclua a sa´ida de mysqldump --nodata nome_db nome_tbl1 nome_tbl2.... Isto ´e muito f´acil de fazer e ´e um modo poderoso de obter informa¸c˜oes sobre qualquer tabela em um banco de dados que ir´a ajudar-nos a criar uma situa¸c˜ao parecida da que vocˆe tem.

• Para problemas relacionados `a velocidade ou problemas com instru¸c˜oes SELECT, vocˆe sempre deve incluir a sa´ida deEXPLAIN SELECT ...e ao menos o n´umero de linhas que a instru¸c˜ao SELECTproduz. Vocˆe tamb´em deve incluir a sa´ida de SHOW CREATE TABLE nome_tabelapara cada tabela envolvida. Quanto mais informa¸c˜ao vocˆe fornecer sobre a sua situa¸c˜ao, mais f´acil ser´a para algu´em ajudar-lo! A seguir um exemplo de um relat´orio de erros muito bom (ele deve ser postado com o script mysqlbug):

Exemplo de execu¸c˜ao usando a ferramenta de linha de comando mysql(perceba o uso do instru¸c˜ao terminadora \Gpara instru¸c˜oes cuja largura de sa´ida deva ultrapassar 80 colunas):

mysql> SHOW VARIABLES;

mysql> SHOW COLUMNS FROM ...\G

<saida para SHOW COLUMNS>

mysql> EXPLAIN SELECT ...\G

<saida para EXPLAIN>

mysql> FLUSH STATUS;

mysql> SELECT ...;

<Uma pequena vers~ao da sa´ida do SELECT,

incluindo a hora em que a consulta foi executada>

mysql> SHOW STATUS;

<saida do SHOW STATUS>

• Se um erro ou problema ocorrer quando estiver executando omysqld, tente fornecer um script de entrada que ir´a reproduzir a anomalia. Este script deve incluir qualquer

ar-quivo de fonte necess´ario. Quanto mais pr´oximo o script puder reproduzir sua situa¸c˜ao, melhor. Se vocˆe puder fazer uma s´erie de testes repetidos, vocˆe poder´a post´a-lo para o [email protected] para um tratamento de alta prioridade!

Se n˜ao puder fornecer o script, vocˆe ao menos deve incluir a sa´ida de mysqladmin variables extended-status processlist na sua mensagem para fornecer alguma informa¸c˜ao da performance do seus sistema.

•

Se vocˆe n˜ao puder produzir um caso de teste em algumas linhas, ou se a tabela de testes for muito grande para ser enviada por email para a lista de mensagens (mais de 10 linhas), vocˆe dever´a dar um dump de suas tabelas usando o mysqldump e criar um arquivo ‘README’ que descreve seu problema.

Crie um arquivo comprimido de seus arquivos usando tar e gzip ou zip, e use o ftp para transferir o arquivo para ftp://support.mysql.com/pub/mysql/secret/.

E envie uma pequena descri¸c˜ao do problema para [email protected].

• Se vocˆe achar que o MySQL produziu um resultado estranho para uma consulta, n˜ao inclua somente o resultado, mas tamb´em sua opini˜ao de como o resultado deve ser, e uma conta descrevendo o base de sua opini˜ao.

• Quando fornecer um exemplo do problema, ´e melhor usar os nomes de vari´aveis, nomes de tabelas, etc. utilizados na sua situa¸c˜ao atual do que enviar com novos nomes. O problema pode ser relacionado ao nome da vari´avel ou tabela! Esses casos s˜ao raros, mas ´e melhor prevenir do que remediar. Al´em disso, ser´a mais f´acil para vocˆe fornecer um exemplo que use sua situa¸c˜ao atual, que ´e o que mais importa para n´os. No caso de ter dados que n˜ao deseja mostrar para outros, vocˆe pode usar oftp para transferi-lo para ftp://support.mysql.com/pub/mysql/secret/. Se os dados s˜ao realmente confidenciais, e vocˆe n˜ao deseja mostr´a-los nem mesmo para n´os, ent˜ao v´a em frente e providencie um exemplo usando outros nome, mas, por favor considere isso como uma

´

unica chance.

• Inclua, se poss´ivel, todas as op¸c˜oes fornecidas aos programas relevantes. Por exemplo, indique as op¸c˜oes que vocˆe utiliza quando inicializa o daemonmysqlde aquelas que s˜ao utilizadas para executar qualquer programa cliente MySQL. As op¸c˜oes para programas como o mysqld e mysql, e para o script configure, s˜ao frequentemente chaves para respostas e s˜ao muito relevantes! Nunca ´e uma m´a id´eia inclu´i-las de qualquer forma!

Se vocˆe usa algum m´odulo, como Perl ou PHP por favor forne¸ca o n´umero da vers˜ao deles tamb´em.

• Se sua quest˜ao ´e relacionada ao sistema de privil´egios, por favor forne¸ca a sa´ida de mysqlaccess, a sa´ida de mysqladmin reload, e todas as mensagens de erro que vocˆe obteve quando tentava conectar! Quando vocˆe testar seus privil´egios, vocˆe deve primeiramente executarmysqlaccess. Depois, executemysqladmin reload versione tente conectar com o programa que gerou o problema. mysqlaccess pode ser encon-trado no diret´orio ‘bin’ sob seu diret´orio de instala¸c˜ao do MySQL.

• Se vocˆe tiver um patch para um erro, isso ´e bom, mas n˜ao assuma que o patch ´e tudo que precisamos, ou que iremos us´a-lo, se vocˆe n˜ao fornecer algumas informa¸c˜oes necess´arias, como os casos de testes mostrando o erro que seu patch corrige. N´os podemos encontrar problemas com seu patch ou n´os podemos n˜ao entendˆe-lo ao todo;

se for assim, n˜ao podemos us´a-lo.

Se n´os n˜ao verificarmos exatamente o que o patch quer dizer, n´os n˜ao poderemos us´a-lo. Casos de testes ir˜ao ajudar-nos aqui. Mostre que o patch ir´a cuidar de todas as situa¸c˜oes que possam ocorrer. Se n´os encontrarmos um caso (mesmo que raro) onde o patch n˜ao funcionaria, ele pode ser in´util.

• Palpites sobre qual ´e o erro, porque ocorre, ou do que ele depende, geralmente est˜ao errados. Mesmo o time MySQL n˜ao pode adivinhar antecipadamente tais coisas sem usar um debugger para determinar a causa real do erro.

• Indique na sua mensagem de e-mail que vocˆe conferiu o manual de referˆencia e o arquivo de mensagens para que outros saibam que vocˆe tentou solucionar o problema.

• Se vocˆe obter um parse error, por favor confira sua sintaxe com aten¸c˜ao! Se vocˆe n˜ao conseguiu encontrar nada errado com ela, ´e extremamente prov´avel que que sua vers˜ao corrente do MySQL n˜ao suporte a consulta que vocˆe est´a utilizando. Se vocˆe estiver usando a vers˜ao recente e o manual em http://www.mysql.com/documentation/manual.php n˜ao cobrir a sintaxe que vocˆe estiver usando, o MySQL n˜ao suporta sua consulta. Neste caso, suas unicas op¸c˜oes s˜ao implementar vocˆe mesmo a sintaxe ou enviar uma mensagem para [email protected] e perguntar por uma oferta para implement´a-lo!

Se o manual cobrir a sintaxe que vocˆe estiver usando, mas vocˆe tiver uma vers˜ao mais antiga do MySQL, vocˆe dever´a conferir o hist´orico de altera¸c˜oes do MySQL para ver quando a sintaxe foi implementada. Neste caso, vocˆe tem a op¸c˜ao de atualizar para uma nova vers˜ao do MySQL. Veja Apˆendice C [News], P´agina 948.

• Se vocˆe tiver um problema do tipo que seus dados aparecem corrompidos ou vocˆe obtem erros quando vocˆe acessa alguma tabela em particular, vocˆe dever´a primeiro checar depois tentar reparar suas tabelas com myisamchk ou CHECK TABLE e REPAIR TABLE. Veja Cap´“ptexi tulo 4 [MySQL Database Administration], P´agina 208.

• Se vocˆe frequentemente obt´em tabelas corrompidas, vocˆe deve ten-tar encontrar quando e porque isto acontece! Neste caso, o arquivo

‘mysql-data-directory/’hostname’.err’ deve conter algumas informa¸c˜oes sobre o que aconteceu. Veja Se¸c˜ao 4.10.1 [Error log], P´agina 373. Por favor forne¸ca qualquer informa¸c˜ao relevante deste arquivo no seu relat´orio de erro! Normalmente o mysqld NUNCA dever´a danificar uma tabela se nada o finalizou no meio de uma atualiza¸c˜ao! Se vocˆe puder encontrar a causa do fim do mysqld, se torna muito mais f´acil para n´os fornecemos a vocˆe uma solu¸c˜ao para o problema! Veja Se¸c˜ao A.1 [What is crashing], P´agina 907.

• Se poss´ivel, fa¸ca o download e instale a vers˜ao mais recente do MySQL para saber se ela resolve ou n˜ao o seu problema. Todas vers˜oes do MySQL s˜ao muito bem testadas e devem funcionar sem problemas! Acreditamos em deixar tudo, o mais comp´ativel poss´ivel com as vers˜oes anteriores, e vocˆe conseguir´a mudar de vers˜oes MySQL em minutos! Veja Se¸c˜ao 2.2.4 [Which version], P´agina 80.

Se vocˆe ´e um cliente de nosso suporte, por favor envio o seu relat´orio de erros em [email protected] tratamento de alta priorit´ario, bem como para a lista de mensagens apropriada para ver se mais algu´em teve experiˆencias com (e talvez resolveu) o problema.

Para informa¸c˜oes sobre relatar erros no MyODBC, veja Se¸c˜ao 12.2.4 [ODBC Problems], P´agina 869.

Para solu¸c˜oes a alguns problemas comuns, veja Veja Apˆendice A [Problems], P´agina 907.

Quando respostas s˜ao enviadas para vocˆe individualmente e n˜ao para a lista de mensagens, ´e considerado boa etiqueta resumir as respostas e enviar o resumo para a lista de mensagens para que outras possam ter o benef´icio das respostas que vocˆe recebeu que ajudaram a resolver seu problema!