Pular para o conteúdo
Setup do Dev
Guias

timestamp ou timestamptz no PostgreSQL? Testamos o que acontece quando o fuso da sessão muda

Os dois ocupam 8 bytes. No teste, o timestamp jogou fora o +00 sem aviso, e o mesmo pedido das 23h30 mudou de dia conforme o fuso da conexão.

Por Setup do Dev
5 min de leitura
Compartilhar
Capa cinza-azulada com a manchete "O +00 que o timestamp jogou fora" e uma tabela com o mesmo registro visto em São Paulo e em UTC.

O PostgreSQL tem dois tipos para data com hora, e o nome engana. O timestamp (sem fuso) guarda a data e a hora como foram escritas, sem saber de que lugar. O timestamptz (com fuso) guarda um instante: segundo a documentação, o valor é convertido e armazenado em UTC, e na leitura volta convertido para o fuso da sessão. Os dois ocupam 8 bytes; o teste com pg_column_size confirmou.

Testamos no PostgreSQL 18.4, numa tabela temporária, gravando as mesmas quatro linhas nos dois tipos e lendo com a sessão em fusos diferentes.

O teste

SET TIME ZONE 'America/Sao_Paulo';
CREATE TEMPORARY TABLE evento (id int, sem_fuso timestamp, com_fuso timestamptz);
INSERT INTO evento VALUES
  (1, '2026-11-12 09:00',     '2026-11-12 09:00'),
  (2, '2026-11-12 09:00-03',  '2026-11-12 09:00-03'),
  (3, '2026-11-12 09:00+00',  '2026-11-12 09:00+00'),
  (4, '2026-11-12 23:30',     '2026-11-12 23:30');

Com a sessão em São Paulo e depois em UTC, a mesma consulta devolveu:

-- sessão em America/Sao_Paulo
 id |      sem_fuso       |        com_fuso
  1 | 2026-11-12 09:00:00 | 2026-11-12 09:00:00-03
  2 | 2026-11-12 09:00:00 | 2026-11-12 09:00:00-03
  3 | 2026-11-12 09:00:00 | 2026-11-12 06:00:00-03
  4 | 2026-11-12 23:30:00 | 2026-11-12 23:30:00-03

-- sessão em UTC
 id |      sem_fuso       |        com_fuso
  1 | 2026-11-12 09:00:00 | 2026-11-12 12:00:00+00
  2 | 2026-11-12 09:00:00 | 2026-11-12 12:00:00+00
  3 | 2026-11-12 09:00:00 | 2026-11-12 09:00:00+00
  4 | 2026-11-12 23:30:00 | 2026-11-13 02:30:00+00

A coluna com_fuso mudou de aparência e continuou certa: as linhas 1 e 2 são o mesmo instante, 9h em Brasília e 12h em UTC. A sem_fuso não mudou nada, e é aí que estão os problemas.

Duas tabelas lado a lado com as quatro linhas do teste. Com a sessão em São Paulo, a coluna timestamptz mostra 09:00-03, 09:00-03, 06:00-03 e 23:30-03. Com a sessão em UTC, mostra 12:00, 12:00, 09:00 e 02:30 do dia seguinte. A coluna timestamp mostra 09:00, 09:00, 09:00 e 23:30 nas duas, inclusive na linha gravada com +00.
As mesmas quatro linhas vistas com a sessão em São Paulo e em UTC

1. O fuso que o timestamp joga fora

A linha 3 foi gravada como “9h em UTC”. No timestamptz, virou 6h em Brasília, o que está certo. No timestamp, ficou 9h, sem aviso e sem erro. A documentação descreve exatamente isso: num literal tratado como timestamp sem fuso, o PostgreSQL “silently ignore[s] any time zone indication”, ignora a indicação de fuso em silêncio.

É o caso de quem recebe datas em ISO 8601 de uma API (2026-11-12T12:00:00Z) e grava numa coluna timestamp: o “Z” some, e o registro fica três horas adiantado em relação ao horário de Brasília, sem que nada no banco indique isso.

2. O mesmo pedido em dois dias

A linha 4, das 23h30 em Brasília, aparece como 02h30 do dia 13 em UTC. Para o instante, tudo bem. Para o relatório, não: o date_trunc('day', ...) trunca no fuso da sessão. Num segundo teste, com quatro vendas em horário de Brasília, a sessão em UTC contou 2 no dia 12 e 2 no dia 13; o certo, em Brasília, é 3 no dia 12 e 1 no dia 13.

SET TIME ZONE 'UTC';
-- errado para quem vende no Brasil: o dia é o de UTC
SELECT date_trunc('day', em) AS dia, count(*) FROM venda GROUP BY 1;

-- certo, qualquer que seja o fuso da sessão (3 no dia 12, 1 no dia 13)
SELECT date_trunc('day', em, 'America/Sao_Paulo') AS dia, count(*) FROM venda GROUP BY 1;
SELECT (em AT TIME ZONE 'America/Sao_Paulo')::date AS dia, count(*) FROM venda GROUP BY 1;

A forma de três argumentos do date_trunc, que recebe o fuso, está nas funções de data e hora. A segunda consulta converte para a hora local de Brasília e corta a data, e deu o mesmo resultado. O ponto é não depender do fuso da conexão, que muda entre o seu computador, o servidor e o painel de BI.

3. A hora que não existiu

O Brasil não tem horário de verão desde 2019, mas o banco de fusos guarda o histórico, e dado antigo passa por ele. Com a sessão em São Paulo:

SELECT '2018-11-04 00:30'::timestamptz;  -- 2018-11-04 01:30:00-02
SELECT '2018-02-17 23:30'::timestamptz;  -- 2018-02-17 23:30:00-03

Em 4 de novembro de 2018 o relógio pulou da meia-noite para a 1h, e a 00h30 não existiu: o PostgreSQL a empurrou para 01h30 no horário de verão. Em 17 de fevereiro, a hora das 23h se repetiu, e ele escolheu o -03. Num timestamp, as duas datas ficariam gravadas como foram escritas, sem como saber a que instante correspondem.

Como trocar a coluna

A troca de timestamp para timestamptz precisa dizer em que fuso os valores antigos foram gravados:

ALTER TABLE evento
  ALTER COLUMN sem_fuso TYPE timestamptz
  USING sem_fuso AT TIME ZONE 'America/Sao_Paulo';

No teste, as linhas 1, 2 e 4 viraram os instantes certos. A linha 3 virou 12h em UTC, e não 9h: o “+00” perdido na gravação não volta com a conversão. E a documentação do ALTER TABLE avisa que mudar o tipo de uma coluna normalmente reescreve a tabela e os índices; em tabela grande, a troca pede uma janela.

Qual usar

A nossa regra: timestamptz para tudo o que é um instante, como a criação do pedido, o login, o log e o pagamento. O timestamp sem fuso fica para o horário de parede que não é um instante, como “a loja abre às 9h” ou o compromisso futuro guardado com o nome do fuso ao lado, porque as regras de um fuso podem mudar até a data chegar (o fim do horário de verão no Brasil é o exemplo).

Do lado da aplicação, no nosso teste o PDO devolveu o timestamptz como texto com o deslocamento, 2026-11-12 09:00:00-03, e o DateTimeImmutable do PHP lê o deslocamento sem ajuda: convertido para UTC, deu 2026-11-12T12:00:00+00:00. E vale fixar o fuso da conexão (SET TIME ZONE ou o parâmetro timezone do usuário do banco) para que a mesma consulta dê o mesmo texto em todo lugar.

Fontes: Documentação do PostgreSQL: tipos de data e hora, Documentação do PostgreSQL: funções de data e hora, Documentação do PostgreSQL: ALTER TABLE

Produzido com auxílio de IA e revisado pela redação.

Comentários (0)

Ainda não há comentários. Comece a conversa.

Deixe seu comentário

Seu e-mail não será publicado. O primeiro comentário de cada pessoa passa por moderação.

Seja respeitoso

Neste artigo

  1. O teste
  2. 1. O fuso que o timestamp joga fora
  3. 2. O mesmo pedido em dois dias
  4. 3. A hora que não existiu
  5. Como trocar a coluna
  6. Qual usar

Mais lidas

Editorias

Leia também

Newsletter semanal

O essencial da tecnologia, toda sexta no seu e-mail

Uma curadoria da redação com as notícias que importam para quem desenvolve, joga e trabalha com tecnologia. Sem spam.

Ao assinar, você concorda com a política de privacidade. Cancele quando quiser.