本文旨在解决django应用连接sql server数据库时，因实例名（如`server\instance`）中的反斜杠字符转义问题导致的连接失败。通过分析常见错误，提供了一种稳健的解决方案：在django数据库配置中，将主机地址指定为ip地址和端口号的组合（`ip_address,port`），并清空`port`字段，从而避免复杂的字符串转义问题，确保连接稳定。
Django连接SQL Server的常见挑战
在使用Django框架连接Microsoft SQL Server数据库时，开发者常会遇到连接配置方面的挑战，特别是当SQL Server实例不是默认实例（即使用主机名\实例名的形式）时。Python的字符串处理机制，尤其是反斜杠（\）作为转义字符的特性，可能导致在数据库配置字典中传递实例名时出现意外的字符转义，进而引发连接错误，例如django.db.utils.OperationalError: ('HYT00', '[HYT00] [Microsoft][ODBC Driver 17 for SQL Server]Login timeout expired (0) (SQLDriverConnect)')。
最初的配置尝试可能如下所示：
DATABASES = {
'default': {
'ENGINE': 'mssql',
'NAME': "reporting",
'HOST': 'DESKTOP-RC52TD0\\SQL2022', # 尝试使用实例名
'PORT': 1433,
'USER': "sa",
'PASSWORD': "Root_1421",
'OPTIONS': {
'driver': 'ODBC Driver 17 for SQL Server',
},
}
}在这种配置中，即使尝试使用原始字符串（r'DESKTOP-RC52TD0\SQL2022'）或双反斜杠（'DESKTOP-RC52TD0\\\\SQL2022'），问题依然存在。这是因为Python在解析字符串字面量时会处理反斜杠，而当这个字符串被传递给底层数据库驱动时，驱动程序可能再次尝试解析它，导致最终传递给SQL Server的实例名格式不正确。
稳健的解决方案：IP地址与端口组合
解决此问题的最可靠方法是绕过实例名解析的复杂性，直接通过SQL Server的IP地址和其监听的端口进行连接。SQL Server通常监听1433端口（默认实例），或为命名实例分配一个动态端口（也可以配置为静态端口）。
核心策略：
- 在HOST字段中，使用IP地址和端口号，以逗号分隔。
- 将PORT字段留空或设置为一个空字符串。
修改后的DATABASES配置示例如下：
DATABASES = {
'default': {
'ENGINE': 'mssql',
'NAME': 'reporting',
'HOST': '192.168.211.225,56985', # 使用IP地址和端口，以逗号分隔
'PORT': '', # 留空
'USER': 'your_username',
'PASSWORD': 'your_password',
'OPTIONS': {
'driver': 'ODBC Driver 17 for SQL Server',
},
}
}注意： 这里的56985是一个示例动态端口。您需要根据您的SQL Server配置获取正确的端口号。对于默认实例，通常是1433。对于命名实例，可以通过SQL Server Configuration Manager查看或确保SQL Server Browser服务正在运行，但直接指定端口更为可靠。
Docker环境下的配置
在Docker环境中部署Django应用时，通常通过环境变量来管理数据库连接信息。这不仅提高了安全性，也使得配置更加灵活。
以下是一个docker-compose.yml示例，展示了如何通过环境变量设置数据库连接参数：
version: '3'
services:
web:
image: landsoft/reporting-api
network_mode: host # 注意：生产环境建议使用自定义网络而非host模式
build:
context: ./app
command: >
sh -c "python manage.py migrate &&
python manage.py runserver 0.0.0.0:8000"
volumes:
- ./app:/code
ports:
- "8000:8000"
environment:
- DB_HOST="192.168.211.225,56985" # 关键：将IP和端口作为HOST变量
- DB_NAME=reporting
- DB_USER=sa
- DB_PASSWORD=Root_1421
# - DB_PORT="" # 如果HOST中已包含端口，则无需设置DB_PORT在Django应用的settings.py中，可以使用django-environ等库来从环境变量中读取这些配置：
import environ
env = environ.Env(
# 定义默认值和类型
DB_HOST=(str, 'localhost'),
DB_NAME=(str, 'default_db'),
DB_USER=(str, 'user'),
DB_PASSWORD=(str, 'password'),
DB_PORT=(str, ''), # 注意这里是str类型，以支持空字符串
)
# 读取 .env 文件
environ.Env.read_env()
DATABASES = {
'default': {
'ENGINE': 'mssql',
'NAME': env('DB_NAME'),
'HOST': env('DB_HOST'),
'PORT': env('DB_PORT'), # 从环境变量读取，此时可能为空字符串
'USER': env('DB_USER'),
'PASSWORD': env('DB_PASSWORD'),
'OPTIONS': {
'driver': 'ODBC Driver 17 for SQL Server',
},
}
}Dockerfile与驱动安装
为了在Docker容器中成功连接SQL Server，需要安装相应的ODBC驱动。以下是一个精简的Dockerfile示例，展示了安装ODBC Driver 17 for SQL Server的关键步骤：
FROM ubuntu:18.04
ENV PYTHONUNBUFFERED 1
ENV DEBIAN_FRONTEND noninteractive
# 安装基本依赖和Microsoft GPG Key
RUN apt-get update && apt-get install -y curl apt-transport-https python3 python3-pip python3-venv python-dev locales nano gnupg2
RUN curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add -
RUN curl https://packages.microsoft.com/config/ubuntu/18.04/prod.list > /etc/apt/sources.list.d/mssql-release.list
# 安装ODBC Driver 17 for SQL Server及其依赖
ENV ACCEPT_EULA=Y
RUN apt-get update && apt-get -y install msodbcsql17 freetds-dev tdsodbc unixodbc-dev
# 安装mssql-tools (可选，用于命令行工具如sqlcmd)
RUN apt-get update && apt-get install mssql-tools
RUN echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc
RUN /bin/bash -c "source ~/.bashrc"
# 设置Python环境和安装Python依赖
WORKDIR /code
COPY requirements.txt /code/
RUN python3 -m venv /venv
ENV PATH="/venv/bin:$PATH"
RUN /venv/bin/python -m pip install --upgrade pip && \
/venv/bin/pip install -r requirements.txt -v
COPY . /code/
# 配置Locale
RUN echo "en_US.UTF-8 UTF-8" > /etc/locale.gen
RUN locale-genrequirements.txt文件应包含mssql-django等必要的Python包：
Django==3.2.23 mssql-django==1.3 djangorestframework>=3.12.4,<=3.13 drf-spectacular>=0.15.1,<=0.16 Pillow>=8.2.0,<=8.3.0 django-environ>=0.11.2,<=0.12
注意事项与故障排除
- SQL Server防火墙： 确保SQL Server所在机器的防火墙允许传入连接到指定端口（例如1433或命名实例的动态/静态端口）。
- SQL Server配置管理器： 验证SQL Server Configuration Manager中TCP/IP协议已启用，并且对于命名实例，检查其监听的端口号。如果使用动态端口，确保SQL Server Browser服务正在运行。然而，直接配置静态端口并使用IP,PORT的连接方式更为稳定。
- 网络连通性： 确保Django应用所在的容器或主机能够访问SQL Server的IP地址和端口。可以使用ping或telnet IP_ADDRESS PORT命令进行测试。
- 认证方式： 确保USER和PASSWORD对应的是SQL Server的有效登录凭据，且该登录具有访问目标数据库的权限。
总结
通过将Django的SQL Server数据库配置中的HOST字段设置为IP_ADDRESS,PORT的形式，并清空PORT字段，可以有效地规避因Python字符串转义或底层驱动解析实例名带来的连接问题。这种方法提供了更直接、更可靠的数据库连接机制，尤其适用于复杂的部署环境如Docker。同时，结合环境变量管理配置和正确的ODBC驱动安装，能够构建出健壮且易于维护的Django-SQL Server连接方案。
