mssql-django의 표준 시간대 지원

이 문서에서는 표준 시간대 인식 날짜/시간 필드가 백 엔드를 통해 mssql-django SQL Server 작동하는 방법과 표준 시간대 지원을 사용하도록 설정할 때 기존 데이터를 마이그레이션하는 방법을 설명합니다.

표준 시간대 지원 작동 방식

Django의 USE_TZ 설정은 settings.py 날짜/시간 필드가 표준 시간대 인식인지 여부를 제어합니다.

설정 열 형식 Behavior
USE_TZ=False datetime2 표준 시간대 정보 없이 순진한 날짜/시간을 저장합니다.
USE_TZ=True datetimeoffset UTC 오프셋을 사용하여 표준 시간대 인식 날짜/시간을 저장합니다.

메모

Django 5.2, 6.0 및 6.1에서는 기본적으로 USE_TZ를 True(으)로 설정하므로, settings.py에서 이를 False(으)로 설정하지 않는 한 시간대 지원이 활성화됩니다. 자세한 내용은 Django의 표준 시간대 지원을 참조하세요. datetimeoffset은 일반적으로 동일한 타임스탬프 정밀도에 datetime2보다 더 많은 스토리지를 사용하므로 큰 테이블에서는 마이그레이션 후 스토리지 및 쿼리 계획의 유효성을 검사해야 합니다.

표준 시간대 지원 사용

USE_TZ=True을(를) settings.py에서 설정하세요:

USE_TZ=True
TIME_ZONE = "UTC"

사용하도록 설정하면 USE_TZ Django는 모든 날짜/시간을 UTC에 저장하고 표시할 현지 표준 시간대로 변환합니다.

mssql-django 2.0부터 백엔드는 tzdata 대신 zoneinfo 패키지와 함께 표준 라이브러리 pytz 모듈을 사용합니다. tzdata 패키지는 Windows 및 최소 컨테이너 이미지처럼 IANA 시간대 데이터베이스를 제공하지 않는 시스템에 해당 데이터베이스를 제공합니다. 이 변경은 음의 일광절약 시간제 오프셋이 있는 구역에 대한 잘못된 오프셋을 수정합니다.

기존 날짜/시간 열 마이그레이션

Django 앱에 DateTimeField 열이 있었고 USE_TZ=True를 사용하도록 설정하기 전이라면, datetime2 열을 datetimeoffset으로 수동으로 마이그레이션하고 로컬 시간을 UTC로 변환해야 합니다.

mssql-django인 경우 백엔드는 에 대한 기본 열 형식으로 DateTimeField를 사용합니다. 사용하도록 설정 USE_TZ 해도 기존 열이 자동으로 변환되지는 않습니다.

다음 단계에서 자리 표시자를 바꿉다.

  • <table-name>: 열을 포함하는 테이블 이름입니다.
  • <datetime-column>: 변환할 열 이름입니다.
  • <offset>: 기존 데이터의 시간대 오프셋을 나타내는 {+|-}HH:MM 형식의 문자열(예: 미국 동부의 경우 '-05:00').

이 글의 코드 샘플은 Azure Data SQL Samples Repository GitHub 저장소에서 다운로드할 수 있는 , , AdventureWorksDW2025또는 AdventureWorksLT2025 샘플 데이터베이스를 사용합니다AdventureWorks2025.

1단계: 열 형식 변경

datetime2 열이 있는 각 테이블에서 다음 SQL을 실행합니다. SQL Server 값을 암시적으로 변환하고 오프셋을 +00:00 할당합니다.

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

2단계: UTC로 변환

열이 datetimeoffset이 되면 각 값의 태그를 원래 현지 표준 시간대 오프셋으로 다시 지정한 다음 UTC로 변환합니다.

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

TODATETIMEOFFSET 는 datetimeoffset 값의 오프셋 부분을 대체하여 타임스탬프가 원래 현지 시간을 반영합니다. AT TIME ZONE 'UTC' 그런 다음 결과를 UTC로 변환합니다.

Important

단일 고정 오프셋은 모든 원본 값이 동일한 오프셋을 공유하는 경우에만 작동합니다. 데이터가 일광 절약 전환에 걸쳐 있는 경우 모든 행에 하나의 상수 오프셋을 적용하는 대신 날짜별로 오프셋을 파생하거나 표준 시간대 이름 기반 변환 전략을 사용합니다.

SQL Server 시간대 이름

로 변환AT TIME ZONE할 때 Windows 표준 시간대 이름을 사용합니다. 일반적인 예:

Region SQL Server 표준 시간대 이름 DST 전환 날짜(2026)
미국 동부 Eastern Standard Time 3월 8일부터 11월 1일까지
미국 중부 Central Standard Time 3월 8일부터 11월 1일까지
미국 태평양 Pacific Standard Time 3월 8일부터 11월 1일까지
UTC UTC 없음(DST 없음)
유럽/런던 GMT Standard Time 3월 29일부터 10월 25일까지

전체 목록을 보려면 SQL Server를 쿼리합니다.

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

전체 설명서는 sys.time_zone_info 참조하세요.

예: 미국 동부 시간을 UTC로 변환(DST 인식)

이 예제에서는 기존 AdventureWorks2025 스키마 테이블을 사용하고 마이그레이션 중에 올바른 DST 처리를 보여 줍니다.

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

항상 DST 전환 날짜에 걸쳐 있는 데이터를 사용하여 표준 시간대 변환을 테스트합니다. 이전 쿼리는 동부 시간이 EST(UTC-5)에서 EDT(UTC-4)로 변경되는 3월 8일(봄 앞으로)을 테스트합니다.

애플리케이션 테이블을 마이그레이션하려면 고유한 AT TIME ZONE 열에 동일한 DateTimeField 변환 패턴을 적용합니다. 각 테이블에 대해 datetimeoffset 열을 추가하고 기존 열에서 채웁니다.

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

변환 결과를 확인한 후 이전 열을 삭제하고 새 열의 이름을 바꿉니다.

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

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

원본 데이터 영역과 일치하는 SQL Server Windows 표준 시간대 이름을 사용합니다. 자세한 내용은 sys.time_zone_info 참조하세요.

3단계: Django 마이그레이션 완료

데이터베이스 열을 변환한 후 표준 시간대 지원이 추가되기 전에 시작된 프로젝트 마이그레이션에 대한 Django의 설명서를 따릅니다.

Important

모든 테이블의 모든 DateTimeField 열에서 이 마이그레이션을 실행합니다. 열 중 하나라도 누락되면 해당 필드의 시간대 처리가 올바르게 되지 않습니다.

Limitations

  • 표준 시간대 및 표준 시간대: 표준 시간대 및 표준 시간대와 관련된 모든 작업이 완전히 지원되는 것은 아닙니다. 자세한 내용은 mssql-django의 제한 사항 및 지원되지 않는 기능을 참조하세요.
  • 날짜/시간을 사용한 산술 연산: 표준 시간대 지원이 활성화된 경우 우변 거듭제곱 및 날짜/시간 값을 사용한 산술 연산이 예상대로 작동하지 않을 수 있습니다.

관련 콘텐츠

  • 에 마지막으로 업데이트됨