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