mssql-django için bağlantı seçenekleri

Bu makale, Django OPTIONS yapılandırmanızda bulunan DATABASES sözlük ayarlarını açıklar. Bu ayarlar, mssql-django öğesinin ODBC sürücüsü aracılığıyla SQL Server’a nasıl bağlanacağını denetler.

ODBC sürücüsü seçimi

mssql-django 1.7 sürümünden itibaren, arka uç varsayılan olarak SQL Server için ODBC Driver 18 kullanır. ODBC Sürücüsü 18 yüklü değilse arka uç otomatik olarak ODBC Sürücüsü 17'ye geri döner.

Note

ODBC Sürücüsü 18 varsayılan olarak etkinleştirir Encrypt=yes ve sunucu sertifikasını doğrular. Sürücü 17 ile çalışan bağlantılar SSL/TLS güven hatasıyla başarısız olabilir. Hatayı çözmek için:

Şirket içi SQL Server için, istemcilerinizin zaten güvendiği bir sertifika yetkilisinden bir sunucu sertifikası yükleyin veya mevcut sunucu sertifikasını her istemci güven deposuna aktarın. Yönergeler için bkz.: Bağlantıları şifrelemek için SQL Server Veritabanı Altyapısı'nı yapılandırın.
IP adresiyle veya sertifikanın öznesi ya da özne alternatif adıyla (SAN) eşleşmeyen bir takma adla bağlanırsanız, HostNameInCertificate=<name-from-certificate> öğesini extra_params öğesine ekleyin.

Otomatik olarak imzalanan bir sertifikaya karşı yerel geliştirme için TrustServerCertificate bölümüne bakın.

Sürücüyü açıkça belirtebilirsiniz:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 17 for SQL Server",
        },
    },
}

Linux'ta, sürücü kitaplığının tam yolunu da belirtebilirsiniz:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.0.so.1.1",
        },
    },
}

DSN ve HOST karşılaştırması

HOST adı veya adlandırılmış bir DSN’yi (Veri Kaynağı Adı) kullanarak bağlanabilirsiniz.

HOST ile bağlanma

Yapılandırmaların çoğu ayarı doğrudan kullanır HOST :

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

DSN ile bağlanma

ODBC veri kaynaklarınızda yapılandırılmış adlandırılmış bir DSN kullanın:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "OPTIONS": {
            "dsn": "MyDataSourceName",
        },
    },
}

FreeTDS desteği

FreeTDS'yi ODBC sürücüsü olarak kullanmak için host_is_server değerini True olarak ayarlayın. Bu, arka ucun HOST içinde bir veri sunucusu adı aramak yerine doğrudan PORT ve freetds.conf kullanmasını söyler:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "FreeTDS",
            "host_is_server": True,
        },
    },
}

FreeTDS ile DSN içermeyen bağlantılar hakkında daha fazla bilgi için bkz. FreeTDS kullanıcı kılavuzu.

Ek ODBC parametreleri

Ek ODBC bağlantı dizesi parametrelerini geçirmek için extra_params kullanın. Değer, bağlantı dizesine eklenen noktalı virgülle ayrılmış bir dizedir:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "TrustServerCertificate=yes;ApplicationIntent=ReadOnly",
        },
    },
}

Bu ayar Microsoft Entra kimlik doğrulama anahtar sözcükleri için de kullanılır.

Azure SQL Veritabanı, Azure SQL Yönetilen Örneği, Microsoft Fabric'teki SQL veritabanı, bir kullanılabilirlik grubu dinleyicisi veya bir yük devretme kümesi örneğine bağlanırken, extra_params öğesine MultiSubnetFailover=Yes ekleyin. Sunucu adı birden fazla IP adresi olarak çözüldüğünde, sürücü aynı anda tüm bu adreslere bağlanır ve ilk yanıt veren adresi kullanır. Bu özellik olmadan, sürücü adresleri tek tek dener ve yanıt vermeyen bir adres, sürücü bir sonrakine geçmeden önce kimlik doğrulaması için kalan zaman aşımını tüketir. DNS tek bir adrese çözüm bulduğunda, sürücü tek bir bağlantı girişimi yapar, böylece ayar açık bırakmak güvenli olur.

MultiSubnetFailover=Yes aşağıdaki sınırlara sahiptir:

TCP dışında başka bir protokol üzerinden kullanamazsınız.
64'ten fazla IP adresiyle yapılandırılmış bir SQL Server örneğine bağlanmak başarısız olur.
Veritabanı aynalama ile kullanamazsınız. Sürücü, bağlantı dizesi Failover_Partner belirttiğinde ve ayrıca sunucu veritabanının yansıtıldığını bildirdiğinde bir hata döndürür. Veritabanı aynalama, desteklenen tüm SQL Server sürümlerinde kullanımdan kaldırılmıştır. Bunun yerine Always On kullanılabilirlik gruplarını kullanın.

Caution

TrustServerCertificate=yes yalnızca kendinden imzalı sertifikalarla yerel geliştirme için kullanın. Üretimde kullanmayın. Sertifika zinciri doğrulamasını devre dışı bırakır ve ortadaki saldırgan riski artırır. Sunucuya güvenilir bir sertifika yükleyin ve ile TrustServerCertificate=nobağlanın.

Bağlantı zaman aşımları ve yeniden denemeler

Zaman aşımı ve yeniden deneme ayarlarıyla bağlantı dayanıklılığını yapılandırın:

Option	Varsayılan	Description
`connection_timeout`	`0` (devre dışı)	Bir bağlantı için beklenecek en fazla saniye sayısı.
`connection_retries`	`5`	Bağlantı hatasıyla ilgili yeniden deneme denemelerinin sayısı.
`connection_retry_backoff_time`	`5`	Yeniden deneme girişimleri arasında beklenecek saniye sayısı.
`query_timeout`	`0` (devre dışı)	Sorgu tamamlanmasını beklemek için en fazla saniye.

Example:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "connection_timeout": 30,
            "connection_retries": 3,
            "connection_retry_backoff_time": 10,
            "query_timeout": 120,
        },
    },
}

connection_timeout=0 MSSQL-Django varsayılan durumudur. Çünkü pyodbc sadece pozitif bir değer sağladığınızda çağrı SQLSetConnectAttr(SQL_ATTR_LOGIN_TIMEOUT, ...) yapar, sürücüye bağlı varsayılan geçerlidir (Microsoft ODBC Driver for SQL Server için 15 saniye). Yanıt vermeyen bağlantı girişimlerinin tahmin edilebilir şekilde başarısız olması için açık bir değer belirleyin.

Hedef, otomatik duraklatma etkinleştirilmiş Azure SQL Veritabanı sunucusuz ise, en az 60 kullanın. Otomatik olarak duraklatılan bir veritabanı, ilk bağlantı denemesinde yeniden başlatılır ve veritabanı yeniden başlatılırken bu deneme 40613 hatasıyla başarısız olabilir. Daha kısa bir zaman aşımı süresiyle, ilk bağlantı girişimi yeniden sürdürme işlemi tamamlanmadan önce zaman aşımına uğrar. connection_retries sonunda bağlanmayı başarır, ancak ilk istek, bağlantı kurulmadan önce birkaç zaman aşımına uğrar. Daha fazla bilgi için bkz. Otomatik duraklatma ve otomatik devam.

Collation

Metin alanı aramaları için özel harmanlama ayarlayın:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "collation": "Chinese_PRC_CI_AS",
        },
    },
}

Birden çok veritabanı bağlantısı

Django aynı anda birden çok veritabanına bağlanmayı destekler. Bu, okuma amaçlı çoğaltmalar, veritabanları arası sorgular veya iş yüklerini yalıtım düzeyine göre ayırmak için kullanışlıdır.

Birden çok veritabanını yapılandırma

Her bağlantıyı şu ayarda DATABASES tanımlayın:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "app_db",
        "HOST": "<your-primary-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
    "readonly": {
        "ENGINE": "mssql",
        "NAME": "app_db",
        "HOST": "<your-readonly-replica>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Encrypt=yes;ApplicationIntent=ReadOnly",
        },
    },
    "analytics": {
        "ENGINE": "mssql",
        "NAME": "analytics_db",
        "HOST": "<your-analytics-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "isolation_level": "READ UNCOMMITTED",
        },
    },
}

Caution

READ UNCOMMITTED kirli okumalara izin verir. Bu yalıtım düzeyini yalnızca mutlak doğruluğun gerekli olmadığı raporlama veya analiz sorguları için kullanın. Daha fazla bilgi için bkz. İşlem yönetimi.

Sorguları veritabanı yönlendiricisi ile yönlendirme

Okuma ve yazma işlemlerini uygun bağlantıya yönlendirmek için bir veritabanı yönlendiricisi oluşturun:

class ReadReplicaRouter:
    """Route read queries to the readonly replica, writes to the primary."""

    def db_for_read(self, model, **hints):
        return "readonly"

    def db_for_write(self, model, **hints):
        return "default"

    def allow_relation(self, obj1, obj2, **hints):
        return True

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        return db == "default"

Yönlendiriciyi settings.py içine kaydedin:

DATABASE_ROUTERS = ["myproject.routers.ReadReplicaRouter"]

Yönlendirici sınıfını myproject/routers.py gibi bir dosyaya kaydedin.

Belirli bir veritabanını doğrudan sorgulama

Belirli bir veritabanı takma adını sorgulamak için using() yöntemini kullanın:

# Explicit read from analytics database
reports = AnalyticsReport.objects.using("analytics").filter(date__gte="2025-01-01")

# Write to default
Product.objects.create(name="Widget", price=9.99)

Bağlantı başına veritabanlarındaki yalıtım düzeyleri hakkında daha fazla bilgi için bkz. Engellemeden verileri okuma.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-08-18