Microsoft SQL Server Django后端

欢迎使用MSSQL-Django第三方后端项目！

mssql-django是django-mssql-backend的分支。该项目为Django Web框架提供企业级数据库连接选项，支持Microsoft SQL Server和Azure SQL数据库。

我们感谢使该项目成为可能的社区，特别感谢贡献者：OskarPersson、michiya、dlo以及原始的Google Code django-pyodbc团队。展望未来，我们鼓励新旧贡献者参与此项目！

我们希望您喜欢使用MSSQL-Django第三方后端。

功能

• 支持Django 3.2、4.0、4.1、4.2和5.0
• 在Microsoft SQL Server 2016、2017、2019、2022上进行了测试
• 通过了Django测试套件的大部分测试
• 与Microsoft ODBC Driver for SQL Server、SQL Server Native Client和FreeTDS ODBC驱动兼容

依赖项

• pyodbc 3.0或更高版本

安装

1. 安装pyodbc 3.0（或更高版本）和Django

2. 安装mssql-django

   pip install mssql-django
   

3. 将您的Django应用程序或项目使用的settings.py文件中的ENGINE设置设置为'mssql'。

   'ENGINE': 'mssql'
   

配置

标准Django设置

以下条目在DATABASES字典中控制后端的行为

• ENGINE

  字符串。它必须是"mssql"。

• NAME

  字符串。数据库名。必需。

• HOST

  字符串。SQL Server实例的"server\instance"格式。

• PORT

  字符串。服务器实例端口。空字符串表示默认端口。

• USER

  字符串。以"user"格式表示的数据库用户名。如果没有提供，则使用MS集成安全性。

• PASSWORD

  字符串。数据库用户密码。

• TOKEN

  字符串。作为用户或具有数据库访问权限的服务主体获取的访问令牌。例如，当使用azure.identity时，可以将DefaultAzureCredential().get_token('https://database.windows.net/.default')的结果传递。

• AUTOCOMMIT

  布尔值。如果您想禁用Django的事务管理并实现自己的，请将此设置为False。

• Trusted_Connection

  字符串。默认值为"yes"。如果需要，可以设置为"no"。

以下条目也适用于任何给定数据库级别设置字典中的TEST字典

• NAME

  字符串。在运行测试套件时使用的数据库名称。如果使用默认值（None），则测试数据库将使用名称"test_" + NAME。

• COLLATION

  字符串。创建测试数据库时使用的排序规则。如果使用默认值（None），则测试数据库将分配SQL Server实例的默认排序规则。

• DEPENDENCIES

  字符串。数据库的创建顺序依赖关系。有关更多详细信息，请参阅官方Django文档。

• MIRROR

  字符串。在测试期间此数据库应镜像的数据库别名。默认值为None。有关更多详细信息，请参阅官方Django文档。

OPTIONS

字典。当前可用的键是

• driver

  字符串。要使用的ODBC驱动程序（例如："ODBC Driver 17 for SQL Server"、"SQL Server Native Client 11.0"、"FreeTDS"等）。默认值为"ODBC Driver 17 for SQL Server"。

• isolation_level

  字符串。为每个数据库会话设置事务隔离级别。此条目的有效值有：READ UNCOMMITTED、READ COMMITTED、REPEATABLE READ、SNAPSHOT和SERIALIZABLE。默认值是None，表示没有为数据库会话设置隔离级别，将使用SQL Server的默认设置。

• dsn

  字符串。可以使用命名的DSN代替HOST。

• host_is_server

  布尔值。仅在Unix/Linux下使用FreeTDS ODBC驱动程序时相关。

  默认情况下，当使用FreeTDS ODBC驱动程序时，在HOST设置中指定的值将在ODBC连接字符串的SERVERNAME组件中使用，而不是在SERVER组件中使用；这意味着此值应该是存在于freetds.conf FreeTDS配置文件中的数据服务器定义的名称，而不是主机名或IP地址。

  但是，如果此选项存在且其值为True，则此特殊行为将关闭。相反，将使用HOST和PORT选项建立到数据库服务器的连接，无需配置freetds.conf。

  有关更多信息，请参阅https://www.freetds.org/userguide/dsnless.html。

• unicode_results

  布尔值。如果设置为True，则激活pyodbc的unicode_results功能，pyodbc返回的字符串始终是Unicode。默认值为False。

• extra_params

  字符串。为ODBC连接添加额外参数。格式为"param=value;param=value"，可以将Azure AD身份验证（服务主体、交互式、Msi）添加到此字段。

• collation

  字符串。在针对数据库执行文本字段查找时使用此校对名称。默认值为None，表示不添加校对指定符到您的查找SQL（将使用数据库的默认校对）。对于中文语言，可以将其设置为"Chinese_PRC_CI_AS"。

• connection_timeout

  整数。设置数据库连接过程的超时时间（秒）。默认值为0，表示禁用超时。

• connection_retries

  整数。设置数据库连接过程的重试次数。默认值为5。

• connection_retry_backoff_time

  整数。设置数据库连接过程重试的退避时间（秒）。默认值为5。

• query_timeout

  整数。设置数据库查询的超时时间（秒）。默认值为0，表示禁用超时。

• setencoding和setdecoding

  # Example
  "OPTIONS": {
          "setdecoding": [
              {"sqltype": pyodbc.SQL_CHAR, "encoding": 'utf-8'},
              {"sqltype": pyodbc.SQL_WCHAR, "encoding": 'utf-8'}],
          "setencoding": [
              {"encoding": "utf-8"}],
          ...
          },
  

• return_rows_bulk_insert

  布尔值。设置后端是否可以返回批量插入的行。默认值为False，不允许后端从批量插入返回行。如果数据库有带有触发器的表，则必须设置为False以防止插入时出错。

  # Examples
  "OPTIONS": {
      # This database doesn't have any triggers so can use return
      # rows from bulk insert feature
      "return_rows_bulk_insert": True
  }
  
  "OPTIONS": {
      # This database has triggers so leave return_rows_bulk_insert as blank (False)
      # to prevent errors related to inserting and returning rows from bulk insert
  }
  

后端特定设置

以下项目级设置也控制后端的行为

• DATABASE_CONNECTION_POOLING

  布尔值。如果设置为False，则不会激活pyodbc的连接池功能。

示例

以下是一个数据库设置的示例

    DATABASES = {
        'default': {
            'ENGINE': 'mssql',
            'NAME': 'mydb',
            'USER': 'user@myserver',
            'PASSWORD': 'password',
            'HOST': 'myserver.database.windows.net',
            'PORT': '',

            'OPTIONS': {
                'driver': 'ODBC Driver 17 for SQL Server',
            },
        },
    }

    # set this to False if you want to turn off pyodbc's connection pooling
    DATABASE_CONNECTION_POOLING = False

限制

以下功能目前尚未完全支持

• 在迁移中更改模型字段从或到AutoField
• Django annotate函数在某些情况下有浮点运算问题
• 带有exists的annotate函数
• 在order_by中的exists函数
• datatimes的右幂和算术运算
• 时区和timedeltas尚未完全支持
• 具有外键约束的.rename字段/模型
• 数据库级约束
• 过滤索引
• 日期提取函数
• 将具有触发器的表和返回插入行的批量插入

JSONField 查找存在限制，更多详情请参阅这里。

贡献

有关贡献的更多详细信息请参阅这里。

本项目欢迎贡献和建议。大多数贡献需要您同意贡献者许可协议（CLA），声明您有权，并且实际上确实授予我们使用您贡献的权利。有关详细信息，请访问https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人将自动确定您是否需要提供 CLA 并相应地装饰 PR（例如，状态检查，评论）。只需遵循机器人提供的说明。您只需在整个使用我们 CLA 的所有存储库中做一次即可。

本项目已采用Microsoft 开源行为准则。有关更多信息，请参阅行为准则常见问题解答或联系opencode@microsoft.com提出任何额外问题或意见。

安全报告指南

有关安全报告指南，请参阅本存储库中的SECURITY.md文件。

商标

本项目可能包含项目、产品或服务的商标或徽标。Microsoft 商标或徽标的授权使用受Microsoft 商标和品牌指南约束，必须遵守。在修改此项目的版本中使用 Microsoft 商标或徽标不得引起混淆或暗示 Microsoft 的赞助。任何使用第三方商标或徽标的行为均受这些第三方政策约束。