Az időzóna támogatása az mssql-django-ban

Ez a cikk bemutatja, hogyan működnek az időzóna-kompatibilis dátum/idő mezők SQL Server a háttérrendszeren keresztül, és hogyan migrálhatók a mssql-django meglévő adatok az időzóna-támogatás engedélyezésekor.

Az időzóna támogatása

A Django USE_TZ beállítása a(z) settings.py fájlban szabályozza, hogy a datetime mezők időzóna-kezelők-e:

Setting Oszloptípus Magatartás
USE_TZ=False datetime2 A naiv dátumidőket időzóna-információk nélkül tárolja.
USE_TZ=True datetimeoffset Az időzóna-tudatú dátumidőket UTC-eltolással tárolja.

Note

A Django alapértelmezés szerint a USE_TZ=False beállítást használja az összes verzióban, beleértve a Django 5.x és 6.0 verziókat is. Ha a projektjének szüksége van időzóna-támogatásra, akkor explicit módon be kell állítania a(z) USE_TZ=True elemet a settings.py fájlban. További információkért tekintse meg az időzóna támogatását a Django-ban . Vegye figyelembe, hogy a datetimeoffset általában a datetime2-nél több tárterületet használ ugyanahhoz az időbélyeg-pontossághoz, ezért nagy táblák esetén a migrálás után ellenőriznie kell a tárolási és lekérdezési terveket.

Időzóna támogatásának engedélyezése

Állítsa be a(z) USE_TZ=True elemet itt: settings.py:

USE_TZ=True
TIME_ZONE = "UTC"

Ha USE_TZ engedélyezve van, a Django az összes dátumot UTC-ben tárolja, és a megjelenítéshez a helyi időzónába konvertálja őket.

mssql-django Az 1.7.2-től kezdve a háttérrendszer a Django Now() viselkedését is igazítja az időzóna-alapú SQL-generációhoz, amikor USE_TZ=True.

Meglévő datetime-oszlopok migrálása

Ha a Django-alkalmazásnak a(z) USE_TZ=True engedélyezése előtt DateTimeField oszlopai voltak, manuálisan kell migrálnia a datetime2 oszlopokat datetimeoffset típusra, és a helyi időt UTC-re kell átalakítania.

A mssql-django háttérrendszer a datetime2 típust használja mögöttes oszloptípusként a(z) DateTimeField esetén, amikor USE_TZ=False. Az USE_TZ engedélyezés nem konvertálja automatikusan a meglévő oszlopokat.

A következő lépésekben cserélje ki a helyőrzőket:

  • <table-name>: Az oszlopot tartalmazó tábla neve.
  • <datetime-column>: Az átalakítandó oszlop neve.
  • <offset>: A meglévő adatai időzónaeltolása egy {+|-}HH:MM formátumú karakterláncként (például '-05:00' az USA keleti parti időzónájához).

A cikkben szereplő kódminták a AdventureWorks2025 vagy AdventureWorksDW2025 mintaadatbázist használják, amelyet a Microsoft SQL Server-minták és közösségi projektek kezdőlapjáról tölthet le.

1. lépés: Oszloptípusok módosítása

Futtassa a következő SQL-t minden olyan táblán, amely datetime2 oszlopokkal rendelkezik. SQL Server implicit módon konvertálja az értéket, és eltolást +00:00 rendel hozzá:

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

2. lépés: Konvertálás UTC-vé

Miután az oszlopot datetimeoffset típusúvá alakította, lásson el újra minden értéket az eredeti helyi időzóna-eltolással, majd konvertálja UTC-re:

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

TODATETIMEOFFSET a datetimeoffset érték eltolásrészét cseréli le, így az időbélyeg az eredeti helyi időt tükrözi. AT TIME ZONE 'UTC' ezután az eredményt UTC-vé alakítja.

Important

Egyetlen rögzített eltolás csak akkor működik, ha az összes forrásérték azonos eltolással rendelkezik. Ha az adatok átfedik a nyári időszámítást, az eltolást dátum alapján kell levezetni, vagy időzóna-alapú konverziós stratégiát használni ahelyett, hogy minden sorra egy állandó eltolást alkalmazna.

Az SQL Server időzónanevei

Konvertáláskor használja a Windows időzónaneveit a(z) AT TIME ZONE használatával. Gyakori példák:

Régió SQL Server időzóna neve DST-áttűnési dátumok (2026)
USA keleti régiója Eastern Standard Time Márc. 8 – Nov 1
USA középső régiója Central Standard Time Márc. 8 – Nov 1
USA csendes-óceáni térsége Pacific Standard Time Márc. 8 – Nov 1
egyezményes világidő UTC Nincs (nincs DST)
Európa/London GMT Standard Time márc. 29 – október 25.

A teljes lista lekérdezéséhez SQL Server:

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

A teljes dokumentációért lásd: sys.time_zone_info.

Példa: az amerikai keleti parti idő átváltása UTC-re (a nyári időszámítást figyelembe véve)

Ez a példa egy meglévő AdventureWorks2025 sématáblát használ, és a migrálás során a megfelelő DST-kezelést mutatja be:

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

Tip

Mindig tesztelje az időzóna-átalakításokat a DST-áttűnési dátumokra kiterjedő adatokkal. Az előző lekérdezés március 8-át teszteli (tavaszi óraátállítás), amikor a keleti idő EST-ről (UTC-5) EDT-re (UTC-4) vált.

Az alkalmazás tábláinak migrálásához alkalmazza ugyanezt a(z) AT TIME ZONE átalakítási mintát a saját DateTimeField oszlopaira. Minden táblához adjon hozzá egy datetimeoffset oszlopot , és töltse ki a meglévő oszlopból:

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

Az átalakítás eredményeinek ellenőrzése után helyezze el a régi oszlopot, és nevezze át az újat:

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

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

Használja a forrásadat-régiónak megfelelő SQL Server Windows időzónanevet. További információ: sys.time_zone_info.

3. lépés: A Django migrálásának befejezése

Az adatbázisoszlopok konvertálása után kövesse Django dokumentációját egy projekt migrálásáról az időzóna támogatásának hozzáadása előtt.

Important

Futtassa ezt a migrációt az összes táblában található összes DateTimeField oszlopra. Ha valamelyik oszlop hiányzik, az adott mezők időzóna-kezelése helytelen lesz.

Limitations

  • Időzónák és idődeltasok: Nem minden időzónát és idődeltát tartalmazó művelet támogatott teljes mértékben. További információ: Az mssql-django korlátozásai és nem támogatott funkciói.
  • Aritmetikai műveletek dátum- és időértékekkel: Előfordulhat, hogy a jobboldali hatványozás és a dátum- és időértékekkel végzett aritmetikai műveletek nem a várt módon működnek, ha az időzóna-támogatás engedélyezve van.

Kapcsolódó tartalom

  • Last updated on