Suporte a fusos horários no mssql-django

Este artigo explica como os campos de data e hora com reconhecimento de fuso horário funcionam com o SQL Server através do backend mssql-django e como migrar os dados existentes quando ativa o suporte para fusos horários.

Como funciona o suporte ao fuso horário

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

Ativar suporte a fusos horários

Defina USE_TZ=True no seu settings.py:

USE_TZ=True
TIME_ZONE = "UTC"

Quando USE_TZ está ativado, o Django armazena todas as datas em UTC e converte-as para o fuso horário local para exibição.

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

Migrar colunas de data-hora existentes

Se a tua aplicação Django já tinha DateTimeField colunas antes de ativar USE_TZ=True, tens de migrar manualmente as colunas datetime2 para o datetimeoffset e converter a hora local para UTC.

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

Nos passos seguintes, substitua os marcadores de lugar:

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

Os exemplos de código neste artigo usam o banco de dados de exemplo AdventureWorks2025 ou AdventureWorksDW2025, que pode ser descarregado da página inicial de Exemplos e Projetos da Comunidade do Microsoft SQL Server.

Passo 1: Alterar os tipos de colunas

Execute o SQL seguinte em cada tabela que tenha colunas datetime2 . O SQL Server converte implicitamente o valor e atribui um +00:00 offset:

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

Passo 2: Converter para UTC

Depois de a coluna ser do tipo datetimeoffset, voltar a etiquetar cada valor com o desvio original do fuso horário local e, em seguida, converter para UTC:

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

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

Nomes dos fusos horários do SQL Server

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

Para uma lista completa, consulte o SQL Server:

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

Consulte sys.time_zone_info para documentação completa.

Exemplo: Converter a hora da Costa Leste dos EUA para UTC (com consideração pelo horário de verão)

Este exemplo utiliza uma tabela de esquemas 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 as suas tabelas de aplicação, aplique o mesmo AT TIME ZONE padrão de conversão às suas próprias DateTimeField colunas. Para cada tabela, adicione uma coluna datatimeoffset e preencha-a a partir 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 verificares os resultados da conversão, elimina a coluna antiga e renomeia 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 corresponda à sua região de origem de dados. Para mais informações, consulte sys.time_zone_info.

Passo 3: Completar a migração para Django

Após converter as colunas da base de dados, siga a documentação do Django sobre a migração de um projeto iniciado antes de ser adicionado suporte para fusos horários.

Limitations

• Fos horários e deltas horários: Nem todas as operações que envolvem fusos horários e deltas de tempo são totalmente suportadas. Para mais informações, consulte Limitações e funcionalidades não suportadas no mssql-django.
• Aritmética com data e hora: A exponenciação à direita e a aritmética com valores de data e hora podem não funcionar como esperado quando o suporte para fusos horários está ativado.

Conteúdo relacionado

• Campo Django para mapeamentos do tipo SQL Server
• Referência de configuração MSSQL-Django
• Limitações e funcionalidades não suportadas no mssql-django
• Wiki de suporte a fusos horários
• Documentação do fuso horário Django