mssql-python으로 연결을 관리하세요

대부분의 애플리케이션은 간단한 패턴을 따릅니다: 연결을 열고, 쿼리를 실행하고, 연결을 종료합니다. 다음 섹션에서는 연결을 열고 닫는 방법, 컨텍스트 관리자 사용, 자동 커밋 설정, 연결 속성 활용에 대해 다룹니다.

연결을 열어

connect() 기능을 사용해 연결을 설정하세요. 서버, 데이터베이스, 인증 정보가 포함된 연결 문자열을 전달하세요:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;"
    "Authentication=ActiveDirectoryDefault;Encrypt=yes"
)

함수는 connect() 다음을 받아들입니다:

첫 번째 위치 인수 또는 connection_str 키워드로 연결 문자열을 사용한다.
드라이버가 연결 문자열에 병합하는 개별 키워드들.
기타 옵션으로는 autocommit, timeout, attrs_before 등이 있습니다.

두 가지 방식을 섞어도 됩니다. 연결 문자열의 키워드 값은 연결 문자열의 다른 값을 재정의하므로, 구성에 기본 연결 문자열을 저장해 두고 호출할 때마다 timeout 같은 설정을 재정의하는 경우에 유용합니다:

# Base connection string from config, with per-call overrides
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;"
    "Authentication=ActiveDirectoryDefault;Encrypt=yes",
    timeout=30,
    autocommit=True
)

연결을 닫으세요

작업이 끝나면 항상 연결을 닫아 연결 풀로 반환하고 서버 자원을 해제하세요. 닫히지 않은 연결은 서버 측 메모리를 보유하며 결국 연결 풀을 소진시켜 새로운 연결 시도가 차단되거나 실패할 수 있습니다.

conn = mssql_python.connect(connection_string)
try:
    # Use the connection
    cursor = conn.cursor()
    cursor.execute("SELECT 1")
finally:
    conn.close()

한 번 닫히면 다음 용도로 연결할 수 없습니다:

conn.close()
print(conn.closed)  # True

# This raises an error
cursor = conn.cursor()  # InterfaceError: Cannot create cursor on closed connection

close()를 여러 번 호출해도 안전합니다(멱등적임):

conn.close()
conn.close()  # No error

컨텍스트 관리자

대부분의 애플리케이션에서 연결 관리를 위해 이 with 문장을 사용하세요. 이 기능은 예외가 발생하더라도 블록이 종료될 때 드라이버가 연결을 종료하도록 보장합니다. 이 방법은 잊혀진 close() 통화로 인한 연결 유출 위험을 제거합니다:

with mssql_python.connect(connection_string) as conn:
    cursor = conn.cursor()
    cursor.execute("CREATE TABLE #Demo (Name NVARCHAR(50))")
    cursor.execute("INSERT INTO #Demo (Name) VALUES ('Widget')")
    conn.commit()  # Must commit explicitly when autocommit=False
# Connection automatically closed

컨텍스트 매니저는 종료 시 연결을 종료합니다. 트랜잭션을 자동으로 커밋하거나 롤백하지 않습니다 :

항상: 예외가 있었든 없든 퇴장 시 호출 close() .
close() 동작: 만약 이면 autocommit=False, 연결이 종료될 때 커밋되지 않은 변경 사항은 롤백됩니다.
변경 사항을 지속하려면 명시적으로 호출 conn.commit() 해야 합니다.

이 설계는 PEP 249 동작을 따르며 우발적인 부분 커밋을 방지합니다. 코드가 commit()에 도달하기 전에 예외가 발생하면, 진행 중인 트랜잭션은 안전하게 롤백됩니다:

# Equivalent manual code:
conn = mssql_python.connect(connection_string)
try:
    cursor = conn.cursor()
    cursor.execute("CREATE TABLE #Demo (Name NVARCHAR(50))")
    cursor.execute("INSERT INTO #Demo (Name) VALUES ('Widget')")
    conn.commit()  # Must commit explicitly
finally:
    conn.close()  # Rolls back uncommitted changes if autocommit=False

자동 커밋 모드

기본적으로 autocommit=False, 는 각 문이 암묵적 트랜잭션 내에서 실행된다는 의미입니다. 변경 사항을 저장하려면 conn.commit()를 호출하고, 버리려면 conn.rollback()를 호출해야 합니다. 암묵적 트랜잭션은 여러 문장을 하나의 원자 연산으로 묶을 수 있기 때문에 데이터 수정에 가장 안전한 선택입니다.

각 문을 즉시 커밋하고 싶을 때 자동 커밋을 활성화하세요. 자동 커밋은 DDL 작업(CREATE TABLE, ALTER INDEX), 읽기 전용 작업 부하 또는 트랜잭션 그룹화가 필요하지 않은 관리 스크립트에 유용합니다:

conn = mssql_python.connect(connection_string)
print(conn.autocommit)  # False

cursor = conn.cursor()
cursor.execute("CREATE TABLE #Demo (Name NVARCHAR(50))")
cursor.execute("INSERT INTO #Demo (Name) VALUES ('Widget')")
conn.commit()  # Required to persist changes

각 문장이 즉시 커밋되도록 자동 커밋을 활성화하세요. 연결할 때 autocommit=True를 사용하거나, setautocommit()로 연결한 후 또는 속성에 직접 할당하여 전환할 수 있습니다:

# At connection time
conn = mssql_python.connect(connection_string, autocommit=True)

# Or after connection (both forms work)
conn.setautocommit(True)
conn.autocommit = True
print(conn.autocommit)  # True

# Now changes are committed automatically
cursor = conn.cursor()
cursor.execute("SELECT TOP 1 Name FROM Production.Product")
print(cursor.fetchone().Name)
# No commit() needed

연결 시간 초과

운전자는 두 번의 독립적인 타임아웃을 가집니다. 하나를 설정해도 다른 하나는 영향을 주지 않습니다.

설정	경계를 정하는 대상	기본값
`timeout` `connect()`에 대한 인수	인증 시도, 네트워크 연결 포함. `SQL_ATTR_LOGIN_TIMEOUT`을 설정합니다.	`0`, 드라이버 기본값을 사용합니다
`Connection.timeout` 속성	연결이 실행되는 각 문장.	`0`, 쿼리 타임아웃을 비활성화합니다

# Bound the authentication attempt (in seconds)
conn = mssql_python.connect(connection_string, timeout=30)

# Bound each statement that this connection runs
conn.timeout = 60

SQL_ATTR_LOGIN_TIMEOUT에서 attrs_before를 설정하면 그 값이 timeout 인수보다 우선 적용됩니다.

메모

Microsoft Entra ID 토큰 획득은 드라이버가 연결되기 전에 이루어지므로, 인증 타임아웃이 토큰을 제한하지 않습니다.

만약 대상이 자동 일시정지가 활성화된 Azure SQL Database serverless라면, 최소한 60.을 사용하세요. 자동 일시 중지된 데이터베이스는 첫 번째 연결 시도 시 다시 시작되지만, 재개가 완료되기 전에 더 짧은 시간 제한이 만료됩니다. 데이터베이스가 재개되는 동안 40613 오류가 발생하면 시도가 실패할 수 있으므로 애플리케이션은 다시 시도해야 합니다. 자세한 내용은 자동 일시정지와 자동 재개를 참조하세요.

연결 특성

런타임에 연결 동작을 수정하는 데 사용됩니다 set_attr() . 연결 속성은 접근 모드, 트랜잭션 격리, 패킷 크기와 같은 저수준 드라이버 설정을 제어합니다. 대부분의 애플리케이션은 이 속성을 변경할 필요가 없지만, 특정 상황에서는 유용합니다:

읽기 전용 모드: 보고 쿼리에서 실수로 쓰는 것을 방지합니다.
트랜잭션 격리: 동시 트랜잭션이 어떻게 상호작용하는지( SERIALIZABLE 엄격한 일관성 사용 및 READ_COMMITTED 일반 사용 목적) 제어.
패킷 크기: 고지연 또는 고처리량 네트워크에 맞게 조정하세요.

import mssql_python

conn = mssql_python.connect(connection_string)

# Set read-only mode
conn.set_attr(mssql_python.SQL_ATTR_ACCESS_MODE, mssql_python.SQL_MODE_READ_ONLY)

# Set transaction isolation level
conn.set_attr(mssql_python.SQL_ATTR_TXN_ISOLATION, mssql_python.SQL_TXN_SERIALIZABLE)

사용 가능한 속성:

상수	설명
`SQL_ATTR_CONNECTION_TIMEOUT`	연결 시간 초과는 초 단위입니다.
`SQL_ATTR_LOGIN_TIMEOUT`	로그인 타임아웃이 몇 초 만에 끝납니다.
`SQL_ATTR_PACKET_SIZE`	네트워크 패킷 크기입니다.
`SQL_ATTR_ACCESS_MODE`	읽기 전용 또는 읽기-쓰기 모드입니다.
`SQL_ATTR_TXN_ISOLATION`	트랜잭션 격리 수준.
`SQL_ATTR_CURRENT_CATALOG`	현재 데이터베이스 이름입니다.

사전 연결 속성

드라이버가 연결을 설정하기 전에 일부 속성(예: 로그인 타임아웃)을 설정해야 합니다. 다음을 attrs_before에 통과시키세요:

conn = mssql_python.connect(
    connection_string,
    attrs_before={
        mssql_python.SQL_ATTR_LOGIN_TIMEOUT: 30,
        mssql_python.SQL_ATTR_CONNECTION_TIMEOUT: 60,
    }
)

연결 정보 가져오기

로깅, 진단 또는 서버 기능에 따른 동작 조정을 위해 드라이버 및 서버 메타데이터를 가져오려면 getinfo()를 사용합니다:

conn = mssql_python.connect(connection_string)

# Server information
print(f"Server name: {conn.getinfo(mssql_python.SQL_SERVER_NAME)}")
print(f"Database name: {conn.getinfo(mssql_python.SQL_DATABASE_NAME)}")

# Driver information
print(f"Driver name: {conn.getinfo(mssql_python.SQL_DRIVER_NAME)}")
print(f"Driver version: {conn.getinfo(mssql_python.SQL_DRIVER_VER)}")

이용 가능한 정보 상수 목록을 확인하세요:

constants = mssql_python.get_info_constants()
for name, value in constants.items():
    print(f"{name}: {value}")

검색 이스케이프 문자

속성은 searchescape 패턴에서 % 와일드카드(_와 LIKE)를 피하는 데 사용된 캐릭터를 반환합니다. 사용자 입력에서 문자 그대로 와일드카드 문자를 안전하게 검색할 수 있습니다:

escape = conn.searchescape

# Use in queries with wildcard characters
cursor.execute(
    f"SELECT Name FROM Production.Product WHERE Name LIKE '%{escape}%%' ESCAPE '{escape}'"
)
# Matches names containing literal '%' character

인코딩 및 디코딩

SQL 문과 결과에 대해 텍스트 인코딩을 구성하세요. 기본 설정은 대부분의 애플리케이션에서 작동합니다. 열에 char/varchar 대해 UTF-8이 아닌 인코딩을 사용하는 서버에 연결했을 때만 변경하세요. 서버가 사용하는 인코딩은 열 정렬에 따라 달라집니다:

# Set encoding for outbound text
conn.setencoding(encoding='utf-8')

# Get current encoding settings
settings = conn.getencoding()
print(settings)  # {'encoding': 'utf-8', 'ctype': ...}

# Set decoding for inbound text from specific SQL types
conn.setdecoding(mssql_python.SQL_CHAR, encoding='utf-8')

# Get current decoding settings
settings = conn.getdecoding(mssql_python.SQL_CHAR)
print(settings)

기본 인코딩:

Direction	SQL 형식	기본 인코딩
아웃바운드 (스트리트)	SQL_WCHAR	`utf-16le`
Inbound	SQL_CHAR	`utf-8`
Inbound	SQL_WCHAR	`utf-16le`
Inbound	SQL_WMETADATA	`utf-16le`

모범 사례

애플리케이션 코드 내 모든 연결에 대해 컨텍스트 관리자(with블록)를 사용하세요. 예외가 발생하더라도 청소를 보장합니다.
더 나은 성능을 위해 연결 풀링(기본 활성화)을 사용하세요. 연결 풀링을 참조하세요.
네트워크 환경에 맞는 적절한 타임아웃을 설정하세요. 30초 타임아웃은 대부분의 클라우드 배포에 적합하며; 크로스 리전 또는 VPN 연결을 위해 그 수를 늘리세요. 자동 일시 중지가 활성화된 60에는 최소 를 사용하세요. 자동으로 일시 중지된 데이터베이스는 처음 연결을 시도할 때 다시 시작되기 때문입니다.
대상이 Azure SQL Database, Azure SQL Managed Instance, Microsoft Fabric의 SQL 데이터베이스, 가용성 그룹 리스너, 또는 failover 클러스터 인스턴스일 때 연결 문자열에 설정 MultiSubnetFailover=yes 하세요. 단일 IP 대상에서는 안전하므로, 모든 Microsoft SQL 계열 TCP 엔드포인트에는 그대로 두세요.
사용 autocommit=False (기본값) 트랜잭션 원자성이 필요한 데이터 수정 시나리오에 적합합니다.
autocommit=True 은 DDL 작업, 읽기 전용 쿼리 및 관리자 스크립트에 사용하세요.
스레드 간 연결을 공유하지 마세요. 드라이버의 스레드 안전 레벨은 1입니다(스레드는 모듈을 공유할 수 있지만 연결은 불가능합니다).

피드백

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

Last updated on 2026-09-04