数据库¶

持久连接¶

持久连接避免了在每个请求中重新建立到数据库的连接的开销。它们由 CONN_MAX_AGE 参数控制，该参数定义连接的最大生存期。它可以为每个数据库单独设置。

默认值为 0，保留在每个请求结束时关闭数据库连接的历史行为。要启用持久连接，请将 CONN_MAX_AGE 设置为正数秒。对于无限持续连接，请将其设置为 None。

编码¶

Django假定所有数据库都使用UTF-8编码。使用其他编码可能会导致意外的行为，例如数据库中对于在Django中有效的数据的“值太长”错误。有关如何正确设置数据库的信息，请参阅下面的数据库特定说明。

PostgreSQL连接设置¶

有关详细信息，请参阅 HOST。

优化PostgreSQL的配置¶

Django需要以下参数用于其数据库连接：

• client_encoding：'UTF8'，

• default_transaction_isolation：'read committed' 默认情况下，或在连接选项中设置的值（见下文），

• timezone：USE_TZ 为 True 时的 'UTC'，否则为 TIME_ZONE。

如果这些参数已经具有正确的值，Django不会为每个新连接设置它们，这会稍微提高性能。您可以直接在 postgresql.conf 中配置它们，或者更方便地每个具有 ALTER ROLE 的数据库用户配置它们。

Django将工作正常没有这种优化，但每个新的连接将做一些额外的查询设置这些参数。

隔离级别¶

像PostgreSQL本身一样，Django默认为 READ COMMITTED isolation level。如果需要更高的隔离级别（如 REPEATABLE READ 或 SERIALIZABLE），请将其设置在 DATABASES 中数据库配置的 OPTIONS 部分中:

import psycopg2.extensions

DATABASES = {
    # ...
    'OPTIONS': {
        'isolation_level': psycopg2.extensions.ISOLATION_LEVEL_SERIALIZABLE,
    },
}

varchar 和 text 列的索引¶

当在模型字段上指定 db_index=True 时，Django通常会输出单个 CREATE INDEX 语句。但是，如果字段的数据库类型是 varchar 或 text （例如，由 CharField，FileField 和 TextField 使用），则Django将创建一个附加索引，该列使用适当的 PostgreSQL operator class。额外的索引对于正确执行在其SQL中使用 LIKE 运算符的查找是必要的，与 contains 和 startswith 查找类型一样。

添加扩展的迁移操作¶

如果您需要使用迁移添加PostgreSQL扩展（如 hstore，postgis 等），请使用 CreateExtension 操作。

使用非持久设置加快测试执行速度¶

您可以通过 将PostgreSQL配置为非持久性 加快测试执行时间。

版本支持¶

Django支持MySQL 5.5及更高版本。

Django的 inspectdb 功能使用 information_schema 数据库，其中包含所有数据库模式的详细数据。

Django希望数据库支持Unicode（UTF-8编码），并委托它来执行事务和引用完整性的任务。重要的是要知道，当使用MyISAM存储引擎时，后两个实际上并不由MySQL执行，请参阅下一节。

存储引擎¶

MySQL有几个 storage engines。您可以更改服务器配置中的默认存储引擎。

直到MySQL 5.5.4，默认引擎是 MyISAM [1]。 MyISAM的主要缺点是它不支持事务或强制外键约束。在更好的方面，它是唯一支持全文索引和搜索直到MySQL 5.6.4的引擎。

从MySQL 5.5.5开始，默认存储引擎是 InnoDB。这个引擎是完全事务性的，并支持外键引用。这可能是最好的选择。但是，请注意，InnoDB自动增量计数器在MySQL重新启动时会丢失，因为它不记住 AUTO_INCREMENT 值，而是将其重新创建为“max（id）+1”。这可能导致 AutoField 值的无意重用。

如果将现有项目升级到MySQL 5.5.5并随后添加一些表，请确保您的表使用相同的存储引擎（即MyISAM vs. InnoDB）。具体来说，如果表之间具有 ForeignKey 的表使用不同的存储引擎，则在运行 migrate 时可能会看到类似以下的错误:

_mysql_exceptions.OperationalError: (
    1005, "Can't create table '\\db_name\\.#sql-4a8_ab' (errno: 150)"
)

MySQL DB API驱动程序¶

Python数据库API在 PEP 249 中描述。 MySQL有三个突出的驱动程序实现这个API：

• MySQLdb 是一个本地驱动程序，由Andy Dustman开发和支持十多年。

• mysqlclient 是 MySQLdb 的一个分支，它特别支持Python 3，可以作为MySQLdb的替代。在写这篇文章的时候，这是使用MySQL与Django的 推荐选择。

• MySQL Connector/Python 是Oracle的纯Python驱动程序，不需要MySQL客户端库或标准库外的任何Python模块。

所有这些驱动程序是线程安全的，并提供连接池。 MySQLdb 是目前唯一不支持Python 3的。

除了DB API驱动程序，Django需要一个适配器来从其ORM访问数据库驱动程序。 Django为MySQLdb/mysqlclient提供了一个适配器，而MySQL Connector/Python包括 its own。

时区定义¶

如果计划使用Django的 时区支持，请使用 mysql_tzinfo_to_sql 将时区表加载到MySQL数据库中。这需要为您的MySQL服务器只做一次，而不是每个数据库。

创建数据库¶

您可以使用命令行工具和此SQL的 create your database:

CREATE DATABASE <dbname> CHARACTER SET utf8;

这确保所有表和列默认使用UTF-8。

连接到数据库¶

请参阅 设置文档。

连接设置按此顺序使用：

1. OPTIONS。

2. NAME，USER，PASSWORD，HOST，PORT

3. MySQL选项文件。

换句话说，如果在 OPTIONS 中设置数据库的名称，这将优先于 NAME，这将覆盖 MySQL option file 中的任何内容。

这里有一个使用MySQL选项文件的配置示例:

# settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'OPTIONS': {
            'read_default_file': '/path/to/my.cnf',
        },
    }
}


# my.cnf
[client]
database = NAME
user = USER
password = PASSWORD
default-character-set = utf8

其他一些MySQLdb连接选项可能很有用，例如 ssl，init_command 和 sql_mode。有关详细信息，请咨询 MySQLdb documentation。

创建表¶

当Django生成模式时，它不指定存储引擎，因此将使用您的数据库服务器配置的默认存储引擎创建表。最简单的解决方案是将数据库服务器的默认存储引擎设置为所需的引擎。

如果您使用的是托管服务，并且无法更改服务器的默认存储引擎，则有几个选项。

• 创建表后，执行 ALTER TABLE 语句将表转换为新的存储引擎（如InnoDB）:

  ALTER TABLE <tablename> ENGINE=INNODB;
  

  如果你有很多表，这可能是乏味的。

• 另一个选项是在创建表之前对MySQLdb使用 init_command 选项:

  'OPTIONS': {
     'init_command': 'SET default_storage_engine=INNODB',
  }
  

  这将在连接到数据库时设置默认存储引擎。创建表后，应该删除此选项，因为它添加的查询仅在创建表时用于每个数据库连接。

表名¶

即使在最新版本的MySQL中也有 known issues，在某些条件下执行某些SQL语句时，可能会导致更改表名。如果可能，建议您使用小写表名，以避免此行为可能导致的任何问题。 Django在从模型中自动生成表名时使用小写表名，因此如果您通过 db_table 参数覆盖表名，那么这主要是一个考虑因素。

保存点¶

Django ORM和MySQL（当使用InnoDB 存储引擎 时）支持数据库 保存点。

如果您使用MyISAM存储引擎，请注意，如果您尝试使用 事务API的保存点相关方法，您将收到数据库生成的错误。这样做的原因是检测MySQL数据库/表的存储引擎是一种昂贵的操作，因此决定在这种检测的结果中基于无操作来动态地转换这些方法是不值得的。

有关特定字段的说明¶

ALTER TABLE `your_table` MODIFY `your_datetime_column` DATETIME(6)

行锁定与 QuerySet.select_for_update()¶

MySQL不支持 SELECT ... FOR UPDATE 语句的 NOWAIT 选项。如果 select_for_update() 与 nowait=True 一起使用，则将产生 DatabaseError。

自动转印可能会导致意外的结果¶

当对字符串类型执行查询但是使用整数值时，MySQL将在执行比较之前将表中所有值的类型强制为整数。如果您的表包含值 'abc'，'def' 并且您查询 WHERE mycolumn=0，则两行都将匹配。类似地，WHERE mycolumn=1 将匹配值 'abc1'。因此，Django中包含的字符串类型字段在将其用于查询之前，将始终将该值转换为字符串。

如果实现直接继承 Field 的自定义模型字段，覆盖 get_prep_value()，或使用 RawSQL，extra() 或 raw()，则应确保执行适当的类型转换。

子字符串匹配和区分大小写¶

对于所有SQLite版本，当尝试匹配某些类型的字符串时，有一些稍微违反直觉的行为。当在查询集中使用 iexact 或 contains 过滤器时会触发这些。行为分为两种情况：

1. For substring matching, all matches are done case-insensitively. That is a filter such as filter(name__contains="aa") will match a name of "Aabb".

2. For strings containing characters outside the ASCII range, all exact string matches are performed case-sensitively, even when the case-insensitive options are passed into the query. So the iexact filter will behave exactly the same as the exact filter in these cases.

一些可能的解决方法是 documented at sqlite.org，但它们不被Django中的默认SQLite后端使用，因为合并它们将是相当困难的。因此，Django暴露了默认的SQLite行为，在进行不区分大小写或子串过滤时，您应该注意到这一点。

老SQLite和 CASE 表达式¶

SQLite 3.6.23.1和更旧版本包含一个错误，当 handling query parameters 在包含 ELSE 和算术的 CASE 表达式中。

SQLite 3.6.23.1是在2010年3月发布的，大多数不同平台的最新二进制发行版都包括较新版本的SQLite，除了适用于Windows的Python 2.7安装程序之外。

在撰写本文时，最新版本的Windows - Python 2.7.10 - 包括SQLite 3.6.21。您可以安装 pysqlite2 或用 https://www.sqlite.org/ 的较新版本替换 sqlite3.dll （默认安装在 C:\Python27\DLLs 中）以解决此问题。

使用较新版本的SQLite DB-API 2.0驱动程序¶

Django将使用一个 pysqlite2 模块，优先于随着Python标准库提供的 sqlite3，如果它发现一个可用。

这提供了将DB-API 2.0接口或SQLite 3本身升级到比特定Python二进制分发版本更新的版本的能力，如果需要的话。

“数据库被锁定”错误¶

SQLite是一个轻量级的数据库，因此不能支持高水平的并发性。 OperationalError: database is locked 错误指示您的应用程序遇到的并发性比 sqlite 在默认配置中可以处理的更多。这个错误意味着一个线程或进程对数据库连接有一个独占锁，另一个线程超时等待锁被释放。

Python SQLite包装器有一个默认超时值，它决定第二个线程在超时之前允许等待锁的时间，并引发 OperationalError: database is locked 错误。

如果您收到此错误，您可以通过以下方式解决：

• 切换到另一个数据库后端。在某一点上，SQLite对于现实世界的应用程序变得过于“轻”，这些并发错误表明你已经达到了这一点。

• 重写代码以减少并发性，并确保数据库事务是短暂的。

• 通过设置 timeout 数据库选项来增加默认超时值:

  'OPTIONS': {
      # ...
      'timeout': 20,
      # ...
  }
  

  这将简单地使SQLite等待一段时间，然后抛出“数据库被锁定”的错误；它不会真正做任何事情来解决它们。

不支持 QuerySet.select_for_update()¶

SQLite不支持 SELECT ... FOR UPDATE 语法。调用它将没有效果。

不支持原始查询中的“pyformat”参数样式¶

对于大多数后端，原始查询（Manager.raw() 或 cursor.execute()）可以使用“pyformat”参数样式，其中查询中的占位符以 '%(name)s' 的形式给出，参数作为字典而不是列表传递。 SQLite不支持这个。

连接到数据库¶

要使用Oracle数据库的服务名称进行连接，您的 settings.py 文件应如下所示:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.oracle',
        'NAME': 'xe',
        'USER': 'a_user',
        'PASSWORD': 'a_password',
        'HOST': '',
        'PORT': '',
    }
}

在这种情况下，您应该将 HOST 和 PORT 都留空。但是，如果您不使用 tnsnames.ora 文件或类似的命名方法，并希望使用SID（本示例中为“xe”）进行连接，那么请填写 HOST 和 PORT，如此:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.oracle',
        'NAME': 'xe',
        'USER': 'a_user',
        'PASSWORD': 'a_password',
        'HOST': 'dbprod01ned.mycompany.com',
        'PORT': '1540',
    }
}

您应该提供 HOST 和 PORT，或者将两者都留为空字符串。 Django将根据这个选择使用不同的连接描述符。

螺纹选项¶

如果计划在多线程环境中运行Django（例如Apache在任何现代操作系统上使用默认MPM模块），那么 必须 将Oracle数据库配置的 threaded 选项设置为True:

'OPTIONS': {
    'threaded': True,
},

否则可能会导致崩溃和其他异常行为。

INSERT ... RETURNING INTO¶

默认情况下，Oracle后端在插入新行时使用 RETURNING INTO 子句有效地检索 AutoField 的值。此行为可能导致在某些异常设置中的 DatabaseError，例如当插入远程表时或在具有 INSTEAD OF 触发器的视图中。可以通过将数据库配置的 use_returning_into 选项设置为False来禁用 RETURNING INTO 子句:

'OPTIONS': {
    'use_returning_into': False,
},

在这种情况下，Oracle后端将使用单独的 SELECT 查询来检索AutoField值。

命名问题¶

Oracle强制实施名称长度限制为30个字符。为了适应这一点，后端截断数据库标识符以适应，用可重复的MD5哈希值替换截断的名称的最后四个字符。此外，后端将数据库标识符转换为全大写。

为了防止这些转换（这通常仅在处理遗留数据库或访问属于其他用户的表时才需要），请使用带引号的名称作为 db_table 的值:

class LegacyModel(models.Model):
    class Meta:
        db_table = '"name_left_in_lowercase"'

class ForeignModel(models.Model):
    class Meta:
        db_table = '"OTHER_USER"."NAME_ONLY_SEEMS_OVER_30"'

引号名称也可以与Django的其他受支持的数据库后端一起使用；除了Oracle，但是，引号没有效果。

当运行 migrate 时，如果将某些Oracle关键字用作模型字段的名称或 db_column 选项的值，则可能会遇到 ORA-06552 错误。 Django引用查询中使用的所有标识符来防止大多数这样的问题，但是当Oracle数据类型用作列名时，仍然会发生此错误。特别地，注意避免使用名称 date，timestamp，number 或 float 作为字段名称。

NULL和空字符串¶

Django通常更喜欢使用空字符串（’‘），而不是NULL，但Oracle对待它们是相同的。为了解决这个问题，Oracle后端会忽略在空字符串作为可能值的字段上显式 null 选项，并生成DDL，如同 null=True。当从数据库中获取时，假设这些字段之一中的 NULL 值实际上意味着空字符串，并且数据被静默地转换以反映这个假设。

TextField 限制¶

Oracle后端将 TextFields 存储为 NCLOB 列。 Oracle对这种LOB列的使用有一些限制：

• LOB列不能用作主键。

• LOB列不能在索引中使用。

• LOB列不能在 SELECT DISTINCT 列表中使用。这意味着在包含 TextField 列的模型上尝试使用 QuerySet.distinct 方法将导致针对Oracle运行时出现 ORA-00932 错误。作为解决方法，使用 QuerySet.defer 方法与 distinct() 结合，以防止 TextField 列包含在 SELECT DISTINCT 列表中。