Python 및 mssql-python 드라이버를 사용하여 Azure SQL Database에 연결 및 쿼리

적용 대상:Azure SQL 데이터베이스

이 빠른 시작에서는 애플리케이션을 Azure SQL Database의 데이터베이스에 연결하고 Python 및 mssql-python 드라이버를 사용하여 쿼리를 수행하는 방법을 설명합니다. mssql-python 드라이버는 Microsoft Entra 인증을 기본적으로 지원하므로 암호 없는 연결이 간단합니다. 암호 없는 허브의 암호 없는 연결에 대해 자세히 알아 보세요.

필수 구성 요소

• Azure 구독.
• Microsoft Entra 인증으로 구성된 Azure SQL 데이터베이스. 빠른 시작을 사용하여 만들 수 있습니다. 단일 데이터베이스 만들기 - Azure SQL Database. 또는 Microsoft Fabric에서 SQL 데이터베이스를 사용할 수 있습니다.
• Python 익스텐션이 있는 Visual Studio Code
• Python 3.10 이상
• 암호 없는 인증을 위한 Azure CLI (Windows, macOS 및 Linux에서 작동).

데이터베이스 구성

Azure SQL 데이터베이스에 대한 암호 없는 보안 연결에는 특정 데이터베이스 구성이 필요합니다. 로컬 및 호스팅된 환경 모두에서 Azure SQL 데이터베이스에 제대로 연결하려면 Azure의 논리 서버에서 다음 설정을 확인합니다.

1. 로컬 개발 연결의 경우 논리 서버가 로컬 컴퓨터 IP 주소 및 기타 Azure 서비스에 연결할 수 있도록 구성되어 있는지 확인합니다.

   • 서버의 네트워킹 페이지로 이동합니다.

   • 선택한 네트워크 라디오 버튼을 눌러 추가 구성 옵션을 표시합니다.

   • 클라이언트 IPv4 주소 추가(xx.xx.xx.xx.xx)를 선택하여 로컬 컴퓨터 IPv4 주소에서 연결을 활성화하는 방화벽 규칙을 추가합니다. 또는 + 방화벽 규칙 추가를 선택하여 원하는 특정 IP 주소를 입력할 수도 있습니다.

   • Azure 서비스 및 리소스의 서버 액세스 허용 확인란을 선택합니다.

     

     경고

     프로덕션 시나리오에는 Azure 서비스 및 리소스의 서버 액세스 허용을 보안상 권장하지 않습니다. 실제 애플리케이션에는 더 강력한 방화벽 제한 또는 가상 네트워크 구성과 같은 보다 강력한 보안 접근 방식을 적용해야 합니다.

     다음 리소스에서 데이터베이스 보안 구성에 대해 자세히 알아 보세요.

     • Azure SQL 데이터베이스 방화벽 규칙 구성
     • 프라이빗 엔드포인트를 사용하는 가상 네트워크 구성

2. 또한 서버에는 Microsoft Entra 인증이 활성화 되어 있어야 하며 Microsoft Entra 관리자 계정이 할당되어 있어야 합니다. 로컬 개발 연결의 경우, Microsoft Entra 관리자 계정은 로컬로 Visual Studio 또는 Azure CLI에 로그인할 수도 있는 계정이어야 합니다. 서버의 Microsoft Entra 인증이 활성화 여부는 논리 서버의 Microsoft Entra ID 페이지에서 확인할 수 있습니다.

   

3. 개인 Azure 계정을 사용하는 경우, 계정을 서버 관리자로 할당하기 위해 Azure SQL 데이터베이스에 Microsoft Entra를 설정 및 구성했는지 확인해야 합니다. 회사 계정을 사용하는 경우, Microsoft Entra ID가 이미 구성되어 있을 수 있습니다.

프로젝트를 만듭니다.

Visual Studio를 사용하여 새 Python 프로젝트를 만듭니다.

1. Visual Studio Code를 열고 프로젝트에 대한 새 폴더를 만들고 해당 디렉터리로 변경합니다.

   mkdir python-sql-azure
   cd python-sql-azure
   

2. 앱을 만들 가상 환경을 만듭니다.

   Windows

   py -m venv .venv
   .venv\scripts\activate
   

   macOS/Linux

   python3 -m venv .venv
   source .venv/bin/activate
   

3. 새 Python 파일app.py(을)를 만드십시오.

mssql-python 드라이버 설치

Python을 사용하여 Azure SQL 데이터베이스에 연결하려면 mssql-python 드라이버를 설치합니다. 이 드라이버는 Microsoft Entra 인증을 기본적으로 지원하므로 수동 토큰 처리가 필요하지 않습니다. 이 빠른 시작에서는 API를 만들고 실행하는 fastapi, uvicorn, pydantic 패키지를 설치합니다.

비고

macOS 및 Linux에서는 설치 mssql-python하기 전에 시스템 종속성이 필요합니다. 플랫폼별 지침 은 mssql-python 패키지 설치 를 참조하세요.

1. 다음을 사용하여 requirements.txt 파일을 만듭니다.

   mssql-python
   fastapi
   uvicorn[standard]
   pydantic
   python-dotenv
   

2. 요구 사항을 설치합니다.

   pip install -r requirements.txt
   

로컬 연결 문자열 구성

로컬 개발의 경우 연결 문자열을 .env 저장할 파일을 프로젝트 폴더에 만듭니다. 이렇게 하면 자격 증명이 코드 및 소스 제어에서 벗어나지 않습니다.

1. 프로젝트 폴더에서 새 파일을 만듭니다 .env.

2. 연결 문자열을 사용하여 AZURE_SQL_CONNECTIONSTRING 변수를 추가합니다. <database-server-name> 및 <database-name> 자리 표시자를 고유한 값으로 바꿉니다.

mssql-python 드라이버는 Microsoft Entra 인증을 기본적으로 지원합니다. 매개 변수를 Authentication 사용하여 인증 방법을 지정합니다.

ActiveDirectoryDefault (권장)

ActiveDirectoryDefault 는 대화형 로그인 없이 여러 원본에서 자격 증명을 자동으로 검색합니다. 로컬 개발에 권장되는 옵션입니다.

가장 안정적인 로컬 개발 환경을 위해 먼저 Azure CLI로 로그인합니다.

az login

그런 다음, 파일에서 다음 연결 문자열 형식을 사용합니다..env

AZURE_SQL_CONNECTIONSTRING=Server=<database-server-name>.database.windows.net;Database=<database-name>;Authentication=ActiveDirectoryDefault;Encrypt=yes;TrustServerCertificate=no;

ActiveDirectoryDefault 는 다음 순서로 자격 증명을 평가합니다.

1. 환경 변수 (서비스 주체 자격 증명의 경우)
2. 관리 ID (Azure에서 실행되는 경우)
3. Azure CLI (from az login)
4. Visual Studio (Windows에만 해당)
5. Azure PowerShell (from Connect-AzAccount)

팁 (조언)

프로덕션 애플리케이션의 경우 시나리오에 특정 인증 방법을 사용하여 자격 증명 검색 대기 시간을 방지합니다.

• Azure App Service/Functions: ActiveDirectoryMSI (관리되는 ID) 사용
• 대화형 사용자 로그인: 사용 ActiveDirectoryInteractive
• 서비스 주체: 사용하세요 ActiveDirectoryServicePrincipal

대화형 인증

Windows에서 Microsoft Entra Interactive Authentication은 Microsoft Entra 다단계 인증 기술을 사용하여 연결을 설정할 수 있습니다. 이 모드에서는 Azure 인증 대화 상자가 나타나고 자격 증명을 입력하여 연결을 완료할 수 있습니다.

AZURE_SQL_CONNECTIONSTRING=Server=<database-server-name>.database.windows.net;Database=<database-name>;Authentication=ActiveDirectoryInteractive;Encrypt=yes;TrustServerCertificate=no;

SQL 인증

사용자 이름 및 암호를 사용하여 SQL Server 인스턴스에 직접 인증할 수 있습니다.

AZURE_SQL_CONNECTIONSTRING=Server=<database-server-name>.database.windows.net;Database=<database-name>;UID=<user-name>;PWD=<user-password>;Encrypt=yes;TrustServerCertificate=no;

경고

사용자 이름, 암호 또는 액세스 키와 같은 기밀정보를 포함하는 연결 문자열을 관리할 때는 주의해야 합니다. 이러한 기밀정보는 소스 제어에 커밋하거나 의도하지 않은 사용자가 액세스할 수 있는 안전하지 않은 위치에 두어서는 안 됩니다. .env 파일에 .gitignore를 추가하여 실수로 비밀을 커밋하는 것을 방지합니다.

Fabric SQL Database

Microsoft Fabric의 SQL 데이터베이스에 연결하려면 동일한 인증 방법을 사용합니다. 서버 이름은 패브릭 형식을 따릅니다.

Windows 도메인에 가입된 컴퓨터에서 추가 단계 없이 원활한 인증에 사용합니다ActiveDirectoryIntegrated.

AZURE_SQL_CONNECTIONSTRING=Server=<workspace-guid>.database.fabric.microsoft.com,1433;Database=<database-name>;Encrypt=yes;TrustServerCertificate=no;Authentication=ActiveDirectoryIntegrated;

macOS, Linux 또는 비 도메인 Windows에서 Azure CLI(ActiveDirectoryDefault)로 로그인한 후 사용합니다az login.

AZURE_SQL_CONNECTIONSTRING=Server=<workspace-guid>.database.fabric.microsoft.com,1433;Database=<database-name>;Encrypt=yes;TrustServerCertificate=no;Authentication=ActiveDirectoryDefault;

패브릭 포털의 데이터베이스 설정 아래에서 Fabric SQL 데이터베이스 연결 문자열을 찾을 수 있습니다.

Azure 포털에서 연결 문자열을 만드는데 필요한 세부 정보는 다음 단계를 통해 확인할 수 있습니다.

1. Azure SQL Server로 이동하여 SQL 데이터베이스 페이지를 선택하여 데이터베이스 이름을 찾은 다음 데이터베이스를 선택합니다.

2. 데이터베이스에서 개요 페이지로 이동하여 서버 이름을 가져옵니다.

Azure SQL 데이터베이스에 코드 추가하여 연결하기

프로젝트 폴더에서 app.py 파일을 만들고 샘플 코드를 추가합니다. 이 코드는 다음과 같은 API를 만듭니다.

• .env를 사용하여 python-dotenv 파일에서 구성을 로드합니다.
• 환경 변수에서 Azure SQL 데이터베이스 연결 문자열 검색합니다.
• 시작하는 동안 데이터베이스에 Persons 테이블을 만듭니다(테스트 시나리오에만 해당).
• 데이터베이스에서 모든 Person 레코드를 검색하는 함수를 정의합니다.
• 데이터베이스에서 하나의 Person 레코드를 검색하는 함수를 정의합니다.
• 데이터베이스에 새 Person 레코드를 추가하는 함수를 정의합니다.

from os import getenv
from typing import Union
from dotenv import load_dotenv
from fastapi import FastAPI
from pydantic import BaseModel
from mssql_python import connect

load_dotenv()

class Person(BaseModel):
    first_name: str
    last_name: Union[str, None] = None

connection_string = getenv("AZURE_SQL_CONNECTIONSTRING")

app = FastAPI()

@app.get("/")
def root():
    print("Root of Person API")
    try:
        conn = get_conn()
        cursor = conn.cursor()

        # Table should be created ahead of time in production app.
        cursor.execute("""
            IF NOT EXISTS (SELECT * FROM sys.tables WHERE name = 'Persons')
            CREATE TABLE Persons (
                ID int NOT NULL PRIMARY KEY IDENTITY,
                FirstName varchar(255),
                LastName varchar(255)
            );
        """)

        conn.commit()
        conn.close()
    except Exception as e:
        # Table might already exist
        print(e)
    return "Person API"

@app.get("/all")
def get_persons():
    rows = []
    with get_conn() as conn:
        cursor = conn.cursor()
        cursor.execute("SELECT * FROM Persons")

        for row in cursor.fetchall():
            print(row.FirstName, row.LastName)
            rows.append(f"{row.ID}, {row.FirstName}, {row.LastName}")
    return rows

@app.get("/person/{person_id}")
def get_person(person_id: int):
    with get_conn() as conn:
        cursor = conn.cursor()
        cursor.execute("SELECT * FROM Persons WHERE ID = ?", (person_id,))

        row = cursor.fetchone()
        return f"{row.ID}, {row.FirstName}, {row.LastName}"

@app.post("/person")
def create_person(item: Person):
    with get_conn() as conn:
        cursor = conn.cursor()
        cursor.execute("INSERT INTO Persons (FirstName, LastName) VALUES (?, ?)",
                       (item.first_name, item.last_name))
        conn.commit()

    return item

def get_conn():
    """Connect using mssql-python with built-in Microsoft Entra authentication."""
    conn = connect(connection_string)
    conn.setautocommit(True)
    return conn

경고

샘플 코드는 프로덕션 코드에서 사용하면 안 되는 원시 SQL 문을 보여 줍니다. 이러한 SQL 문 대신 보다 안전한 개체 계층을 생성하는 SqlAlchemy와 같은 ORM(개체 관계형 매퍼) 패키지를 사용하여 데이터베이스에 액세스하세요.

로컬 앱 실행 및 테스트

이제 앱을 로컬로 테스트할 준비가 완료되었습니다.

1. Visual Studio Code에서 app.py 파일을 엽니다.

   uvicorn app:app --reload
   

2. http://127.0.0.1:8000/docs 앱의 Swagger UI 페이지에서 POST 메서드를 확장하고 시도를 선택합니다.

   API에 대해 생성된 설명서의 다른 형태를 볼 수도 /redoc 있습니다.

3. 샘플 JSON에 이름과 성 값을 추가하도록 수정합니다. 실행을 선택하여 데이터베이스에 새 기록을 추가합니다. API는 성공적인 응답을 반환합니다.

4. GET Swagger UI 페이지에서 메서드를 확장하고 [시도]를 선택합니다. 실행을 선택하면 방금 만든 사람이 반환됩니다.

Azure App Service에 배포

Azure에 앱을 배포할 준비가 완료되었습니다.

1. Azure App Service의 gunicorn이 uvicorn을 실행할 수 있도록 start.sh 파일을 만듭니다. start.sh는 한 줄입니다.

   gunicorn -w 4 -k uvicorn.workers.UvicornWorker app:app
   

2. az webapp up을 사용하여 App Service에 코드를 배포합니다. (-dryrun 옵션을 사용하면 리소스를 만들지 않고 명령이 수행하는 작업을 확인할 수 있습니다.)

   az webapp up \
       --resource-group <resource-group-name> \
       --name <web-app-name>         
   

3. az webapp config set 명령을 사용하여 start.sh 파일을 사용하도록 App Service를 구성합니다.

   az webapp config set \
       --resource-group <resource-group-name> \
       --name <web-app-name> \
       --startup-file start.sh
   

4. az webapp identity assign 명령을 사용하여 App Service의 시스템 할당 관리 ID를 사용하도록 설정합니다.

   az webapp identity assign \
       --resource-group <resource-group-name> \
       --name <web-app-name>
   

   이 빠른 시작에서는 시스템 할당 관리 ID가 데모용으로 사용됩니다. 사용자 할당 관리 ID는 광범위한 시나리오에서 더 효율적입니다. 관리 ID 모범 사례 권장 사항에서 더 자세히 알아 보세요. mssql-python에서 사용자 할당 관리 ID를 사용하는 예제는 Azure SQL Database와 암호 없는 연결을 사용하도록 Python 애플리케이션 마이그레이션을 참조하세요.

Azure SQL Server Database에 App Service 연결

데이터베이스 구성 섹션에서 Azure SQL 데이터베이스 서버의 네트워킹 및 Microsoft Entra 인증을 구성했습니다. 이 섹션에서는 데이터베이스 구성을 완료하고 연결 문자열을 사용하여 App Service를 구성하여 데이터베이스 서버에 액세스합니다.

이러한 명령을 실행하려면 SSMS(SQL Server Management Studio) 및 MSSQL 확장을 사용하는 Visual Studio Code를 포함하여 Azure SQL Database에 연결할 수 있는 모든 도구 또는 IDE를 사용할 수 있습니다. 빠른 시작에서 설명한 대로 Azure Portal을 사용할 수도 있습니다 . Azure Portal 쿼리 편집기를 사용하여 Azure SQL Database를 쿼리합니다.

1. SQL 명령을 사용하여 Azure SQL 데이터베이스에 사용자를 추가하여 암호 없는 액세스에 대한 사용자 및 역할을 만듭니다.

   CREATE USER [<web-app-name>] FROM EXTERNAL PROVIDER
   ALTER ROLE db_datareader ADD MEMBER [<web-app-name>]
   ALTER ROLE db_datawriter ADD MEMBER [<web-app-name>]
   

   자세한 내용은 포함된 데이터베이스 사용자 - 데이터베이스를 이식 가능하게 만들기를 참조하세요. 동일한 원칙에 대한 Azure VM 적용 예시는 자습서: Windows VM 시스템 할당 관리 ID를 사용하여 Azure SQL에 액세스하는 방법을 참조하세요. 할당된 역할에 대한 자세한 내용은 고정 데이터베이스 역할을 참조하세요.

   App Service 시스템 할당 관리 ID를 비활성화했다가 다시 활성화한 경우, 사용자를 삭제하고 다시 만듭니다. DROP USER [<web-app-name>](을)를 명령을 실행하고 CREATE 및 ALTER 명령을 다시 실행합니다. 사용자를 보려면 SELECT * FROM sys.database_principals(을)를 사용합니다.

2. az webapp config appsettings set 명령을 사용하여 연결 문자열에 대한 앱 설정을 추가합니다.

   az webapp config appsettings set \
       --resource-group <resource-group-name> \
       --name <web-app-name> \
       --settings AZURE_SQL_CONNECTIONSTRING="<connection-string>"
   

   배포된 앱의 경우 연결 문자열은 다음과 유사해야 합니다.

   Server=<database-server-name>.database.windows.net;Database=<database-name>;Authentication=ActiveDirectoryMSI;Encrypt=yes;TrustServerCertificate=no;
   

   <database-server-name> 및 <database-name>에 값을 입력합니다.

   암호 없는 연결 문자열은 사용자 이름 또는 암호를 포함하지 않습니다. 대신 앱이 Azure에서 실행되면 mssql-python 드라이버는 인증 모드를 사용하여 ActiveDirectoryMSI App Service의 관리 ID를 사용하여 자동으로 인증합니다.

배포된 애플리케이션 테스트

앱 URL로 이동하여 Azure SQL 데이터베이스 연결이 작동하는지 테스트합니다. 앱 URL는 App Service 개요 페이지에서 찾을 수 있습니다.

https://<web-app-name>.azurewebsites.net

URL에 /docs를 추가하여 Swagger UI를 보고 API 메서드를 테스트하세요.

축하합니다! 이제 애플리케이션이 로컬 및 호스팅된 환경 모두에서 Azure SQL 데이터베이스에 연결되었습니다.

관련 콘텐츠

• mssql-python 드라이버 설명서
• Azure SQL Database에서 암호 없는 연결을 사용하도록 Python 애플리케이션 마이그레이션
• Azure 서비스에 대한 암호 없는 연결
• 관리 ID 모범 사례 권장 사항