ODBC安装及Django配置

预计阅读时间：25-35 分钟。本文包含 macOS 和 Windows 平台的配置方法，您可以根据您的操作系统选择阅读相应部分。实际操作中，软件下载和安装可能需要额外时间。

开始之前

在开始配置之前，我们先简单了解几个基本概念，这会让你对接下来的操作更有数。

什么是 ODBC？我为什么需要它？

ODBC (Open Database Connectivity)：你可以把它想象成一个通用的“翻译官”或“适配器”。很多不同的应用程序（比如我们这里的 Python/Django）想要和各种不同的数据库（比如 SQL Server、Oracle、MySQL 等）“对话”。ODBC 提供了一套标准的接口（API），让应用程序可以用一种统一的方式来请求数据，而不用关心底层数据库的具体实现细节。
为什么需要？ 对于某些数据库（尤其是像 SQL Server 这样的商业数据库），Python 的数据库驱动（比如 pyodbc 或 Django 使用的 mssql-django 后端间接依赖的驱动）会通过 ODBC 来与数据库通信。ODBC 驱动程序由数据库厂商（如微软）或第三方提供，并安装在你的操作系统上。

为什么 Java 连接数据库好像不太需要 ODBC，但 Python 有时需要？

Java 有 JDBC (Java Database Connectivity)：Java 生态系统中有其自己的一套标准接口 JDBC。数据库厂商通常会提供纯 Java 的 JDBC 驱动程序，这些驱动程序直接实现了与数据库通信的协议，所以它们不依赖操作系统层面的 ODBC。
Python 的情况：Python 也有很多数据库的直接驱动程序（比如 psycopg2 for PostgreSQL, mysqlclient for MySQL），它们可能不依赖 ODBC。但对于 SQL Server，一种常见的连接方式就是通过 ODBC。Django 在连接 SQL Server 时，其后端库（如 mssql-django）通常会利用系统上已安装的 ODBC 驱动。

本文会用到哪些 ODBC 相关程序/驱动？

在 macOS 上连接 SQL Server：

我们会使用 unixODBC：一个开源的 ODBC 管理器，相当于 Windows 上的 ODBC 数据源管理器。
以及 FreeTDS：一个开源的驱动程序，让 macOS/Linux 系统能够连接到 SQL Server。

在 Windows 上连接 SQL Server：

我们会使用 Windows 系统自带的 “ODBC 数据源管理器”。
以及微软官方提供的 “ODBC Driver for SQL Server” (例如 ODBC Driver 17/18 for SQL Server)。

关于 Oracle 连接：

本文后续展示的 Django 连接 Oracle 的示例，将采用 Oracle 特有的连接字符串方式，它不依赖于我们前面为 SQL Server 配置的 ODBC，而是通过 Django 的 Oracle 后端直接与 Oracle 客户端库（如果需要）或数据库通信。

简单来说，ODBC 就像一座桥梁，帮助我们的 Python/Django 应用连接到特定类型的数据库。接下来的内容，我们将一步步教你如何在你的 Mac 或 Windows 系统上搭建这座“桥梁”来连接 SQL Server，并配置 Django 项目使用它。

Mac系统连接SQLServer

本章节描述的在macOS上使用 unixODBC 和 FreeTDS 连接SQL Server的配置流程，其核心原理和步骤与在Linux系统上操作非常相似。主要区别在于软件包的安装命令（例如，您会使用 apt、yum 或 dnf 而不是 brew）以及配置文件的默认存放路径。理解了macOS的配置过程后，您可以触类旁通地在Linux上完成类似配置。

Mac：系统版本Sonoma14.5；brew4.4.6

SQLServer：2019版本（容器镜像为mcr.microsoft.com/mssql/server:2019-latest）

brew install unixodbc
brew install freetds

open -e /opt/homebrew/etc/odbcinst.ini  # 编辑文件
# 在文件末尾输入下面的内容，用来将FreeTDS注册到unixodbc中
[FreeTDS]
Description=FreeTDS Driver
Driver=/opt/homebrew/lib/libtdsodbc.so


open -e /opt/homebrew/etc/odbc.ini  # 编辑文件
# 在文件末尾输入下面的内容，请根据你实际要连接的数据库配置Server、Port和Database
# 如果你使用的SQLServer版本较老，TDS_Version可尝试小一点的版本，例如7.0
[djangoadmindemo]
Driver=FreeTDS
Server=127.0.0.1
Port=7011
Database=djangoadmin
TDS_Version=7.4

你可以使用下面的命令来验证ODBC是否配置正确

export ODBCSYSINI=/opt/homebrew/etc
export ODBCINI=/opt/homebrew/etc/odbc.ini
odbcinst -q -s  # 如果配置正确，会列出你配置的所有数据源名称
isql -v djangoadmindemo sa ********  # 使用指定的用户和密码连接djangoadmindemo数据源

Django项目配置文件中，数据库连接配置的OPTIONS参考下面的写法

DATABASES = {
    'default': {
        ......
        'OPTIONS': {
            "driver": "FreeTDS",
            'dsn': "djangoadmindemo",
        },
    }
}

Windows系统连接SQLServer

Windows：win10专业版

SQLServer：2019版本（容器镜像为mcr.microsoft.com/mssql/server:2019-latest）

驱动下载和安装

点击下面的链接，选择合适的版本进行下载：

Download ODBC Driver for SQL Server - ODBC Driver for SQL Server | Microsoft Learn

安装完成后，按win+R，输入odbcad32，打开ODBC数据源管理程序：

点击添加，如果你的SQLServer版本比较新，就选择ODBC Driver 18 for SQL Server，如果很老，就选择SQL Server。

注意：服务器的IP和端口之前请用逗号,分割，不要用冒号:

一直点下一步，最后点击测试数据源。

如果提示“证书链是由不受信任的颁发机构颁发的。”，可以返回上一步，勾选“信任服务证书”

Django项目配置文件中，数据库连接配置的OPTIONS参考下面的写法，driver对应上图的驱动程序，dsn对应上图的名称。

DATABASES = {
    'default': {
        ......
        'OPTIONS': {
            "driver": "ODBC Driver 18 for SQL Server",
            'dsn': "djangoadmindemo",
        },
    }
}

连接ORACLE

Oracle：23版本（容器镜像为gvenzl/oracle-free:23）

（注：Django5.0和Django4.X都要求Oracle版本为19c或更高）

请参考下面的示例进行配置：

    'default': {
        'ENGINE': 'django.db.backends.oracle',
        'NAME': (
            "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=162.105.132.198)(PORT=7012))"
            "(CONNECT_DATA=(SERVICE_NAME=FREEPDB1)))"
        ),  # ORACLE的连接描述，如果你配置了tnsnames.ora，你可以在这里只指定服务名的名称
        'USER': 'djangoadmin',
        'PASSWORD': '**********',
    }