Постоянные соединения с базой данных¶

Persistent connections avoid the overhead of re-establishing a connection to the database in each request. They’re controlled by the CONN_MAX_AGE parameter which defines the maximum lifetime of a connection. It can be set independently for each database.

Значение по умолчанию — «0», сохраняя историческое поведение закрытия соединения с базой данных в конце каждого запроса. Чтобы включить постоянные соединения, установите для CONN_MAX_AGE положительное целое число секунд. Для неограниченных постоянных подключений установите значение «Нет».

Кодировка¶

Django предполагает, что все базы данных используют UTF-8. Использование другой кодировки может привести к неожиданному поведению, например ошибке «value too long», в то время, как данные правильны для Django. Смотрите ниже как настраивать различные базы данных.

Настройки подключения PostgreSQL¶

Смотрите подробности в описании HOST.

Оптимизация настроек PostgreSQL¶

Django необходимы следующие параметры для подключения:

• client_encoding: 'UTF8',

• default_transaction_isolation: 'read committed' по умолчанию, или значение их параметров подключения (смотрите ниже),

• часовой пояс:

  • когда USE_TZ имеет значение True, 'UTC' по умолчанию или значение TIME_ZONE, установленное для соединения,

  • когда USE_TZ имеет значение False, значение глобальной настройки TIME_ZONE.

Если эти параметры уже содержат правильные значения, Django не будет устанавливать их при каждом запросе, что немного улучшит производительность. Вы можете настроить их непосредственно в postgresql.conf, или для каждой базы данных отдельно, используя ALTER ROLE.

Django отлично работает и без этой оптимизации, но для каждого соединения будут выполняться дополнительные запросы для установки параметров.

Уровень изоляции транзакций¶

Как и в PostgreSQL, Django по умолчанию использует READ COMMITTED уровень изоляции транзакций. Если вам нужен более высокий уровень изоляции, такой как REPEATABLE READ или SERIALIZABLE, укажите его в параметрах OPTIONS настройки DATABASES:

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 для столбца. Дополнительный индекс необходим для правильного выполнения поиска, использующего оператор LIKE в своем SQL, как это делается с типами поиска «contains» и «startswith».

Операция миграции для добавления расширений¶

Если вам нужно добавить расширение PostgreSQL (например, hstore, postgis и т. д.) с помощью миграции, используйте операцию CreateExtension.

Курсоры на стороне сервера¶

When using QuerySet.iterator(), Django opens a server-side cursor. By default, PostgreSQL assumes that only the first 10% of the results of cursor queries will be fetched. The query planner spends less time planning the query and starts returning results faster, but this could diminish performance if more than 10% of the results are retrieved. PostgreSQL’s assumptions on the number of rows retrieved for a cursor query is controlled with the cursor_tuple_fraction option.

Ручное указание значений автоинкрементных первичных ключей¶

Django uses PostgreSQL’s SERIAL data type to store auto-incrementing primary keys. A SERIAL column is populated with values from a sequence that keeps track of the next available value. Manually assigning a value to an auto-incrementing field doesn’t update the field’s sequence, which might later cause a conflict. For example:

>>> from django.contrib.auth.models import User
>>> User.objects.create(username='alice', pk=1)
<User: alice>
>>> # The sequence hasn't been updated; its next value is 1.
>>> User.objects.create(username='bob')
...
IntegrityError: duplicate key value violates unique constraint
"auth_user_pkey" DETAIL:  Key (id)=(1) already exists.

If you need to specify such values, reset the sequence afterwards to avoid reusing a value that’s already in the table. The sqlsequencereset management command generates the SQL statements to do that.

Шаблоны тестовых баз данных¶

Вы можете использовать настройку TEST['TEMPLATE'], чтобы указать template (например, 'template0'), на основе которого будет создана тестовая база данных.

Ускорение выполнения тестов с помощью неустойчивых настроек¶

Вы можете ускорить выполнение тестов, настроив PostgreSQL на кратковременный режим.

Поддержка версий¶

Django supports MySQL 5.7 and higher.

Функция Inspectdb в Django использует базу данных Information_schema, которая содержит подробные данные обо всех схемах базы данных.

Django ожидает, что база данных будет поддерживать Unicode (кодировка UTF-8), и делегирует ей задачу обеспечения транзакций и ссылочной целостности. Важно помнить о том, что два последних параметра фактически не поддерживаются MySQL при использовании механизма хранения MyISAM, см. следующий раздел.

Механизмы хранения¶

MySQL имеет несколько «подсистем хранения». Вы можете изменить механизм хранения по умолчанию в конфигурации сервера.

Механизм хранения MySQL по умолчанию — InnoDB. Этот механизм полностью транзакционен и поддерживает ссылки на внешние ключи. Это рекомендуемый выбор. Однако счетчик автоинкремента InnoDB теряется при перезапуске MySQL, поскольку он не запоминает значение AUTO_INCREMENT, а вместо этого воссоздает его как «max(id)+1». Это может привести к непреднамеренному повторному использованию значений AutoField.

Основные недостатки MyISAM заключаются в том, что он не поддерживает транзакции и не применяет ограничения внешнего ключа.

Драйверы API MySQL БД¶

MySQL имеет пару драйверов, которые реализуют API базы данных Python, описанный в PEP 249:

• mysqlclient is a native driver. It’s the recommended choice.

• MySQL Connector/Python — это чистый драйвер Python от Oracle, который не требует клиентской библиотеки MySQL или каких-либо модулей Python за пределами стандартной библиотеки.

Эти драйверы являются потокобезопасными и обеспечивают пул соединений.

В дополнение к драйверу API БД, Django необходим адаптер для доступа к драйверам базы данных из ORM. Django предоставляет адаптер для mysqlclient, а MySQL Connector/Python включает «свой собственный».

Определения часовых поясов¶

Если вы планируете использовать поддержку часовых поясов Django, используйте mysql_tzinfo_to_sql для загрузки таблиц часовых поясов в базу данных MySQL. Это необходимо сделать только один раз для вашего сервера MySQL, а не для каждой базы данных.

Создание вашей базы данных¶

You can create your database using the command-line tools and this SQL:

CREATE DATABASE <dbname> CHARACTER SET utf8;

Это гарантирует, что все таблицы и столбцы будут использовать UTF-8 по умолчанию.

Подключение к базе данных¶

Обратитесь к документации по настройкам.

Настройки подключения используются в следующем порядке:

1. ОПЦИИ.

2. NAME, USER, PASSWORD, HOST, PORT

3. Файлы опций MySQL.

Другими словами, если вы установите имя базы данных в OPTIONS, оно будет иметь приоритет над NAME, которое переопределит все, что есть в ``файле опций MySQL`_.

Вот пример конфигурации, в которой используется файл опций 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.

Создание ваших таблиц¶

Когда Django генерирует схему, он не указывает механизм хранения, поэтому таблицы будут созданы с использованием любого механизма хранения по умолчанию, для которого настроен ваш сервер базы данных. Самое простое решение — установить в качестве механизма хранения по умолчанию вашего сервера базы данных нужный механизм.

Если вы используете услугу хостинга и не можете изменить механизм хранения данных вашего сервера по умолчанию, у вас есть несколько вариантов.

• After the tables are created, execute an ALTER TABLE statement to convert a table to a new storage engine (such as InnoDB):

  ALTER TABLE <tablename> ENGINE=INNODB;
  

  Это может быть утомительно, если у вас много таблиц.

• Другой вариант — использовать опцию init_command для MySQLdb перед созданием таблиц:

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

  Это устанавливает механизм хранения по умолчанию при подключении к базе данных. После создания таблиц следует удалить эту опцию, поскольку она добавляет запрос, который необходим только во время создания таблицы, к каждому соединению с базой данных.

Название таблицы¶

Даже в последних версиях MySQL существуют известные проблемы, которые могут привести к изменению регистра имени таблицы при выполнении определенных операторов SQL при определенных условиях. Рекомендуется по возможности использовать имена таблиц в нижнем регистре, чтобы избежать проблем, которые могут возникнуть из-за такого поведения. Django использует имена таблиц в нижнем регистре, когда автоматически генерирует имена таблиц из моделей, поэтому это особенно важно, если вы переопределяете имя таблицы с помощью параметра db_table.

Точки сохранения¶

И Django ORM, и MySQL (при использовании механизма хранения InnoDB <mysql-storage-engines>) поддерживают точки сохранения базы данных <topics-db-transactions-savepoints>`.

Если вы используете механизм хранения MyISAM, имейте в виду, что вы получите ошибки, генерируемые базой данных, если попытаетесь использовать методы API транзакций <topics-db-transactions-savepoints>, связанные с точкой сохранения. Причина этого в том, что обнаружение механизма хранения базы данных/таблицы MySQL является дорогостоящей операцией, поэтому было решено, что не стоит динамически преобразовывать эти методы в пустые на основе результатов такого обнаружения.

Примечания к конкретным полям¶

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

Блокировка строк с помощью QuerySet.select_for_update()¶

MySQL и MariaDB не поддерживают некоторые параметры оператора SELECT ... FOR UPDATE. Если select_for_update() используется с неподдерживаемой опцией, то выдается ошибка NotSupportedError.

При использовании select_for_update() в MySQL убедитесь, что вы фильтруете набор запросов по крайней мере по набору полей, содержащихся в уникальных ограничениях, или только по полям, охватываемым индексами. В противном случае будет установлена ​​эксклюзивная блокировка записи для всей таблицы на время транзакции.

Автоматическое приведение типов может привести к неожиданным результатам¶

При выполнении запроса к строковому типу, но с целочисленным значением, MySQL приведёт типы всех значений в таблице к целому числу перед выполнением сравнения. Если ваша таблица содержит значения 'abc', 'def' и вы запрашиваете WHERE mycolumn=0, обе строки будут совпадать. Аналогично, WHERE mycolumn=1 будет соответствовать значению abc1. Таким образом, поля строкового типа, включенные в Django, всегда преобразуют значение в строку перед использованием ее в запросе.

Если вы реализуете пользовательские поля модели, которые наследуются от Field напрямую, переопределяют get_prep_value() или используете RawSQL, extra() или raw(), вы должны убедиться, что выполняете соответствующее приведение типов.

Соответствие подстроки и чувствительность к регистру¶

For all SQLite versions, there is some slightly counter-intuitive behavior when attempting to match some types of strings. These are triggered when using the iexact or contains filters in Querysets. The behavior splits into two cases:

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.

Некоторые возможные обходные пути для этого задокументированы на sqlite.org, но они не используются бэкендом SQLite по умолчанию в Django, поскольку их включение было бы довольно сложно сделать надежным. Таким образом, Django предоставляет поведение SQLite по умолчанию, и вы должны знать об этом при выполнении фильтрации без учета регистра или подстроки.

Десятичная обработка¶

SQLite не имеет настоящего десятичного внутреннего типа. Десятичные значения внутренне преобразуются в тип данных REAL (8-байтовое число с плавающей запятой IEEE), как описано в документации по типам данных SQLite, поэтому они не поддерживают правильно округленную десятичную арифметику с плавающей запятой.

Ошибки «База данных заблокирован໶

SQLite задуман как облегченная база данных и, следовательно, не может поддерживать высокий уровень параллелизма. Ошибки OperationalError: база данных заблокирована указывают на то, что ваше приложение испытывает больший параллелизм, чем sqlite может обработать в конфигурации по умолчанию. Эта ошибка означает, что один поток или процесс имеет исключительную блокировку соединения с базой данных, а у другого потока истекло время ожидания снятия блокировки.

Оболочка Python SQLite имеет значение тайм-аута по умолчанию, которое определяет, как долго второму потоку разрешено ждать блокировки, прежде чем истечет время ожидания, и выдает ошибку «OperationalError: база данных заблокирована».

Если вы получаете эту ошибку, вы можете решить ее следующим образом:

• Переключение на другую базу данных. В определенный момент SQLite становится слишком «облегченным» для реальных приложений, и такого рода ошибки параллелизма указывают на то, что вы достигли этой точки.

• Перепишите код, чтобы уменьшить параллелизм и обеспечить кратковременность транзакций базы данных.

• Увеличьте значение таймаута по умолчанию, установив параметр базы данных timeout:

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

  Это заставит SQLite ждать немного дольше, прежде чем выдать ошибку «база данных заблокирована»; на самом деле он ничего не сделает для их решения.

QuerySet.select_for_update() не поддерживается¶

SQLite не поддерживает синтаксис SELECT … FOR UPDATE. Вызов не даст никакого эффекта.

«pyformat» parameter style in raw queries not supported¶

For most backends, raw queries (Manager.raw() or cursor.execute()) can use the «pyformat» parameter style, where placeholders in the query are given as '%(name)s' and the parameters are passed as a dictionary rather than a list. SQLite does not support this.

Изоляция при использовании QuerySet.iterator()¶

Существуют особые особенности, описанные в разделе «Изоляция в SQLite» при изменении таблицы во время итерации по ней с использованием QuerySet.iterator(). Если строка добавляется, изменяется или удаляется внутри цикла, то эта строка может появиться, а может и не появиться, или может появиться дважды в последующих результатах, полученных от итератора. Ваш код должен справиться с этим.

Включение расширения JSON1 в SQLite¶

Чтобы использовать JSONField в SQLite, вам необходимо включить расширение JSON1 в библиотеке Python sqlite3. Если расширение не включено в вашей установке, возникнет системная ошибка (fields.E180).

Чтобы включить расширение JSON1, вы можете следовать инструкциям на «вики-странице»_.

Подключение к базе данных¶

Чтобы подключиться с использованием имени службы вашей базы данных 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 будет использовать другой дескриптор подключения в зависимости от этого выбора.

'NAME': 'localhost:1521/orclpdb1',

'NAME': (
    '(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))'
    '(CONNECT_DATA=(SERVICE_NAME=orclpdb1)))'
),

Резьбовой вариант¶

Если вы планируете запускать Django в многопоточной среде (например, Apache, используя модуль MPM по умолчанию в любой современной операционной системе), то вы должны установить для параметра threaded конфигурации вашей базы данных Oracle значение True:

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

Невыполнение этого требования может привести к сбоям и другому странному поведению.

ВСТАВИТЬ… ВОЗВРАЩАЕМСЯ В¶

По умолчанию серверная часть Oracle использует предложение RETURNING INTO для эффективного получения значения AutoField при вставке новых строк. Такое поведение может привести к ошибке DatabaseError в некоторых необычных настройках, например, при вставке в удаленную таблицу или в представление с триггером INSTEAD OF. Предложение RETURNING INTO можно отключить, установив для параметра use_returning_into конфигурации базы данных значение False:

'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, кавычки не имеют никакого эффекта.

При выполнении миграции может возникнуть ошибка ORA-06552, если определенные ключевые слова Oracle используются в качестве имени поля модели или значения опции db_column. Django заключает в кавычки все идентификаторы, используемые в запросах, чтобы предотвратить большинство подобных проблем, но эта ошибка все равно может возникнуть, если в качестве имени столбца используется тип данных Oracle. В частности, старайтесь не использовать имена date, timestamp, number или float в качестве имени поля.

NULL и пустые строки¶

Джанго обычно предпочитает использовать пустую строку (''), а не NULL, но Oracle обрабатывает обе строки одинаково. Чтобы обойти эту проблему, серверная часть Oracle игнорирует явную опцию null для полей, которые имеют пустую строку в качестве возможного значения, и генерирует DDL, как если бы null=True. При выборке из базы данных предполагается, что значение NULL в одном из этих полей действительно означает пустую строку, и данные автоматически преобразуются, чтобы отразить это предположение.

Ограничения TextField¶

Бэкэнд Oracle хранит TextFields как столбцы NCLOB. Oracle в целом накладывает некоторые ограничения на использование таких столбцов LOB:

• Столбцы LOB нельзя использовать в качестве первичных ключей.

• Столбцы LOB нельзя использовать в индексах.

• Столбцы LOB нельзя использовать в списке SELECT DISTINCT. Это означает, что попытка использовать метод QuerySet.distinct в модели, которая включает столбцы TextField, приведет к ошибке ORA-00932 при запуске в Oracle. В качестве обходного пути используйте метод QuerySet.defer в сочетании с distinct(), чтобы предотвратить включение столбцов TextField в список SELECT DISTINCT.