Time zone support in mssql-django

This article explains how time zone-aware datetime fields work with SQL Server through the mssql-django backend and how to migrate existing data when you enable time zone support.

How time zone support works

Django's USE_TZ setting in settings.py controls whether datetime fields are time zone-aware:

Enable time zone support

Set USE_TZ=True in your settings.py:

USE_TZ=True
TIME_ZONE = "UTC"

When USE_TZ is enabled, Django stores all datetimes in UTC and converts them to the local time zone for display.

Starting with mssql-django 1.7.2, the backend also aligns Django Now() behavior with time zone-aware SQL generation when USE_TZ=True.

Migrate existing datetime columns

If your Django app had DateTimeField columns before enabling USE_TZ=True, you must manually migrate datetime2 columns to datetimeoffset and convert local time to UTC.

The mssql-django backend uses datetime2 as the underlying column type for DateTimeField when USE_TZ=False. Enabling USE_TZ doesn't automatically convert existing columns.

In the following steps, replace the placeholders:

• <table-name>: The table name containing the column.
• <datetime-column>: The column name to convert.
• <offset>: The time zone offset of your existing data as a string in {+|-}HH:MM format (for example, '-05:00' for US Eastern).

The code samples in this article use the AdventureWorks2025 or AdventureWorksDW2025 sample database, which you can download from the Microsoft SQL Server Samples and Community Projects home page.

Step 1: Alter column types

Run the following SQL on each table that has datetime2 columns. SQL Server implicitly converts the value and assigns a +00:00 offset:

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

Step 2: Convert to UTC

After the column is datetimeoffset, re-tag each value with the original local time zone offset and then convert to UTC:

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

TODATETIMEOFFSET replaces the offset portion of the datetimeoffset value so the timestamp reflects the original local time. AT TIME ZONE 'UTC' then converts the result to UTC.

SQL Server time zone names

Use Windows time zone names when converting with AT TIME ZONE. Common examples:

For a complete list, query SQL Server:

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

See sys.time_zone_info for full documentation.

Example: Convert US Eastern time to UTC (DST-aware)

This example uses an existing AdventureWorks2025 schema table and demonstrates correct DST handling during migration:

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

To migrate your application tables, apply the same AT TIME ZONE conversion pattern to your own DateTimeField columns. For each table, add a datetimeoffset column and populate it from the existing column:

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

After you verify the conversion results, drop the old column and rename the new one:

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 the SQL Server Windows time zone name that matches your source data region. For more information, see sys.time_zone_info.

Step 3: Complete the Django migration

After converting the database columns, follow Django's documentation on migrating a project started before time zone support was added.

Limitations

• Time zones and timedeltas: Not all operations involving time zones and timedeltas are fully supported. For more information, see Limitations and unsupported features in mssql-django.
• Arithmetic with datetimes: Righthand power and arithmetic with datetime values might not work as expected when time zone support is enabled.

Related content

• Django field to SQL Server type mappings
• mssql-django configuration reference
• Limitations and unsupported features in mssql-django
• Time zone support wiki
• Django time zone documentation