Ondersteuning voor tijdzones in mssql-django

In dit artikel wordt uitgelegd hoe tijdzonebewuste datum/tijd-velden werken met SQL Server via de mssql-django back-end en hoe u bestaande gegevens migreert wanneer u ondersteuning voor tijdzones inschakelt.

Hoe ondersteuning voor tijdzones werkt

De instelling van USE_TZ Django in settings.py bepaalt of datum/tijd-velden tijdzonebewust zijn:

Ondersteuning voor tijdzone inschakelen

Stel USE_TZ=True in uw settings.py in:

USE_TZ=True
TIME_ZONE = "UTC"

Wanneer USE_TZ deze optie is ingeschakeld, slaat Django alle datum/tijd in UTC op en converteert deze naar de lokale tijdzone voor weergave.

mssql-django Vanaf 1.7.2 stemt de back-end ook het gedrag van Django Now() af op tijdzonebewuste SQL-generatie wanneer USE_TZ=True.

Bestaande datum/tijd-kolommen migreren

Als uw Django-app vóór het inschakelen van USE_TZ=True kolommen DateTimeField had, moet u datetime2-kolommen handmatig migreren naar datetimeoffset en de lokale tijd naar UTC converteren.

De mssql-django backend gebruikt datetime2 als onderliggend kolomtype voor DateTimeField wanneer USE_TZ=False. Als u inschakelt USE_TZ , worden bestaande kolommen niet automatisch geconverteerd.

Vervang in de volgende stappen de tijdelijke aanduidingen:

• <table-name>: de tabelnaam die de kolom bevat.
• <datetime-column>: de kolomnaam die moet worden geconverteerd.
• <offset>: De tijdzone-offset van uw bestaande gegevens als een tekenreeks in {+|-}HH:MM notatie (bijvoorbeeld '-05:00' voor US Eastern).

De codevoorbeelden in dit artikel gebruiken de AdventureWorks2025 of AdventureWorksDW2025 voorbeelddatabase die u kunt downloaden van de startpagina van Microsoft SQL Server Samples en Community Projects .

Stap 1: Kolomtypen wijzigen

Voer de volgende SQL uit op elke tabel met datum/tijd2-kolommen . SQL Server de waarde impliciet converteert en een +00:00 offset toewijst:

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

Stap 2: Converteren naar UTC

Nadat de kolom datetimeoffset is, tagt u elke waarde opnieuw met de oorspronkelijke offset van de lokale tijdzone en converteert u naar UTC:

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

TODATETIMEOFFSET vervangt het offsetgedeelte van de datum/tijdoffset-waarde , zodat het tijdstempel de oorspronkelijke lokale tijd weerspiegelt. AT TIME ZONE 'UTC' converteert vervolgens het resultaat naar UTC.

SQL Server tijdzonenamen

Gebruik Windows tijdzonenamen bij het converteren met AT TIME ZONE. Veelvoorkomende voorbeelden:

Voer een query uit voor een volledige lijst SQL Server:

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

Zie sys.time_zone_info voor volledige documentatie.

Voorbeeld: Amerikaanse Eastern Time omzetten naar UTC (rekening houdend met zomertijd)

In dit voorbeeld wordt een bestaande AdventureWorks2025 schematabel gebruikt en wordt de juiste DST-verwerking tijdens de migratie gedemonstreert:

-- 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;

Als u uw toepassingstabellen wilt migreren, past u hetzelfde AT TIME ZONE conversiepatroon toe op uw eigen DateTimeField kolommen. Voeg voor elke tabel een datetimeoffset-kolom toe en vul deze in vanuit de bestaande kolom:

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';

Nadat u de conversieresultaten hebt gecontroleerd, zet u de oude kolom neer en wijzigt u de naam van de nieuwe kolom:

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

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

Gebruik de SQL Server Windows tijdzonenaam die overeenkomt met uw brongegevensregio. Zie sys.time_zone_info voor meer informatie.

Stap 3: De Django-migratie voltooien

Nadat u de databasekolommen hebt geconverteerd, volgt u de documentatie van Django over het migreren van een project dat is gestart voordat ondersteuning voor tijdzones werd toegevoegd.

Limitations

• Tijdzones en timedeltas: Niet alle bewerkingen met tijdzones en timedeltas worden volledig ondersteund. Zie Beperkingen en niet-ondersteunde functies in mssql-django voor meer informatie.
• Rekenkundige bewerkingen met datum/tijd: Rechtshandige macht en rekenkundige bewerkingen met datum/tijd-waarden werken mogelijk niet zoals verwacht wanneer ondersteuning voor tijdzones is ingeschakeld.

Verwante inhoud

• Django-veld voor SQL Server typetoewijzingen
• naslaginformatie voor mssql-django-configuratie
• Beperkingen en niet-ondersteunde functies in mssql-django
• Ondersteuningswiki voor tijdzones
• Documentatie voor Django-tijdzone