mssql-django의 표준 시간대 지원

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

표준 시간대 지원 작동 방식

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

표준 시간대 지원 사용

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

USE_TZ=True
TIME_ZONE = "UTC"

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

mssql-django 1.7.2부터 백 엔드는 Django Now() 동작을 표준 시간대 인식 SQL 생성 USE_TZ=True시에도 맞춥니다.

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

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

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

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

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

이 문서의 코드 샘플은 AdventureWorks2025 또는 AdventureWorksDW2025 샘플 데이터베이스를 사용합니다. 이 데이터베이스는 Microsoft SQL Server 샘플 및 커뮤니티 프로젝트 홈페이지에서 다운로드할 수 있습니다.

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로 변환합니다.

SQL Server 시간대 이름

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

전체 목록을 보려면 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;

애플리케이션 테이블을 마이그레이션하려면 고유한 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의 설명서를 따릅니다.

Limitations

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

관련 콘텐츠

• Django 필드의 SQL Server 형식 매핑
• mssql-django 구성 참조
• mssql-django의 제한 사항 및 지원되지 않는 기능
• 표준 시간대 지원 wiki
• Django 표준 시간대 설명서