mssql-django ile kapsayıcı ve yerel geliştirme

Bu kılavuz Windows, Linux, macOS, Docker kapsayıcıları, devcontainers ve CI işlem hatlarında arka uçla mssql-django çalışan Django geliştiricileri için ortam kurulumunu kapsar.

Prerequisites

• Python 3.10'dan 3.14'e kadar. Django 6.0 ve 6.1 için Python 3.12 ve daha sonraki sürümler gereklidir.
• Docker Desktop (kapsayıcı tabanlı geliştirme için)
• Varsayılan pyodbc yolunu kullandığınızda SQL Server için Microsoft ODBC Driver 17 veya 18. bkz. SQL Server için ODBC Sürücüsünü İndirme.
• Gerekli mssql-python paketle uyumlu bir temel görüntü: Windows x64, Windows ARM64 Python 3.11 ve daha sonraki sürümlerle, macOS 15 ve daha sonraki sürümlerle veya Linux x64/ARM64 glibc 2.28 ve daha sonraki sürümlerle veya musl 1.2 ve daha sonraki sürümlerle. ARM64 üzerinde SUSE Linux desteklenmiyor.

mssql-python yolu, SQL Server kurulumu için ayrı bir Microsoft ODBC sürücüsü gerektirmez. Yine de unixODBC çalışma zamanına ihtiyaç duyar, çünkü Django arka ucu yüklediğinde arka uç pyodbc’yi içe aktarır. Daha fazla bilgi için, mssql-django için veritabanı sürücüsünü seç sayfasına bakınız.

sqlcmd ile yerel SQL Server (önerilir)

sqlcmd (Go) yardımcı programı tek bir komutta SQL Server kapsayıcısı oluşturabilir. Docker görüntüsü çekme, parola oluşturma, bağlantı noktası ataması ve bağlantı bağlamını otomatik olarak işler:

sqlcmd create mssql --accept-eula

Önceden bağlanmış örnek bir veritabanına sahip bir kapsayıcı oluşturmak için:

sqlcmd create mssql --accept-eula --using https://aka.ms/AdventureWorksLT.bak

Oluşturma işleminden sonra bağlantı sqlcmd bağlamını depolar, böylece hemen sorgulayabilirsiniz:

sqlcmd query "SELECT @@VERSION"

Oluşturma sırasında yazdırılan bağlantı ayrıntılarını sqlcmd kullanarak Django'yu bağlanacak şekilde yapılandırın. sqlcmd config view öğesini bunları daha sonra geri almak için kullanın:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "master",
        "USER": "sa",
        "PASSWORD": "<password from sqlcmd output>",
        "HOST": "localhost",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "TrustServerCertificate=yes",
        },
    },
}

İşiniz bittiğinde kapsayıcıyı durdurun veya silin:

sqlcmd stop
sqlcmd delete

Tip

Geliştirmeye hazır, boş bir kullanıcı veritabanına sahip bir konteyner oluşturmak için sqlcmd create mssql --user-database mydb komutunu çalıştırın.

Visual Studio Code'da Yerel SQL Server

Visual Studio Code için MSSQL uzantısı doğrudan düzenleyiciden yerel SQL Server kapsayıcıları oluşturabilir:

1. Etkinlik Çubuğu'nda SQL Server görünümünü açın.
2. Bağlantı> EkleYerel SQL Server Oluştur'u seçin (veya Komut Paleti: MS SQL: Yerel SQL Server Oluştur'u kullanın).
3. SQL Server sürümünü seçin ve EULA'yı kabul edin.
4. Uzantı kapsayıcı görüntüsünü çeker, bir parola oluşturur ve otomatik olarak bir bağlantı profili ekler.

Kapsayıcı çalıştırıldıktan sonra, Django koduna geçmeden önce Visual Studio Code veritabanlarına göz atabilir, sorgu çalıştırabilir ve nesneleri yönetebilirsiniz.

Docker ile yerel SQL Server

Kapsayıcıları doğrudan yönetmeyi tercih ediyorsanız, resmi SQL Server kapsayıcı görüntüsü iki ortam değişkeniyle çalışır:

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<strong_password>" \
  -p 1433:1433 --name sql1 \
  -d mcr.microsoft.com/mssql/server:2022-latest

Important

SQL Server kapsayıcılar için kullanınMSSQL_SA_PASSWORD. Eski SA_PASSWORD değişken kullanım dışıdır. Parolanın SQL Server karmaşıklık gereksinimlerini karşılaması gerekir: büyük harf, küçük harf, rakam ve özel karakter içeren en az 8 karakter.

Kapsayıcının başlaması için birkaç saniye bekleyin, ardından migrasyonları çalıştırın:

python manage.py migrate
python manage.py createsuperuser

Django uygulamaları için Dockerfile

Varsayılan pyodbc yolu üzerinden SQL Server'a bağlanan bir Django uygulaması için minimal bir Dockerfile oluşturun. ODBC sürücüsü, Python temel görüntüsüyle birlikte gelmeyen temel bağımlılıktır:

FROM python:3.12-slim

# Install ODBC Driver 18 for SQL Server
RUN apt-get update && \
    apt-get install -y --no-install-recommends curl gnupg2 && \
    curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | \
        gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg && \
    echo "deb [signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/debian/12/prod bookworm main" > \
        /etc/apt/sources.list.d/mssql-release.list && \
    apt-get update && \
    ACCEPT_EULA=Y apt-get install -y --no-install-recommends msodbcsql18 unixodbc-dev && \
    apt-get purge -y curl gnupg2 && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# Collect static files
RUN python manage.py collectstatic --noinput

EXPOSE 8000
CMD ["gunicorn", "myproject.wsgi:application", "--bind", "0.0.0.0:8000"]

Important

Temizlemeden sonra apt-get autoremove -y eklemeyin. ODBC sürücüsünün çalışma zamanında yüklediği ancak bağımlılık olarak belirtmediği libgssapi-krb5-2 kaldırılır. Yapı yine başarılı oluyor ve tüm bağlantılar başarısız oluyor. pyodbc hatası yanıltıcıdır: 18. sürüm yüklenemez, mssql-django 17. sürüme geri döner ve hata, arızalanan 18. sürüm yerine eksik 17. sürümü adlandırır.

requirements.txtnız:

django>=5.2,<6.2
mssql-django>=2.0
gunicorn>=22.0

Veritabanı takma adınız "python_driver": "mssql_python" ile mssql-python sürücü yolunu kullanıyorsa, yine de unixODBC gereklidir; çünkü Django arka ucu yüklediğinde arka uç pyodbc'yi içe aktarır. Microsoft paket deposuna veya msodbcsql18ya da 'ye ihtiyacınız yok, bu yüzden ODBC kurulum bloğu şu şekilde küçülüyor:

RUN apt-get update && \
    apt-get install -y --no-install-recommends unixodbc libkrb5-3 libgssapi-krb5-2 && \
    rm -rf /var/lib/apt/lists/*

Derleme ve çalıştırma:

docker build -t mydjango .
docker run -e "DB_HOST=host.docker.internal" -e "DB_NAME=<database>" \
  -e "DB_USER=<user_id>" -e "DB_PASSWORD=<password>" \
  -p 8000:8000 mydjango

Note

Ana makinedeki bir SQL Server’a ulaşmak için Docker Desktop’ta (Windows ve macOS) host.docker.internal kullanın. Linux'ta bunun yerine kullanın --network host .

Devcontainer kurulumu

SQL Server'ı yardımcı hizmet olarak içeren Visual Studio Code için bir .devcontainer/devcontainer.json oluşturun:

{
    "name": "Django + SQL Server",
    "image": "mcr.microsoft.com/devcontainers/python:3",
    "features": {
        "ghcr.io/devcontainers/features/docker-in-docker:2": {}
    },
    "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
    "postCreateCommand": "bash .devcontainer/post-create.sh",
    "forwardPorts": [1433, 8000],
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-mssql.mssql"
            ]
        }
    }
}

Bu devcontainer, varsayılan pyodbc yolu ve Python bağımlılıkları için ODBC sürücüsünü yükler ancak SQL Server örneği içermez. sqlcmd create mssql --accept-eula kullanarak devcontainer içinde bir örnek başlatın (çünkü Docker-in-Docker kullanılabilir) veya dahili bir SQL Server hizmeti için Docker Compose yaklaşımını kullanın. mssql-python yolunu kullanıyorsanız, post-create betiğindeki msodbcsql18 kurulumunu sudo apt-get install -y unixodbc libkrb5-3 libgssapi-krb5-2 ile değiştirin.

pyodbc ve Python bağımlılıkları için ODBC sürücüsünü yüklemek üzere .devcontainer/post-create.sh oluşturun:

#!/bin/bash
set -e

# Install ODBC Driver 18
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | \
    sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
echo "deb [signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/debian/12/prod bookworm main" | \
    sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev

pip install -r requirements.txt

Docker Compose ile SQL Server ekleme

SQL Server devcontainer'a hizmet olarak eklemek için Docker Compose'u kullanın:

.devcontainer/docker-compose.yml:

services:
  app:
    image: mcr.microsoft.com/devcontainers/python:3
    volumes:
      - ..:/workspace:cached
    command: sleep infinity
    depends_on:
      - db

  db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: "<strong_password>"
    ports:
      - "1433:1433"

.devcontainer/devcontainer.json (Oluşturma sürümü):

{
    "name": "Django + SQL Server",
    "dockerComposeFile": "docker-compose.yml",
    "service": "app",
    "workspaceFolder": "/workspace",
    "postCreateCommand": "bash .devcontainer/post-create.sh",
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-mssql.mssql"
            ]
        }
    }
}

Django'yu SQL Server hizmetine adını kullanarak bağlayın:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "mydb",
        "USER": "sa",
        "PASSWORD": "<password>",
        "HOST": "db",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "TrustServerCertificate=yes",
        },
    },
}

Geliştirme için kimlik doğrulaması

Uygulamanızın nerede çalıştığına ve veritabanının nerede barındırıldığına bağlı olarak bir kimlik doğrulama yaklaşımı seçin.

Azure SQL karşı yerel geliştirme

Azure SQL’e yönelik yerel geliştirmede, pyodbc yolunda OPTIONS["extra_params"] içindeki Authentication=ActiveDirectoryDefault öğesini veya DefaultAzureCredential ile birlikte TOKEN ayarını kullanın. DefaultAzureCredential az login oturumunuzu otomatik olarak algılar:

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://database.windows.net/.default").token

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "mydb",
        "HOST": "<server>.database.windows.net",
        "PORT": "1433",
        "TOKEN": token,
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

Tam kimlik doğrulama matrisi ve uyarılar için bkz. mssql-django ile kimlik doğrulaması Microsoft Entra.

Azure SQL’e yönelik kapsayıcı geliştirme

Azure’da çalışan kapsayıcılar için, bir Microsoft Entra erişim belirtecini açıkça almak üzere TOKEN ile ManagedIdentityCredential ayarını kullanın:

from azure.identity import ManagedIdentityCredential

credential = ManagedIdentityCredential()
token = credential.get_token("https://database.windows.net/.default").token

DATABASES = {
  "default": {
    "ENGINE": "mssql",
    "NAME": "mydb",
    "HOST": "<server>.database.windows.net",
    "PORT": "1433",
    "TOKEN": token,
    "OPTIONS": {
      "driver": "ODBC Driver 18 for SQL Server",
    },
  },
}

Kimlik doğrulama yöntemlerinin tam listesi için bkz. mssql-django ile kimlik doğrulaması Microsoft Entra.

CI işlem hattı kurulumu

CI işlem hattınızdaki bir SQL Server hizmet kapsayıcısında Django test paketinizi çalıştırın.

GitHub Actions

name: Django Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      sqlserver:
        image: mcr.microsoft.com/mssql/server:2022-latest
        env:
          ACCEPT_EULA: Y
          MSSQL_SA_PASSWORD: "<strong_password>"
        ports:
          - 1433:1433
        options: >-
          --health-cmd "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P \"$$MSSQL_SA_PASSWORD\" -C -Q 'SELECT 1'"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install ODBC Driver for pyodbc
        run: |
          curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | \
              sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
          echo "deb [signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/ubuntu/$(lsb_release -rs)/prod $(lsb_release -cs) main" | \
              sudo tee /etc/apt/sources.list.d/mssql-release.list
          sudo apt-get update
          sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Run tests
        env:
          DB_HOST: localhost
          DB_NAME: "master"
          DB_USER: "<user_id>"
          DB_PASSWORD: "<password>"
        run: python manage.py test

Tip

Paylaşılan işlem hatları için satır içi yer tutucu parolasını şifrelenmiş bir gizli dizi (${{ secrets.SQL_PWD }}) ile değiştirin ve SQL Server hizmet görüntüsünü özete sabitleyin.

Azure Pipelines

trigger:
  - main

resources:
  containers:
    - container: sqlserver
      image: mcr.microsoft.com/mssql/server:2022-latest
      env:
        ACCEPT_EULA: Y
        MSSQL_SA_PASSWORD: "<strong_password>"
      ports:
        - 1433:1433

pool:
  vmImage: ubuntu-latest

services:
  sqlserver: sqlserver

steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: "3.12"

  - script: |
      curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | \
          sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
      echo "deb [signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/ubuntu/$(lsb_release -rs)/prod $(lsb_release -cs) main" | \
          sudo tee /etc/apt/sources.list.d/mssql-release.list
      sudo apt-get update
      sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev
      pip install -r requirements.txt
    displayName: Install dependencies

  - script: python manage.py test
    displayName: Run tests
    env:
      DB_HOST: "localhost"
      DB_NAME: "master"
      DB_USER: "<user_id>"
      DB_PASSWORD: "<password>"

Ortam tabanlı settings.py

Ortam değişkenlerinden veritabanı kimlik bilgilerini okuyacak şekilde yapılandırın settings.py . Bu tek yapılandırma yerel geliştirme, Docker ve CI genelinde çalışır:

import os

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": os.environ.get("DB_NAME", "mydb"),
        "USER": os.environ.get("DB_USER", ""),
        "PASSWORD": os.environ.get("DB_PASSWORD", ""),
        "HOST": os.environ.get("DB_HOST", "localhost"),
        "PORT": os.environ.get("DB_PORT", "1433"),
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": os.environ.get("DB_EXTRA_PARAMS", "TrustServerCertificate=yes"),
        },
    },
}

Kimlik bilgilerini yerel geliştirme için bir .env dosyasında depolayın (.env dosyasına .gitignore ekleyin):

DB_HOST=localhost
DB_NAME=mydb
DB_USER=<user_id>
DB_PASSWORD=<password>

veya django-environile python-dotenv ortam değişkenlerini yükleyin:

pip install django-environ

import environ

env = environ.Env()
environ.Env.read_env()  # Reads .env from the directory holding this settings file

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": env("DB_NAME"),
        "USER": env("DB_USER", default=""),
        "PASSWORD": env("DB_PASSWORD", default=""),
        "HOST": env("DB_HOST", default="localhost"),
        "PORT": env("DB_PORT", default="1433"),
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": env("DB_EXTRA_PARAMS", default="TrustServerCertificate=yes"),
        },
    },
}

Caution

.env dosyaları hiçbir zaman kaynak denetimine kaydetmeyin. Dosyanıza .env ekleyin.gitignore.

Yaygın konteyner sorunlarını giderin

Belirti	Cause	Düzelt
Can't open lib 'ODBC Driver 18 for SQL Server'	ODBC sürücüsü pyodbc yolu için konteynere yüklenmemiş veya apt-get autoremove kurulumdan sonra sökülmüştür libgssapi-krb5-2 .	Dockerfile veya post-create scriptinize kurun msodbcsql18 , sonra çalıştırmayın apt-get autoremove .
Can't open lib 'ODBC Driver 17 for SQL Server' 18 sürümünü kurduğunuzda	Sürüm 18 kayıtlı ama yüklenmiyor, bu yüzden mssql-django tekrar 17 sürümüne dönüyor ve o da yüklenmemiş. Genellikle nedeni, eksik bir libgssapi-krb5-2 öğesidir.	libgssapi-krb5-2'i yükleyin ve apt-get autoremove'yi temizledikten sonra curl'i çalıştırmayın.
Error loading pyodbc module: libodbc.so.2	Konteynerin unixODBC çalışma süresi yoktur. Backend, Django yüklediğinde pyodbc'yi mssql-python yolunda bile içe aktarıyor.	Kurulum unixodbc (veya unixodbc-dev).
DDBC Error: Failed to load the driver	mssql-python sürücüsü kendi bağımlılıklarını yükleyemiyor.	Yükleyin libkrb5-3 ve libgssapi-krb5-2.
Bağlantı 1433 numaralı bağlantı noktasında reddedildi	SQL Server kapsayıcı hazır değil.	Sistem durumu denetimi ekleyin veya hizmetin başlatılmasını bekleyin.
Login failed for user '<user_id>'	Kimlik bilgileri yanlış veya parola karmaşıklık gereksinimlerini karşılamıyor. mssql-python yolunda, var olmayan bir veritabanı aynı mesajı verir.	Kapsayıcınız için doğru SQL oturum açma bilgilerini kullanın ve parolanın karmaşıklık gereksinimlerini karşıladığından emin olun. Giriş doğruysa, NAME içindeki veritabanının mevcut olduğunu doğrulayın.
Cannot open database	Veritabanı henüz yok. pyodbc kod yolu bu durumu raporlar; mssql-python kod yolu ise bunun yerine Login failed raporlar.	komutunu çalıştırmadan migrateönce veritabanını oluşturun veya ilk kurulum için kullanın master .
Kapsayıcıda yavaş ilk bağlantı	DNS çözümlemesi veya kimlik bilgisi zinciri başlatma.	Yerel SQL Server için konak adı yerine kullanınlocalhost.
SSL Provider: [error:0A000086]	Otomatik olarak imzalanan sertifika ile TLS sertifika doğrulama hatası.	Yalnızca geliştirme amacıyla TrustServerCertificate=yes öğesini extra_params öğesine ekleyin.

İlgili içerik

• mssql-django yükleme
• mssql-django için bağlantı seçenekleri
• mssql-django ile Microsoft Entra kimlik doğrulaması
• Azure App Service SQL Server ile Django uygulaması dağıtma
• Django uygulamalarını SQL Server ile test edin