mssql-python 모듈 설정 설정

mssql-python 드라이버는 모듈 전체의 동작을 제어하는 클래스를 Settings 제공합니다. 이 설정들은 모든 연결과 커서 작업에 영향을 미칩니다. 애플리케이션을 시작할 때 한 번 설정하고, 연결을 만들기 전에 꼭 설정하세요.

접근 설정

현재 Settings 객체를 검색하여 그 속성을 검사하거나 수정하세요:

import mssql_python

# Get settings object
settings = mssql_python.get_settings()

# Check current values
print(settings.lowercase)
print(settings.decimal_separator)

사용 가능한 설정

다음 설정은 드라이버가 데이터를 반환하고 결과를 포맷하는 방식을 제어합니다.

소문자

이 설정은 lowercase 열명이 cursor.description 소문자로 표시되는지 여부를 제어합니다. 애플리케이션이 이름으로 열에 액세스할 때 대소문자 불일치를 방지하려면 이 설정을 활성화하세요. Flask와 FastAPI 같은 웹 프레임워크는 종종 행을 사전으로 변환하여 일관된 케이싱이 중요합니다:

settings = mssql_python.get_settings()

# Enable lowercase column names (default: False)
settings.lowercase = True

# Column names in cursor.description are now lowercased:
# ('productid', ...) instead of ('ProductID', ...)

값	설명
`False`	Default. 기둥 이름은 원래 케이싱을 보존합니다.
`True`	열 `cursor.description` 명은 소문자로 변환됩니다.

소수 구분 기호

드라이버는 수치 변환을 위한 십진수 구분자를 제어하는 모듈 수준의 기능을 제공합니다. 이 설정을 변경하는 것은 SQL Server 인스턴스가 프랑스어나 독일어 로케이지처럼 쉼표를 사용하는 경우에만 해당됩니다. 대부분의 애플리케이션은 이 설정을 변경할 필요가 없습니다:

import mssql_python

# Get current separator
sep = mssql_python.getDecimalSeparator()
print(f"Current separator: {sep}")  # Usually "."

# Set custom separator (for locales using comma)
mssql_python.setDecimalSeparator(",")

십진수 처리에 대한 자세한 내용은 데이터 타입 매핑을 참조하세요.

native_uuid

native_uuid 설정은 UNIQUEIDENTIFIER 열이 Python uuid.UUID 객체로 반환되는지, 아니면 pyodbc와 호환되는 대문자 문자열로 반환되는지를 결정합니다. 이 설정은 문자열 UUID 값에 의존하는 pyodbc에서 마이그레이션하는 팀에 유용합니다:

settings = mssql_python.get_settings()

# Return UUIDs as uuid.UUID objects (default: True)
settings.native_uuid = True

# Return UUIDs as uppercase strings (pyodbc-compatible)
settings.native_uuid = False

값	설명
`True`	Default. `UNIQUEIDENTIFIER` 열은 `uuid.UUID` 객체를 반환합니다.
`False`	`UNIQUEIDENTIFIER` 열은 대문자 문자열을 반환합니다(pyodbc 호환).

연결별로도 native_uuid 설정할 수 있습니다:

# Override for a specific connection
conn = mssql_python.connect(connection_string, native_uuid=False)

비고

이 설정은 native_uuid mssql-python 버전 1.5.0에서 도입되었습니다.

모듈 수준 상수

드라이버는 읽기 전용 DB-API 2.0 컴플라이언스 상수를 노출하여 기능을 설명합니다. 다음 상수를 사용해 다양한 DB-API 드라이버에 적응하는 코드를 작성하세요:

import mssql_python

# DB-API 2.0 compliance level
print(mssql_python.apilevel)      # '2.0'

# Thread safety level
print(mssql_python.threadsafety)  # 1

# Parameter style
print(mssql_python.paramstyle)    # 'pyformat'

APILEVEL

apilevel Constant는 DB-API 준수 수준을 보고합니다:

값	Meaning
`'2.0'`	완전 DB-API 2.0 준수.

스레드세이프티

threadsafety 상수는 스레드 안전 수준을 보고합니다:

값	Meaning
`0`	스레드는 모듈을 공유할 수 없습니다.
`1`	스레드는 모듈을 공유할 수 있지만 연결은 공유할 수 없습니다.
`2`	스레드는 모듈과 연결을 공유할 수 있습니다.
`3`	스레드는 모듈, 연결, 커서를 공유할 수 있습니다.

mssql-python 드라이버는 threadsafety = 1를 사용하며, 이는 다음을 의미합니다:

모듈을 스레드 간에 가져오고 사용할 수 있습니다.
각 연결은 한 번에 한 스레드에만 속해야 합니다.
스레드별로 별도의 연결을 만들거나, 기본적으로 활성화된 연결 풀을 사용하세요. 자세한 내용은 연결 풀링을 참조하세요.

패러마스타일

paramstyle 상수는 매개변수 자리 표시자 형식을 보고합니다:

Style	Format	예시
`'qmark'`	물음표	`WHERE id = ?`
`'numeric'`	숫자 위치	`WHERE id = :1`
`'named'`	명명된	`WHERE id = :id`
`'format'`	ANSI C printf	`WHERE id = %s`
`'pyformat'`	Python 형식	`WHERE id = %(id)s`

mssql-python 드라이버는 paramstyle = 'pyformat'를 사용합니다. SQL 인젝션을 방지하기 위해 항상 이름 있는 매개변수를 사용하세요. 사용자 입력으로 문자열 형식이나 f-문자열을 통해 쿼리를 만들지 마세요:

# Use named parameters with %(name)s syntax
cursor.execute(
    "SELECT * FROM Production.Product WHERE ProductSubcategoryID = %(cat)s AND ListPrice > %(price)s",
    {"cat": 5, "price": 10.00}
)

버전 정보

어떤 버전의 드라이버가 설치되어 있는지 확인하세요:

import mssql_python

# Driver version
print(mssql_python.__version__)  # e.g., '1.15.0'

시작 시 설정 설정

애플리케이션 시작 시 모듈 구성을 한 번 설정하세요. 연결 생성 전에 말이죠. 값을 일찍 설정하면 연결 간 불일치 동작을 방지할 수 있습니다:

import mssql_python

def configure_driver():
    """Configure mssql-python settings for this application."""
    settings = mssql_python.get_settings()
    
    # Use lowercase column names in cursor.description
    settings.lowercase = True

# Call at application startup
configure_driver()

# All subsequent connections use these settings
conn = mssql_python.connect(connection_string)

스레드 안전 고려사항

모듈 설정은 전역적이며 모든 스레드 간 모든 연결에 영향을 미칩니다. 연결을 이미 열어둔 후에 설정을 변경하면, 기존 연결이 변화를 일관되게 반영하지 않을 수 있습니다. 첫 연결을 만들기 전에 모든 구성 값을 설정하세요:

import mssql_python
import threading

# Settings changes affect all threads
settings = mssql_python.get_settings()
settings.lowercase = True  # Affects all connections in all threads

def worker():
    # This connection uses the global settings
    conn = mssql_python.connect(connection_string)
    cursor = conn.cursor()
    cursor.execute("SELECT Name FROM Production.Product")
    row = cursor.fetchone()
    print(cursor.description[0][0])  # 'name' due to global setting

threads = [threading.Thread(target=worker) for _ in range(5)]
for t in threads:
    t.start()
for t in threads:
    t.join()

중요합니다

연결을 만들기 전에 설정을 설정하세요. 연결이 생성된 후 설정을 변경하면 일관성 없는 동작이 발생할 수 있습니다.

연결별 구성

전역 기본값을 바꾸지 않고도 연결별로 일부 설정을 변경할 수 있습니다. 애플리케이션의 각 부분이 서로 다른 동작을 요구할 때는 연결별 오버라이드를 사용하세요. 예를 들어, 보고 모듈에는 문자열 UUID가 필요할 수 있는 반면, 애플리케이션의 나머지 부분에서는 uuid.UUID 객체를 사용할 수 있습니다:

# Per-connection native_uuid override
conn = mssql_python.connect(connection_string, native_uuid=False)

# Use the autocommit property
conn.autocommit = True

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-09-14