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

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=YourStr0ngP@ssword" \
  -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

SQL Server bağlanan bir Django uygulaması için en düşük 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-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 && \
    apt-get autoremove -y && \
    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"]

requirements.txtnız:

django>=5.2
mssql-django>=1.5
gunicorn>=22.0

Derleme ve çalıştırma:

docker build -t mydjango .
docker run -e DB_HOST=host.docker.internal -e DB_NAME=mydb \
  -e DB_USER=<your-username> -e DB_PASSWORD=<your-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 ODBC sürücüsünü ve Python bağımlılıkları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.

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

#!/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: "YourStr0ngP@ssword"
    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 ile yerel geliştirme için, OPTIONS["extra_params"] içinde Authentication=ActiveDirectoryDefault kullanın (1.7.3 ve sonraki sürümlerde mssql-django ile birlikte, ayrıca uyumlu bir Microsoft ODBC Sürücüsü gerekir) veya DefaultAzureCredential ile 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": "myserver.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 ManagedIdentityCredential ile TOKEN 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": "myserver.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: YourStr0ngP@ssword
        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.x"

      - name: Install ODBC Driver
        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: <username>
          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: YourStr0ngP@ssword
      ports:
        - 1433:1433

pool:
  vmImage: ubuntu-latest

services:
  sqlserver: sqlserver

steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: "3.x"

  - 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: <username>
      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 (.gitignore dosyasına .env ekleyin):

DB_HOST=localhost
DB_NAME=mydb
DB_USER=<username>
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 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",
        },
    },
}

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' KAPSAYıCıda ODBC sürücüsü yüklü değil. msodbcsql18 öğesini Dockerfile dosyanıza veya post-create betiğinize yükleyin.
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 '<username>' Kimlik bilgileri yanlış veya parola karmaşıklık gereksinimlerini karşılamıyor. 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.
Cannot open database Veritabanı henüz yok. 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

  • Last updated on