mssql-python용 연결 문자열

mssql-python 드라이버는 SQL Server, Azure SQL Database, Azure SQL Managed Instance, Microsoft Fabric 내 SQL 데이터베이스에 연결할 때 다음과 같은 연결 문자열 키워드를 지원합니다.

연결 문자열 구문

연결 문자열은 세미콜론으로 구분된 키-값 쌍을 사용합니다:

keyword1=value1;keyword2=value2;...

특수 문자(세미콜론, 등호, 또는 컬리 괄호)를 포함하는 랩 값:

PWD={my;complex=password}

값에 문자 그대로의 닫힘 괄호를 포함하려면, 두 개의 닫힘 괄호(}}):

PWD={password}}with}}brace}

기본 연결 예시

다음 예시들은 다양한 인증 방법을 사용하여 연결하는 방법을 보여줍니다. 운영 애플리케이션의 경우, 가능한 한 Microsoft Entra 인증을 사용하세요. 코드와 연결 문자열에서 비밀번호를 제거합니다.

이 예시는 여러 자격 증명 소스(Azure CLI, 환경 변수, 관리 식별 등)를 순서대로 시도하는 , 를 사용합니다ActiveDirectoryDefault. 비밀번호는 코드로 저장되지 않습니다:

import mssql_python

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

SQL 인증이 있는 SQL Server

로컬 개발에서는 자신이 제어하는 SQL Server 인스턴스에 대해서만 SQL 인증을 사용하세요. 자격 증명은 연결 문자열에 내장되어 있으므로, 소스 코드보다는 환경 변수나 .env 파일에 보관하세요:

conn = mssql_python.connect(
    "Server=<server>;"
    "Database=<database>;"
    "UID=<login>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

Azure SQL with Microsoft Entra authentication

Azure SQL Database의 연결 문자열은 SQL Server와 동일합니다. ActiveDirectoryDefault로컬 개발, 컨테이너, Azure 호스팅 환경 전반에서 코드 변경 없이 작동합니다:

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

키워드 인수 사용

연결 매개변수는 연결 문자열 대신 또는 추가로 키워드 인수로 전달할 수 있습니다. 키워드 인항은 연결 문자열 assembly의 함정을 피합니다. , , ;, {와 } 같은 @특수 문자를 가진 비밀번호는 키워드 인수로 전달될 때 컬리 괄호 라벨이 필요 없는 경우:

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

연결 문자열 assembly와 비교하면, 비밀번호는 다음을 랩 @ 해야 합니다:

# Connection string requires escaping
conn = mssql_python.connect("Server=srv;UID=user;PWD={p@ss;word};")

# Keyword arguments - no escaping needed
conn = mssql_python.connect(server="srv", uid="user", pwd="p@ss;word")

드라이버는 정규화 후 키워드 인수를 연결 문자열에 병합합니다. 키워드 인수가 이미 연결 문자열에 포함된 매개변수와 일치하면, 키워드 인자가 우선권을 가지며 연결 문자열 값을 덮어쓴다:

# The keyword argument database="production" overrides Database=dev in the connection string
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Encrypt=yes;",
    database="production",
    authentication="ActiveDirectoryDefault"
)
# Connects to "production", not "dev"

다음 예시는 키워드 인수와 연결된 연결 문자열을 결합합니다:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

연결 문자열 키워드

서버 및 데이터베이스

연결에 대해 대상 SQL Server 인스턴스와 데이터베이스를 지정하세요.

키워드 별칭 Default 묘사
Server addr, address None SQL Server 호스트명, IP 주소 또는 명명된 인스턴스. 명명된 인스턴스의 경우, server\instance. For Azure SQL, use server.database.windows.net. 포트 server,port를 지정하려면 .
Database None None 연결할 데이터베이스 이름입니다.

Authentication

SQL 인증을 위한 자격 증명을 제공하거나 Microsoft Entra 인증 모드를 지정하세요. 비밀번호 없는 옵션에 대해서는 Microsoft Entra 인증 모드를 참조하세요.

키워드 별칭 Default 묘사
UID uid None SQL 인증용 사용자 이름입니다.
PWD pwd None SQL 인증용 비밀번호.
Trusted_Connection trusted_connection no Windows 통합 인증을 사용하세요. 활성화하려면 yes로 설정하세요.
Authentication authentication None Microsoft Entra 인증 모드. Microsoft Entra 인증을 참조하세요.

암호화 및 보안

모든 연결은 기본적으로 사용됩니다 Encrypt=yes . 대부분의 애플리케이션에서는 기본값이 충분합니다. SQL Server 인스턴스가 TDS 8.0을 지원하고 TLS 1.3이 필요할 때만 사용 strict 하세요. 자체 서명 인증서가 있는 개발 환경에서만 사용 TrustServerCertificate=yes 하세요.

키워드 별칭 Default 묘사
Encrypt encrypt yes TLS 암호화를 사용하도록 설정합니다. 값: yes, no. strict TDS 8.0과 필수 TLS 1.3에 사용strict.
TrustServerCertificate trust_server_certificate, trustservercertificate no 검증 없이 자가 서명된 서버 인증서를 신뢰하세요. 개발용으로 yes 설정하세요.
HostnameInCertificate hostnameincertificate None 서버의 TLS 인증서에 예상되는 호스트네임.
ServerCertificate servercertificate None 신뢰받는 인증서 기관을 포함하는 PEM 파일로 가는 경로.
ServerSPN serverspn None Kerberos 인증의 서버 서비스 프린시펄 이름.

고가용성 및 장애 조치

이 키워드들은 Always On의 가용성 그룹 배포에 적용됩니다. 읽기 중심 워크로드(보고서, 분석)를 보조 복제본으로 라우팅하여 주 복제본의 부하를 줄이도록 설정 ApplicationIntent=ReadOnly 했습니다. 가용성 그룹이 여러 서브넷에 걸쳐 있을 때 설정 MultiSubnetFailover=yes 하세요.

키워드 별칭 Default 묘사
MultiSubnetFailover multisubnetfailover no Always On 가용성 그룹에 대해 다중 서브넷 장애 전환을 활성화하세요.
ApplicationIntent applicationintent ReadWrite 애플리케이션 워크로드 유형을 선언하세요. 보조 복제본으로 읽기 전용 라우팅에 사용됩니다 ReadOnly .
ConnectRetryCount connectretrycount 1 유휴 연결 복원력을 위한 자동 재연결 시도 횟수. 이는 유휴 연결이 끊긴 경우에 대한 드라이버 수준의 기능이지, 애플리케이션 수준의 재시도 논리를 대체하는 것이 아닙니다.
ConnectRetryInterval connectretryinterval 10 유휴 연결 복원력 재연결 시도 사이에 몇 초가 걸립니다.

성능 및 네트워크

기본 설정은 대부분의 애플리케이션에서 작동합니다. 대량 데이터 전송 시 최대 32767까지 증가 PacketSize . 연결이 방화벽을 넘나거나 유휴 TCP 세션을 버리는 로드 밸런서가 발생하면 설정하세요 KeepAlive .

키워드 별칭 Default 묘사
PacketSize packet size, packetsize 4096 네트워크 패킷 크기 (512–32767)
KeepAlive keepalive None TCP 킵-얼라이브 간격은 초 단위입니다.
KeepAliveInterval keepaliveinterval None TCP keep-alive 재시도 간격은 초 단위입니다.
IpAddressPreference ipaddresspreference None IP 주소 가족 선호도: IPv4First, , IPv6FirstUsePlatformDefault.

예약된 키워드

키워드 묘사
Driver 내부용으로 예약되어 있습니다. 운전자는 이 값을 자동으로 관리합니다.
APP 예약되었습니다. 항상 운전자가 '로 "MSSQL-Python" 설정하세요.

Microsoft Entra 인증 모드

키워드는 Authentication 다음과 같은 값들을 지원합니다. 배치에 맞는 모드를 선택하세요:

값 묘사 사용 시기
ActiveDirectoryDefault Azure Identity SDK에서 사용하는 용도DefaultAzureCredential. 여러 인증 방법을 연속적으로 시도합니다. Local Development across Azure CLI, Azure PowerShell, and Azure Developer CLI. 프로덕션에서는 느린 자격 증명 체인 워크를 피하기 위해 특정 모드(ActiveDirectoryMSI, ActiveDirectoryServicePrincipal)를 사용하세요.
ActiveDirectoryInteractive 브라우저 기반 인터랙티브 로그인. Windows에서는 ODBC 드라이버에 네이티브로 위임됩니다. 사용자가 브라우저에서 인증할 수 있는 로컬 개발 및 도구들.
ActiveDirectoryDeviceCode 헤드리스 환경을 위한 장치 코드 흐름. 입력 코드를 https://microsoft.com/devicelogin표시합니다. SSH 세션, Docker 컨테이너 또는 브라우저가 없는 기타 환경입니다.
ActiveDirectoryPassword Deprecated. Microsoft Entra ID로 사용자 이름과 비밀번호 인증. UID 및 PWD가 필요합니다. ROPC 플로우를 사용하는데, MFA와 호환되지 않습니다. 권장하지 않습니다. 대신 ActiveDirectoryMSI 또는 ActiveDirectoryServicePrincipal를 사용하십시오.
ActiveDirectoryMSI Azure-hosted applications for managed Service Identity. Azure VMS, App Service, or Azure Functions (managed identity conconfiguration). 자격 증명이 필요하지 않습니다.
ActiveDirectoryServicePrincipal 서비스 주된 인증. (클라이언트 ID)와 PWD (클라이언트 비밀)이 필요합니다 UID . 등록된 애플리케이션 아이덴티티를 사용하는 CI/CD 파이프라인 및 백그라운드 서비스.
ActiveDirectoryIntegrated Windows 통합 인증과 Microsoft Entra ID (Kerberos). Kerberos가 설정된 엔터프라이즈 환경에서 도메인에 조인 Windows 기기.

재현 가능한 도커, 개발 컨테이너, CI 환경 설정에 대해서는 컨테이너 및 로컬 개발을 참조하세요. 그 기사는 Python 런타임 선택을 중앙 집중화하고, 공유 환경에서 다이제스트 고정 이미지를 사용하는 방법을 보여줍니다.

예시: DefaultAzureCredential

ActiveDirectoryDefaultAzure Identity DefaultAzureCredential 체인에 매핑됩니다. 로컬 개발 중에 먼저 Azure CLI 토큰을 시도하고, Azure에 배포할 때 관리 신원을 시도합니다:

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

예시: 장치 코드 흐름

브라우저가 없는 환경(예: SSH 세션이나 도커 컨테이너)에서 실행 시 장치 코드 흐름을 사용하세요. 드라이버는 별도의 기기에서 입력할 URL과 코드를 표시합니다:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Follow the prompt to authenticate at https://microsoft.com/devicelogin

예시: 서비스 프린시펄

서비스 주체 인증은 클라이언트 ID와 비밀이 포함된 등록된 애플리케이션 신원을 사용합니다. 사용자 상호작용 없이 실행되는 CI/CD 파이프라인과 백그라운드 서비스에 이 방식을 사용하세요:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"
    "PWD=<client-secret>;"
    "Encrypt=yes;"
)

애플리케이션을 등록하고 데이터베이스 접근 권한을 부여하려면 Microsoft Entra service principals with Azure SQL을 참조하세요. 전체 설정 mssql-python은 서비스 주체 인증(Service principal authentication)을 참조하세요.

연결 시간 초과

연결 타임아웃을 매개변수로 timeout 설정하세요. 서버가 접근 불가능할 때 애플리케이션이 무기한 정지되는 것을 방지하기 위해 타임아웃을 사용하세요:

# 30-second connection timeout
conn = mssql_python.connect(connection_string, timeout=30)

기존 연결의 타임아웃도 변경할 수 있습니다:

conn.timeout = 60

자동 커밋 모드

기본적으로 autocommit 는 False이며, 명시적 commit() 호출이 필요합니다. 트랜잭션 제어가 필요 없는 DDL 문이나 읽기 전용 쿼리에 대해 자동 커밋을 활성화하세요:

# Via parameter
conn = mssql_python.connect(connection_string, autocommit=True)

# Or after connection
conn.setautocommit(True)

연결 특성

연결을 설정하기 전에 다음을 사용하여 attrs_beforeODBC 연결 속성을 설정합니다:

import mssql_python

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

프로그램적 연결 문자열 구축

연결 문자열 주입을 방지하기 위해 사용자 입력에 문자열 연결이나 f-string을 사용하지 마세요. 대신 키워드 인수나 환경 변수를 사용하세요. JSON/YAML 설정 파일, Azure Key Vault, 빌더 클래스 등 더 많은 구성 패턴은 프로그래밍 방식으로 연결 문자열을 구축하는 방법을 참조하세요.

import os

conn = mssql_python.connect(
    server=os.environ["DB_SERVER"],
    database=os.environ["DB_NAME"],
    authentication=os.environ.get("DB_AUTH", "ActiveDirectoryDefault"),
    encrypt="yes"
)

연결 문자열 검증

드라이버는 연결 문자열을 검증하고 알 수 없거나 철자가 틀린 키워드에 대해 레이즈 ConnectionStringParseError 합니다:

try:
    conn = mssql_python.connect("Servr=localhost;")  # Typo
except mssql_python.ConnectionStringParseError as e:
    print(f"Invalid connection string: {e}")
    # Output: Unknown keyword 'Servr'

관련 콘텐츠

  • Last updated on