Suporte a fuso horário no mssql-django

Este artigo explica como os campos datetime com reconhecimento de fuso horário funcionam com SQL Server por meio do mssql-django back-end e como migrar dados existentes ao habilitar o suporte a fuso horário.

Como funciona o suporte a fuso horário

A configuração USE_TZ do Django em settings.py controla se os campos de data e hora incluem reconhecimento de fuso horário:

Habilitar o suporte a fuso horário

Defina USE_TZ=True em seu settings.py:

USE_TZ=True
TIME_ZONE = "UTC"

Quando USE_TZ estiver habilitado, o Django armazenará todos os datetimes em UTC e os converterá no fuso horário local para exibição.

A partir de mssql-django 1.7.2, o backend também alinha o comportamento do Django Now() com a geração de SQL sensível a fuso horário quando USE_TZ=True.

Migrar colunas de datetime existentes

Se o aplicativo Django tiver DateTimeField colunas antes de habilitar USE_TZ=True, você deverá migrar manualmente colunas datetime2 para datetimeoffset e converter a hora local em UTC.

O mssql-django backend usa datetime2 como tipo de coluna subjacente para DateTimeField quando USE_TZ=False. A habilitação USE_TZ não converte automaticamente as colunas existentes.

Nas etapas a seguir, substitua os marcadores:

• <table-name>: o nome da tabela que contém a coluna.
• <datetime-column>: O nome da coluna a ser convertido.
• <offset>: O deslocamento de fuso horário dos seus dados existentes como uma string no formato {+|-}HH:MM (por exemplo, '-05:00' para o Horário do Leste dos EUA).

Os exemplos de código neste artigo usam o banco de dados de exemplo AdventureWorks2025 ou AdventureWorksDW2025, que você pode baixar na página inicial Microsoft SQL Server Samples and Community Projects.

Etapa 1: alterar tipos de coluna

Execute o SQL a seguir em cada tabela que tenha colunas datetime2 . SQL Server converte implicitamente o valor e atribui um +00:00 deslocamento:

ALTER TABLE <table-name>
ALTER COLUMN <datetime-column> DATETIMEOFFSET;

Etapa 2: Converter em UTC

Depois que a coluna estiver como datetimeoffset, rotule novamente cada valor com o deslocamento original do fuso horário local e, em seguida, converta-o para UTC:

UPDATE <table-name>
SET <datetime-column> = TODATETIMEOFFSET(<datetime-column>, <offset>) AT TIME ZONE 'UTC';

TODATETIMEOFFSET substitui a parte de deslocamento do valor datetimeoffset para que o carimbo de data/hora reflita a hora local original. AT TIME ZONE 'UTC' em seguida, converte o resultado em UTC.

nomes de fuso horário do SQL Server

Use nomes de fuso horário do Windows ao converter com AT TIME ZONE. Exemplos comuns:

Para obter uma lista completa, consulte SQL Server:

SELECT name, current_utc_offset, is_currently_dst
FROM sys.time_zone_info
ORDER BY name;

Consulte sys.time_zone_info para obter a documentação completa.

Exemplo: converter o horário do leste dos EUA para UTC (considerando o DST)

Este exemplo usa uma tabela de esquema existente AdventureWorks2025 e demonstra o tratamento correto do DST durante a migração:

-- Test with a DST transition date (March 8, 2026)
SELECT TOP 10 SalesOrderID,
             CAST (OrderDate AS DATETIME2) AS OriginalDateTime2,
             (CAST (OrderDate AS DATETIME2) AT TIME ZONE 'Eastern Standard Time') AS EasternTime,
             (CAST (OrderDate AS DATETIME2) AT TIME ZONE 'Eastern Standard Time' AT TIME ZONE 'UTC') AS ConvertedToUtc
FROM Sales.SalesOrderHeader
WHERE MONTH(OrderDate) = 3 AND DAY(OrderDate) = 8
ORDER BY SalesOrderID;

Para migrar suas tabelas de aplicativos, aplique o mesmo AT TIME ZONE padrão de conversão às suas próprias DateTimeField colunas. Para cada tabela, adicione uma coluna datetimeoffset e preencha-a da coluna existente:

ALTER TABLE [your_schema].[your_table] 
ADD [date_column_datetimeoffset] datetimeoffset NULL;

UPDATE [your_schema].[your_table]
SET [date_column_datetimeoffset] = CAST([old_date_column] AS DATETIME2) AT TIME ZONE 'Eastern Standard Time' AT TIME ZONE 'UTC';

Depois de verificar os resultados da conversão, remova a coluna antiga e renomeie a nova:

ALTER TABLE [your_schema].[your_table]
DROP COLUMN [old_date_column];

EXECUTE sp_rename '[your_schema].[your_table].[date_column_datetimeoffset]', 'date_column', 'COLUMN';

Use o nome do fuso horário SQL Server Windows que corresponde à região de dados de origem. Para obter mais informações, consulte sys.time_zone_info.

Etapa 3: Concluir a migração do Django

Depois de converter as colunas de banco de dados, siga a documentação do Django sobre como migrar um projeto iniciado antes da adição do suporte de fuso horário.

Limitations

• Fusos horários e timedeltas: nem todas as operações que envolvem fusos horários e timedeltas têm suporte total. Para obter mais informações, consulte Limitações e recursos sem suporte no mssql-django.
• Aritmética com datas e horas: a exponenciação à direita e a aritmética com valores de data e hora podem não funcionar como esperado quando o suporte a fusos horários estiver habilitado.

Conteúdo relacionado

• Mapeamentos de tipos de campos do Django para tipos do SQL Server
• Referência de configuração mssql-django
• Limitações e recursos sem suporte no mssql-django
• Wiki de suporte a fuso horário
• Documentação do fuso horário do Django