Unterstützung der Zeitzone in mssql-django

In diesem Artikel wird erläutert, wie Zeitzonenfähige Datumstimefelder mit SQL Server über das mssql-django Back-End funktionieren und wie vorhandene Daten migriert werden, wenn Sie die Unterstützung für Zeitzonen aktivieren.

Funktionsweise der Zeitzonenunterstützung

Die Einstellung USE_TZ in settings.py von Django steuert, ob Datum/Uhrzeit-Felder Zeitzoneninformationen berücksichtigen:

Aktivieren der Zeitzonenunterstützung

Legen Sie USE_TZ=True in Ihrem settings.py fest:

USE_TZ=True
TIME_ZONE = "UTC"

Wenn USE_TZ diese Option aktiviert ist, speichert Django alle Datetimes in UTC und konvertiert sie zur Anzeige in die lokale Zeitzone.

Ab mssql-django 1.7.2 gleicht das Backend auch das Django-Verhalten Now() an die zeitzonenbewusste SQL-Generierung an, wenn USE_TZ=True.

Migrieren vorhandener Datetime-Spalten

Wenn Ihre Django-App vor dem Aktivieren von DateTimeFieldUSE_TZ=True bereits Spalten vom Typ datetime2 enthielt, müssen Sie diese manuell in datetimeoffset migrieren und die lokale Zeit in UTC konvertieren.

Das mssql-django Backend verwendet datetime2 als zugrunde liegenden Spaltentyp für DateTimeField, wenn USE_TZ=False. Durch aktivieren USE_TZ werden vorhandene Spalten nicht automatisch konvertiert.

Ersetzen Sie in den folgenden Schritten die Platzhalter:

• <table-name>: Der Tabellenname, der die Spalte enthält.
• <datetime-column>: Der zu konvertierende Spaltenname.
• <offset>: Der Zeitzonen-Offset Ihrer bestehenden Daten als Zeichenfolge im Format {+|-}HH:MM (z. B. '-05:00' für die US-Ostküstenzeit).

Die Codebeispiele in diesem Artikel verwenden die AdventureWorks2025- oder AdventureWorksDW2025 Beispieldatenbank, die Sie von der Microsoft SQL Server Samples and Community Projects Homepage herunterladen können.

Schritt 1: Ändern von Spaltentypen

Führen Sie die folgende SQL-Datei für jede Tabelle mit Datetime2-Spalten aus. SQL Server wandelt den Wert implizit um und weist einen +00:00 Offset zu:

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

Schritt 2: Konvertieren in UTC

Nachdem die Spalte "datetimeoffset" lautet, markieren Sie jeden Wert erneut mit dem ursprünglichen Offset für die lokale Zeitzone, und konvertieren Sie dann in UTC:

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

TODATETIMEOFFSET Ersetzt den Offsetteil des Datetimeoffset-Werts , sodass der Zeitstempel die ursprüngliche lokale Uhrzeit wiedergibt. AT TIME ZONE 'UTC' konvertiert dann das Ergebnis in UTC.

SQL Server Zeitzonennamen

Verwenden Sie Windows Zeitzonennamen beim Konvertieren mit AT TIME ZONE. Häufige Beispiele:

Abfrage SQL Server für eine vollständige Liste:

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

Vollständige Dokumentation finden Sie unter sys.time_zone_info .

Beispiel: Konvertieren der US-Ostzeit in UTC (DST-aware)

In diesem Beispiel wird eine vorhandene AdventureWorks2025 Schematabelle verwendet und die korrekte DST-Behandlung während der Migration veranschaulicht:

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

Um Ihre Anwendungstabellen zu migrieren, wenden Sie dasselbe AT TIME ZONE Konvertierungsmuster auf Ihre eigenen DateTimeField Spalten an. Fügen Sie für jede Tabelle eine Datetimeoffset-Spalte hinzu, und füllen Sie sie aus der vorhandenen Spalte auf:

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

Nachdem Sie die Konvertierungsergebnisse überprüft haben, löschen Sie die alte Spalte und benennen Sie die neue Spalte um:

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

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

Verwenden Sie den SQL Server Windows Zeitzonennamen, der Ihrem Quelldatenbereich entspricht. Weitere Informationen finden Sie unter sys.time_zone_info.

Schritt 3: Abschließen der Django-Migration

Nachdem Sie die Datenbankspalten konvertiert haben, folgen Sie der Dokumentation von Django zum Migrieren eines Projekts, das vor dem Hinzufügen der Zeitzonenunterstützung gestartet wurde.

Einschränkungen

• Zeitzonen und Timedeltas: Nicht alle Vorgänge mit Zeitzonen und Timedeltas werden vollständig unterstützt. Weitere Informationen finden Sie unter Einschränkungen und nicht unterstützte Features in mssql-django.
• Arithmetik mit Datetimes: Rechtschreibkraft und Arithmetik mit Datetime-Werten funktionieren möglicherweise nicht wie erwartet, wenn die Unterstützung für Zeitzonen aktiviert ist.

Verwandte Inhalte

• Zuordnungen von Django-Feldern zu SQL-Server-Typen
• mssql-django-Konfigurationsreferenz
• Einschränkungen und nicht unterstützte Features in mssql-django
• Unterstützungswiki für Zeitzonen
• Django-Zeitzonendokumentation