Pular para o conteúdo principal

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
Bugs de fuso horário estão entre os mais difíceis de depurar — eles aparecem e desaparecem conforme a localização do servidor, se manifestam de forma diferente em desenvolvimento e em produção, e muitas vezes só surgem depois de uma transição de horário de verão. A causa raiz é quase sempre uma diferença entre como o MySQL armazena o tempo e como a aplicação espera lê-lo.

DATETIME vs TIMESTAMP

Esses dois tipos parecem semelhantes, mas se comportam de forma diferente no momento crítico — a leitura. TIMESTAMP converte os valores automaticamente:
  • No INSERT/UPDATE: converte do time_zone da sessão para UTC para o armazenamento
  • No SELECT: converte de UTC de volta para o time_zone da sessão para a exibição
DATETIME não faz conversão. O valor que você grava é o valor que você recebe de volta. Zonas nomeadas como 'America/New_York' exigem que as tabelas de fuso horário estejam carregadas (consulte Fusos Horários Nomeados abaixo) — um servidor recém-inicializado não as tem. Verifique com SELECT COUNT(*) FROM mysql.time_zone_name; antes de executar o exemplo abaixo; se for 0, carregue-as primeiro ou substitua por um deslocamento numérico como '-05:00'.

O Problema de 2038

TIMESTAMP é armazenado como um timestamp Unix de 32 bits. Ele não consegue representar datas depois de 2038-01-19 03:14:07 UTC. Qualquer aplicação que armazena datas futuras — reservas, assinaturas, eventos agendados — deve usar DATETIME para evitar esse limite.

Fusos Horários do Servidor e da Sessão

O MySQL tem duas configurações independentes de fuso horário:
Se time_zone mostra SYSTEM, o MySQL está usando o fuso horário do sistema operacional. Isso funciona até o SO mudar (migração de servidor, transição de horário de verão) — então seus timestamps se deslocam. Boa prática: defina o servidor explicitamente em UTC e faça a conversão para exibição na aplicação.
Ou em tempo de execução:

Fusos Horários Nomeados

'+00:00' e 'UTC' são ambos válidos, mas zonas nomeadas como 'America/New_York' exigem que as tabelas de fuso horário estejam carregadas. Se CONVERT_TZ() retorna NULL ou as zonas nomeadas falham, as tabelas estão ausentes.

Colunas AUTO_UPDATE

Colunas TIMESTAMP oferecem suporte ao preenchimento automático na inserção e na atualização:
CURRENT_TIMESTAMP é avaliado em UTC se o fuso horário da sessão é UTC, então created_at e updated_at são armazenados de forma consistente, independentemente de quem se conecta e de qual fuso horário. Você pode fazer o mesmo com DATETIME e NOW():
NOW() retorna a data e a hora atuais no fuso horário da sessão — mais um motivo para padronizar a sessão em UTC.

Perguntas Frequentes

Devo armazenar timestamps em UTC em DATETIME ou usar TIMESTAMP?

Se suas datas ficam dentro do teto de 2038, TIMESTAMP é mais limpo — ele cuida da conversão para UTC automaticamente. Para datas futuras além de 2038, ou para aplicações que precisam armazenar datas históricas anteriores a 1970, use DATETIME e imponha UTC na camada de aplicação, sempre convertendo para UTC antes de inserir.

Por que os timestamps se deslocam depois de uma migração de servidor?

O servidor antigo usava time_zone = SYSTEM apontando para um fuso horário do SO; o novo servidor aponta para outro (ou para UTC). Os valores TIMESTAMP armazenados em UTC são exibidos corretamente nos dois fusos horários, mas se algum valor foi armazenado assumindo o fuso horário do sistema em vez de UTC, ele vai se deslocar. Audite com SELECT @@global.time_zone nos dois servidores antes de migrar.

Como armazeno apenas uma data, sem o componente de hora?

Use DATE. Ele ocupa 3 bytes e não tem ambiguidade de hora do dia nem de fuso horário. Operações como WHERE date_col = '2024-03-15' não são ambíguas, independentemente do fuso horário da sessão.

Solução de Problemas

Veja também