Много баз данных

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

Определение ваших баз данных

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

Базы данных могут иметь любой выбранный вами псевдоним. Однако псевдоним default имеет особое значение. Django использует базу данных с псевдонимом default при отсутствии выбора другой базы данных.

Следующий пример settings.py определяет две базы данных — базу данных PostgreSQL по умолчанию и базу данных MySQL, называемую users:

DATABASES = {
    'default': {
        'NAME': 'app_data',
        'ENGINE': 'django.db.backends.postgresql',
        'USER': 'postgres_user',
        'PASSWORD': 's3krit'
    },
    'users': {
        'NAME': 'user_data',
        'ENGINE': 'django.db.backends.mysql',
        'USER': 'mysql_user',
        'PASSWORD': 'priv4te'
    }
}

Если понятие default базы данных не имеет смысла в контексте вашего проекта, вам необходимо быть внимательным и всегда указывать используемую базу данных. Django требует, чтобы запись default базы данных была определена, но словарь параметров может быть пустым, если он не будет использоваться. Для всех моделей ваших приложений, включая те, которые находятся в приложениях contrib и сторонних приложениях, которые вы используете, необходимо настроить DATABASE_ROUTERS, чтобы никакие запросы не были перенаправлены на базу данных по умолчанию. Следующий пример settings.py определяет две базы данных, отличные от базы данных по умолчанию, при этом запись default намеренно оставлена пустой:

DATABASES = {
    'default': {},
    'users': {
        'NAME': 'user_data',
        'ENGINE': 'django.db.backends.mysql',
        'USER': 'mysql_user',
        'PASSWORD': 'superS3cret'
    },
    'customers': {
        'NAME': 'customer_data',
        'ENGINE': 'django.db.backends.mysql',
        'USER': 'mysql_cust',
        'PASSWORD': 'veryPriv@ate'
    }
}

Если вы попытаетесь получить доступ к базе данных, которую вы не определили в настройке DATABASES, Django вызовет исключение django.db.utils.ConnectionDoesNotExist.

Синхронизация баз данных

Команда управления migrate работает с одной базой данных за раз. По умолчанию она работает с базой данных default, но с помощью опции --database вы можете указать, что она должна синхронизировать другую базу данных. Таким образом, чтобы синхронизировать все модели со всеми базами данных в нашем примере, вам необходимо выполнить:

$ ./manage.py migrate
$ ./manage.py migrate --database=users

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

Использование других команд управления

Другие команды django-admin управления, взаимодействующие с базой данных, работают так же, как и migrate — они всегда работают с одной базой данных за раз, используя --database для управления используемой базой данных.

Автоматическое маршрутизирование баз данных

Самый простой способ использования нескольких баз данных — настроить схему маршрутизации баз данных. Схема маршрутизации по умолчанию гарантирует, что объекты остаются «привязанными» к исходной базе данных (т.е., объект, извлеченный из базы данных foo будет сохранён в той же базе данных). Схема маршрутизации по умолчанию гарантирует, что если база данных не указана, все запросы возвращаются к базе данных default.

Вам ничего не нужно делать, чтобы активировать схему маршрутизации по умолчанию — она предоставляется «из коробки» в каждом проекте Django. Однако, если вы хотите реализовать более интересные методы распределения баз данных, вы можете определить и установить собственные маршрутизаторы баз данных.

Маршрутизаторы баз данных

Маршрутизатор базы данных — это класс, который предоставляет до четырёх методов:

db_for_read(model, **hints)

Предлагает базу данных, которая должна использоваться для операций чтения для объектов типа model.

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

Возвращает None если нет предложения.

db_for_write(model, **hints)

Предлагает базу данных, которая должна использоваться для записи объектов типа Model.

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

Возвращает None если нет предложения.

allow_relation(obj1, obj2, **hints)

Возвращает True если отношение между obj1 и obj2 должно быть разрешено, False если отношение должно быть запрещено, или None если маршрутизатор не имеет мнения. Это чисто операция валидации, используемая операциями внешних ключей и многие-ко-многим для определения, должно ли быть разрешено отношение между двумя объектами.

allow_migrate(db, app_label, model_name=None, **hints)

Определяет, разрешена ли операция миграции в базе данных с псевдонимом db. Возвращает True если операция должна быть выполнена, False если она не должна быть выполнена, или None если маршрутизатор не имеет мнения.

Позиционный аргумент app_label — это метка приложения, которое мигрируется.

model_name устанавливается большинством операций миграции в значение model._meta.model_name (нижняя строка модели __name__ модели, которая мигрируется). Его значение — None для операций RunPython и RunSQL, если они не предоставляют его с помощью подсказок.

hints используются некоторыми операциями для передачи дополнительной информации маршрутизатору.

Когда model_name установлено, hints обычно содержит класс модели по ключу 'model'. Обратите внимание, что это может быть историческая модель, и, следовательно, не иметь никаких пользовательских атрибутов, методов или менеджеров. Вы должны полагаться только на _meta.

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

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

Подпись allow_migrate значительно изменилась по сравнению с предыдущими версиями. См. примечания о устаревании для получения дополнительной информации.

Маршрутизатор не обязательно должен предоставлять все эти методы — он может опустить один или несколько из них. Если один из методов пропущен, Django пропустит этот маршрутизатор при выполнении соответствующей проверки.

Подсказки

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

В настоящее время единственная подсказка, которая будет предоставлена, это instance, экземпляр объекта, который связан с операцией чтения или записи, которая выполняется. Это может быть экземпляр, который сохраняется, или это может быть экземпляр, который добавляется в соотношении многие-ко-многим. В некоторых случаях никакая подсказка экземпляра не будет предоставлена вообще. Маршрутизатор проверяет наличие подсказки экземпляра и определяет, следует ли использовать эту подсказку для изменения поведения маршрутизации.

Использование маршрутизаторов

Маршрутизаторы баз данных устанавливаются с помощью параметра DATABASE_ROUTERS. Этот параметр определяет список имен классов, каждый из которых определяет маршрутизатор, который должен использоваться основным маршрутизатором (django.db.router).

Основной маршрутизатор используется операциями с базой данных Django для распределения использования баз данных. Всякий раз, когда запрос должен узнать, какую базу данных использовать, он обращается к основному маршрутизатору, предоставляя модель и подсказку (если она доступна). Затем Django пытается каждый маршрутизатор по очереди, пока не найдет предложение базы данных. Если ни одно предложение не найдено, он попробует текущую _state.db подсказки экземпляра. Если подсказка экземпляра не была предоставлена или у экземпляра в настоящее время нет состояния базы данных, основной маршрутизатор распределит базу данных default.

Пример

Итак, что это значит на практике? Рассмотрим другой пример конфигурации. В этой конфигурации будет несколько баз данных: одна для приложения auth, а все остальные приложения используют настройку «первичный/реплицированный» с двумя репликами для чтения. Вот настройки, определяющие эти базы данных:

DATABASES = {
    'default': {},
    'auth_db': {
        'NAME': 'auth_db',
        'ENGINE': 'django.db.backends.mysql',
        'USER': 'mysql_user',
        'PASSWORD': 'swordfish',
    },
    'primary': {
        'NAME': 'primary',
        'ENGINE': 'django.db.backends.mysql',
        'USER': 'mysql_user',
        'PASSWORD': 'spam',
    },
    'replica1': {
        'NAME': 'replica1',
        'ENGINE': 'django.db.backends.mysql',
        'USER': 'mysql_user',
        'PASSWORD': 'eggs',
    },
    'replica2': {
        'NAME': 'replica2',
        'ENGINE': 'django.db.backends.mysql',
        'USER': 'mysql_user',
        'PASSWORD': 'bacon',
    },
}

Теперь нам нужно обработать маршрутизацию. Сначала мы хотим маршрутизатор, который знает, как отправлять запросы для приложения auth на auth_db:

class AuthRouter(object):
    """
    A router to control all database operations on models in the
    auth application.
    """
    def db_for_read(self, model, **hints):
        """
        Attempts to read auth models go to auth_db.
        """
        if model._meta.app_label == 'auth':
            return 'auth_db'
        return None

    def db_for_write(self, model, **hints):
        """
        Attempts to write auth models go to auth_db.
        """
        if model._meta.app_label == 'auth':
            return 'auth_db'
        return None

    def allow_relation(self, obj1, obj2, **hints):
        """
        Allow relations if a model in the auth app is involved.
        """
        if obj1._meta.app_label == 'auth' or \
           obj2._meta.app_label == 'auth':
           return True
        return None

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        """
        Make sure the auth app only appears in the 'auth_db'
        database.
        """
        if app_label == 'auth':
            return db == 'auth_db'
        return None

И мы также хотим маршрутизатор, который отправляет все остальные приложения в конфигурацию «первичный/реплицированный», и случайным образом выбирает реплику для чтения:

import random

class PrimaryReplicaRouter(object):
    def db_for_read(self, model, **hints):
        """
        Reads go to a randomly-chosen replica.
        """
        return random.choice(['replica1', 'replica2'])

    def db_for_write(self, model, **hints):
        """
        Writes always go to primary.
        """
        return 'primary'

    def allow_relation(self, obj1, obj2, **hints):
        """
        Relations between objects are allowed if both objects are
        in the primary/replica pool.
        """
        db_list = ('primary', 'replica1', 'replica2')
        if obj1._state.db in db_list and obj2._state.db in db_list:
            return True
        return None

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        """
        All non-auth models end up in this pool.
        """
        return True

Наконец, в файле настроек мы добавим следующее (заменив path.to. фактическим путем к модулю(ям) Python, где определены маршрутизаторы):

DATABASE_ROUTERS = ['path.to.AuthRouter', 'path.to.PrimaryReplicaRouter']

Порядок обработки маршрутизаторов важен. Маршрутизаторы будут запрошены в порядке, в котором они перечислены в настройке DATABASE_ROUTERS. В этом примере AuthRouter обрабатывается до PrimaryReplicaRouter, и в результате решения, касающиеся моделей в auth, обрабатываются до принятия любых других решений. Если в настройке DATABASE_ROUTERS два маршрутизатора были перечислены в другом порядке, PrimaryReplicaRouter.allow_migrate() был бы обработан в первую очередь. Всеобъемлющий характер реализации PrimaryReplicaRouter означает, что все модели будут доступны во всех базах данных.

После установки этой настройки давайте запустим некоторый код Django:

>>> # This retrieval will be performed on the 'auth_db' database
>>> fred = User.objects.get(username='fred')
>>> fred.first_name = 'Frederick'

>>> # This save will also be directed to 'auth_db'
>>> fred.save()

>>> # These retrieval will be randomly allocated to a replica database
>>> dna = Person.objects.get(name='Douglas Adams')

>>> # A new object has no database allocation when created
>>> mh = Book(title='Mostly Harmless')

>>> # This assignment will consult the router, and set mh onto
>>> # the same database as the author object
>>> mh.author = dna

>>> # This save will force the 'mh' instance onto the primary database...
>>> mh.save()

>>> # ... but if we re-retrieve the object, it will come back on a replica
>>> mh = Book.objects.get(title='Mostly Harmless')

Ручное выбор базы данных

Django также предоставляет API, который позволяет вам полностью контролировать использование базы данных в вашем коде. Ручное указание базы данных будет иметь приоритет над базой данных, назначенной маршрутизатором.

Ручное выбор базы данных для запроса QuerySet

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

using() принимает один аргумент: псевдоним базы данных, на которой вы хотите выполнить запрос. Например:

>>> # This will run on the 'default' database.
>>> Author.objects.all()

>>> # So will this.
>>> Author.objects.using('default').all()

>>> # This will run on the 'other' database.
>>> Author.objects.using('other').all()

Выбор базы данных для сохранения save()

Используйте ключевое слово using в Model.save() чтобы указать, в какую базу данных следует сохранить данные.

Например, чтобы сохранить объект в базе данных legacy_users, вы бы использовали это:

>>> my_object.save(using='legacy_users')

Если вы не укажете using, метод save() сохранит данные в базу данных по умолчанию, назначенную маршрутизаторами.

Перемещение объекта из одной базы данных в другую

Если вы сохранили экземпляр в одной базе данных, может возникнуть соблазн использовать save(using=...) в качестве способа миграции экземпляра в новую базу данных. Однако, если вы не предпримете соответствующих шагов, это может привести к непредвиденным последствиям.

Рассмотрим следующий пример:

>>> p = Person(name='Fred')
>>> p.save(using='first')  # (statement 1)
>>> p.save(using='second') # (statement 2)

В выражении 1 новый объект Person сохраняется в базе данных first. В этот момент p еще не имеет первичного ключа, поэтому Django выдает SQL INSERT оператор. Это создает первичный ключ, и Django назначает этот первичный ключ p.

При выполнении сохранения в выражении 2 p уже имеет значение первичного ключа, и Django попытается использовать этот первичный ключ в новой базе данных. Если значение первичного ключа не используется в базе данных second, проблем не возникнет — объект будет скопирован в новую базу данных.

Однако, если первичный ключ p уже используется в базе данных second, существующий объект в базе данных second будет перезаписан при сохранении p.

Вы можете избежать этого двумя способами. Во-первых, вы можете очистить первичный ключ экземпляра. Если у объекта нет первичного ключа, Django будет обрабатывать его как новый объект, избегая потери данных в базе данных second:

>>> p = Person(name='Fred')
>>> p.save(using='first')
>>> p.pk = None # Clear the primary key.
>>> p.save(using='second') # Write a completely new object.

Второй вариант заключается в использовании опции force_insert для save(), чтобы гарантировать, что Django выполнит SQL INSERT:

>>> p = Person(name='Fred')
>>> p.save(using='first')
>>> p.save(using='second', force_insert=True)

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

Выбор базы данных для удаления

По умолчанию вызов удаления существующего объекта будет выполнен в той же базе данных, что и была использована для извлечения объекта в первую очередь:

>>> u = User.objects.using('legacy_users').get(username='fred')
>>> u.delete() # will delete from the `legacy_users` database

Чтобы указать базу данных, из которой будет удалена модель, передайте ключевой аргумент using методу Model.delete(). Этот аргумент работает точно так же, как ключевой аргумент using для save().

Например, если вы мигрируете пользователя из базы данных legacy_users в базу данных new_users, вы можете использовать следующие команды:

>>> user_obj.save(using='new_users')
>>> user_obj.delete(using='legacy_users')

Использование менеджеров с несколькими базами данных

Используйте метод db_manager() менеджеров, чтобы предоставить менеджерам доступ к базе данных отличной от базы данных по умолчанию.

Например, предположим, что у вас есть пользовательский метод менеджера, который взаимодействует с базой данных - User.objects.create_user(). Поскольку create_user() - это метод менеджера, а не метод QuerySet, вы не можете выполнить User.objects.using('new_users').create_user(). (Метод create_user() доступен только для User.objects, менеджера, а не для объектов QuerySet производных от менеджера.) Решение заключается в использовании db_manager(), как в этом примере:

User.objects.db_manager('new_users').create_user(...)

db_manager() возвращает копию менеджера, привязанного к указанной базе данных.

Использование get_queryset() с несколькими базами данных

Если вы переопределяете get_queryset() в своем менеджере, обязательно вызывайте метод в родительском классе (используя super()) или выполните соответствующую обработку атрибута _db в менеджере (строка, содержащая имя базы данных для использования).

Например, если вы хотите вернуть пользовательский класс QuerySet из метода get_queryset, вы можете сделать это так:

class MyManager(models.Manager):
    def get_queryset(self):
        qs = CustomQuerySet(self.model)
        if self._db is not None:
            qs = qs.using(self._db)
        return qs

Отображение нескольких баз данных в админском интерфейсе Django

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

Объекты ModelAdmin имеют пять методов, требующих настройки для поддержки нескольких баз данных:

class MultiDBModelAdmin(admin.ModelAdmin):
    # A handy constant for the name of the alternate database.
    using = 'other'

    def save_model(self, request, obj, form, change):
        # Tell Django to save objects to the 'other' database.
        obj.save(using=self.using)

    def delete_model(self, request, obj):
        # Tell Django to delete objects from the 'other' database
        obj.delete(using=self.using)

    def get_queryset(self, request):
        # Tell Django to look for objects on the 'other' database.
        return super(MultiDBModelAdmin, self).get_queryset(request).using(self.using)

    def formfield_for_foreignkey(self, db_field, request=None, **kwargs):
        # Tell Django to populate ForeignKey widgets using a query
        # on the 'other' database.
        return super(MultiDBModelAdmin, self).formfield_for_foreignkey(db_field, request=request, using=self.using, **kwargs)

    def formfield_for_manytomany(self, db_field, request=None, **kwargs):
        # Tell Django to populate ManyToMany widgets using a query
        # on the 'other' database.
        return super(MultiDBModelAdmin, self).formfield_for_manytomany(db_field, request=request, using=self.using, **kwargs)

Здесь реализованная стратегия работы с несколькими базами данных предполагает, что все объекты заданного типа хранятся в определенной базе данных (например, все объекты User находятся в базе данных other). Если ваше использование нескольких баз данных более сложное, ваш ModelAdmin должен отражать эту стратегию.

Обработка вложенных элементов может быть выполнена аналогичным образом. Они требуют трех настраиваемых методов:

class MultiDBTabularInline(admin.TabularInline):
    using = 'other'

    def get_queryset(self, request):
        # Tell Django to look for inline objects on the 'other' database.
        return super(MultiDBTabularInline, self).get_queryset(request).using(self.using)

    def formfield_for_foreignkey(self, db_field, request=None, **kwargs):
        # Tell Django to populate ForeignKey widgets using a query
        # on the 'other' database.
        return super(MultiDBTabularInline, self).formfield_for_foreignkey(db_field, request=request, using=self.using, **kwargs)

    def formfield_for_manytomany(self, db_field, request=None, **kwargs):
        # Tell Django to populate ManyToMany widgets using a query
        # on the 'other' database.
        return super(MultiDBTabularInline, self).formfield_for_manytomany(db_field, request=request, using=self.using, **kwargs)

После написания определений вашего админского управления моделями их можно зарегистрировать с любой Admin экземпляра:

from django.contrib import admin

# Specialize the multi-db admin objects for use with specific models.
class BookInline(MultiDBTabularInline):
    model = Book

class PublisherAdmin(MultiDBModelAdmin):
    inlines = [BookInline]

admin.site.register(Author, MultiDBModelAdmin)
admin.site.register(Publisher, PublisherAdmin)

othersite = admin.AdminSite('othersite')
othersite.register(Publisher, MultiDBModelAdmin)

В этом примере созданы две админские панели. На первой панели отображаются объекты Author и Publisher; объекты Publisher имеют табличную вложенную область, показывающую книги, изданные этим издателем. Вторая панель отображает только издателей без вложенных областей.

Использование необработанных курсоров с несколькими базами данных

Если вы используете более одной базы данных, вы можете использовать django.db.connections для получения соединения (и курсора) для конкретной базы данных. django.db.connections — это объект, похожий на словарь, который позволяет вам получить определенное соединение по его псевдониму:

from django.db import connections
cursor = connections['my_db_alias'].cursor()

Ограничения при использовании нескольких баз данных

Связи между базами данных

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

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

Если вы используете Postgres, Oracle или MySQL с InnoDB, это обеспечивается на уровне целостности базы данных — ограничения ключей на уровне базы данных предотвращают создание связей, которые нельзя проверить.

Однако, если вы используете SQLite или MySQL с таблицами MyISAM, принудительной целостности ссылок нет; в результате вы можете «подделать» внешние ключи между базами данных. Однако такая конфигурация не официально поддерживается Django.

Поведение приложений contrib

Некоторые приложения contrib содержат модели, и некоторые приложения зависят от других. Так как связи между базами данных невозможны, это создает некоторые ограничения на то, как вы можете разделить эти модели между базами данных:

• каждый из contenttypes.ContentType, sessions.Session и sites.Site может храниться в любой базе данных, при условии подходящего маршрутизатора.
• модели auth — User, Group и Permission — связаны друг с другом и с ContentType, поэтому они должны храниться в той же базе данных, что и ContentType.
• модели admin зависят от auth, поэтому их модели должны находиться в той же базе данных, что и auth.
• модели flatpages и redirects зависят от sites, поэтому их модели должны находиться в той же базе данных, что и sites.

Кроме того, некоторые объекты автоматически создаются сразу после того, как migrate создает таблицу для их хранения в базе данных:

• по умолчанию Site,
• для каждой модели (включая те, которые не хранятся в этой базе данных),
• три Permission для каждой модели (включая те, которые не хранятся в этой базе данных).

Для распространённых конфигураций с несколькими базами данных не имеет смысла иметь эти объекты более чем в одной базе данных. Распространённые конфигурации включают первичную/репликационную и подключение к внешним базам данных. Поэтому рекомендуется написать маршрутизатор баз данных, который позволит синхронизировать эти три модели только с одной базой данных. Используйте тот же подход для приложений contrib и сторонних приложений, которым не нужны их таблицы в нескольких базах данных.