TEXT 30
Multi-db.txt Guest on 29th April 2021 06:44:38 AM
  1. ==================
  2. Multiple databases
  3. ==================
  4.  
  5. This topic guide describes Django's support for interacting with
  6. multiple databases. Most of the rest of Django's documentation assumes
  7. you are interacting with a single database. If you want to interact
  8. with multiple databases, you'll need to take some additional steps.
  9.  
  10. Defining your databases
  11. =======================
  12.  
  13. The first step to using more than one database with Django is to tell
  14. Django about the database servers you'll be using. This is done using
  15. the :setting:`DATABASES` setting. This setting maps database aliases,
  16. which are a way to refer to a specific database throughout Django, to
  17. a dictionary of settings for that specific connection. The settings in
  18. the inner dictionaries are described fully in the :setting:`DATABASES`
  19. documentation.
  20.  
  21. Databases can have any alias you choose. However, the alias
  22. ``default`` has special significance. Django uses the database with
  23. the alias of ``default`` when no other database has been selected.
  24.  
  25. The following is an example ``settings.py`` snippet defining two
  26. databases -- a default PostgreSQL database and a MySQL database called
  27. ``users``::
  28.  
  29.     DATABASES = {
  30.         'default': {
  31.             'NAME': 'app_data',
  32.             'ENGINE': 'django.db.backends.postgresql_psycopg2',
  33.             'USER': 'postgres_user',
  34.             'PASSWORD': 's3krit'
  35.         },
  36.         'users': {
  37.             'NAME': 'user_data',
  38.             'ENGINE': 'django.db.backends.mysql',
  39.             'USER': 'mysql_user',
  40.             'PASSWORD': 'priv4te'
  41.         }
  42.     }
  43.  
  44. If the concept of a ``default`` database doesn't make sense in the context
  45. of your project, you need to be careful to always specify the database
  46. that you want to use. Django requires that a ``default`` database entry
  47. be defined, but the parameters dictionary can be left blank if it will not be
  48. used. You must setup :setting:`DATABASE_ROUTERS` for all of your apps' models,
  49. including those in any contrib and third-party apps you are using, so that no
  50. queries are routed to the default database in order to do this. The following
  51. is an example ``settings.py`` snippet defining two non-default databases, with
  52. the ``default`` entry intentionally left empty::
  53.  
  54.     DATABASES = {
  55.         'default': {},
  56.         'users': {
  57.             'NAME': 'user_data',
  58.             'ENGINE': 'django.db.backends.mysql',
  59.             'USER': 'mysql_user',
  60.             'PASSWORD': 'superS3cret'
  61.         },
  62.         'customers': {
  63.             'NAME': 'customer_data',
  64.             'ENGINE': 'django.db.backends.mysql',
  65.             'USER': 'mysql_cust',
  66.             'PASSWORD': 'veryPriv@ate'
  67.         }
  68.     }
  69.  
  70. If you attempt to access a database that you haven't defined in your
  71. :setting:`DATABASES` setting, Django will raise a
  72. ``django.db.utils.ConnectionDoesNotExist`` exception.
  73.  
  74. Synchronizing your databases
  75. ============================
  76.  
  77. The :djadmin:`migrate` management command operates on one database at a
  78. time. By default, it operates on the ``default`` database, but by
  79. providing a :djadminopt:`--database` argument, you can tell :djadmin:`migrate`
  80. to synchronize a different database. So, to synchronize all models onto
  81. all databases in our example, you would need to call::
  82.  
  83.     $ ./manage.py migrate
  84.     $ ./manage.py migrate --database=users
  85.  
  86. If you don't want every application to be synchronized onto a
  87. particular database, you can define a :ref:`database
  88. router<topics-db-multi-db-routing>` that implements a policy
  89. constraining the availability of particular models.
  90.  
  91. Using other management commands
  92. -------------------------------
  93.  
  94. The other ``django-admin`` commands that interact with the database
  95. operate in the same way as :djadmin:`migrate` -- they only ever operate
  96. on one database at a time, using :djadminopt:`--database` to control
  97. the database used.
  98.  
  99. .. _topics-db-multi-db-routing:
  100.  
  101. Automatic database routing
  102. ==========================
  103.  
  104. The easiest way to use multiple databases is to set up a database
  105. routing scheme. The default routing scheme ensures that objects remain
  106. 'sticky' to their original database (i.e., an object retrieved from
  107. the ``foo`` database will be saved on the same database). The default
  108. routing scheme ensures that if a database isn't specified, all queries
  109. fall back to the ``default`` database.
  110.  
  111. You don't have to do anything to activate the default routing scheme
  112. -- it is provided 'out of the box' on every Django project. However,
  113. if you want to implement more interesting database allocation
  114. behaviors, you can define and install your own database routers.
  115.  
  116. Database routers
  117. ----------------
  118.  
  119. A database Router is a class that provides up to four methods:
  120.  
  121. .. method:: db_for_read(model, **hints)
  122.  
  123.     Suggest the database that should be used for read operations for
  124.     objects of type ``model``.
  125.  
  126.     If a database operation is able to provide any additional
  127.     information that might assist in selecting a database, it will be
  128.     provided in the ``hints`` dictionary. Details on valid hints are
  129.     provided :ref:`below <topics-db-multi-db-hints>`.
  130.  
  131.     Returns ``None`` if there is no suggestion.
  132.  
  133. .. method:: db_for_write(model, **hints)
  134.  
  135.     Suggest the database that should be used for writes of objects of
  136.     type Model.
  137.  
  138.     If a database operation is able to provide any additional
  139.     information that might assist in selecting a database, it will be
  140.     provided in the ``hints`` dictionary. Details on valid hints are
  141.     provided :ref:`below <topics-db-multi-db-hints>`.
  142.  
  143.     Returns ``None`` if there is no suggestion.
  144.  
  145. .. method:: allow_relation(obj1, obj2, **hints)
  146.  
  147.     Return ``True`` if a relation between ``obj1`` and ``obj2`` should be
  148.     allowed, ``False`` if the relation should be prevented, or ``None`` if
  149.     the router has no opinion. This is purely a validation operation,
  150.     used by foreign key and many to many operations to determine if a
  151.     relation should be allowed between two objects.
  152.  
  153. .. method:: allow_migrate(db, app_label, model_name=None, **hints)
  154.  
  155.     Determine if the migration operation is allowed to run on the database with
  156.     alias ``db``. Return ``True`` if the operation should run, ``False`` if it
  157.     shouldn't run, or ``None`` if the router has no opinion.
  158.  
  159.     The ``app_label`` positional argument is the label of the application
  160.     being migrated.
  161.  
  162.     ``model_name`` is set by most migration operations to the value of
  163.     ``model._meta.model_name`` (the lowercased version of the model
  164.     ``__name__``) of the model being migrated. Its value is ``None`` for the
  165.     :class:`~django.db.migrations.operations.RunPython` and
  166.     :class:`~django.db.migrations.operations.RunSQL` operations unless they
  167.     provide it using hints.
  168.  
  169.     ``hints`` are used by certain operations to communicate additional
  170.     information to the router.
  171.  
  172.     When ``model_name`` is set, ``hints`` normally contains the model class
  173.     under the key ``'model'``. Note that it may be a :ref:`historical model
  174.     <historical-models>`, and thus not have any custom attributes, methods, or
  175.     managers. You should only rely on ``_meta``.
  176.  
  177.     This method can also be used to determine the availability of a model on a
  178.     given database.
  179.  
  180.     Note that migrations will just silently not perform any operations on a
  181.     model for which this returns ``False``. This may result in broken foreign
  182.     keys, extra tables, or missing tables if you change it once you have
  183.     applied some migrations.
  184.  
  185.     .. versionchanged:: 1.8
  186.  
  187.         The signature of ``allow_migrate`` has changed significantly from previous
  188.         versions. See the :ref:`deprecation notes
  189.         <deprecated-signature-of-allow-migrate>` for more details.
  190.  
  191. A router doesn't have to provide *all* these methods -- it may omit one
  192. or more of them. If one of the methods is omitted, Django will skip
  193. that router when performing the relevant check.
  194.  
  195. .. _topics-db-multi-db-hints:
  196.  
  197. Hints
  198. ~~~~~
  199.  
  200. The hints received by the database router can be used to decide which
  201. database should receive a given request.
  202.  
  203. At present, the only hint that will be provided is ``instance``, an
  204. object instance that is related to the read or write operation that is
  205. underway. This might be the instance that is being saved, or it might
  206. be an instance that is being added in a many-to-many relation. In some
  207. cases, no instance hint will be provided at all. The router checks for
  208. the existence of an instance hint, and determine if that hint should be
  209. used to alter routing behavior.
  210.  
  211. Using routers
  212. -------------
  213.  
  214. Database routers are installed using the :setting:`DATABASE_ROUTERS`
  215. setting. This setting defines a list of class names, each specifying a
  216. router that should be used by the master router
  217. (``django.db.router``).
  218.  
  219. The master router is used by Django's database operations to allocate
  220. database usage. Whenever a query needs to know which database to use,
  221. it calls the master router, providing a model and a hint (if
  222. available). Django then tries each router in turn until a database
  223. suggestion can be found. If no suggestion can be found, it tries the
  224. current ``_state.db`` of the hint instance. If a hint instance wasn't
  225. provided, or the instance doesn't currently have database state, the
  226. master router will allocate the ``default`` database.
  227.  
  228. An example
  229. ----------
  230.  
  231. .. admonition:: Example purposes only!
  232.  
  233.     This example is intended as a demonstration of how the router
  234.     infrastructure can be used to alter database usage. It
  235.     intentionally ignores some complex issues in order to
  236.     demonstrate how routers are used.
  237.  
  238.     This example won't work if any of the models in ``myapp`` contain
  239.     relationships to models outside of the ``other`` database.
  240.     :ref:`Cross-database relationships <no_cross_database_relations>`
  241.     introduce referential integrity problems that Django can't
  242.     currently handle.
  243.  
  244.     The primary/replica (referred to as master/slave by some databases)
  245.     configuration described is also flawed -- it
  246.     doesn't provide any solution for handling replication lag (i.e.,
  247.     query inconsistencies introduced because of the time taken for a
  248.     write to propagate to the replicas). It also doesn't consider the
  249.     interaction of transactions with the database utilization strategy.
  250.  
  251. So - what does this mean in practice? Let's consider another sample
  252. configuration. This one will have several databases: one for the
  253. ``auth`` application, and all other apps using a primary/replica setup
  254. with two read replicas. Here are the settings specifying these
  255. databases::
  256.  
  257.     DATABASES = {
  258.         'auth_db': {
  259.             'NAME': 'auth_db',
  260.             'ENGINE': 'django.db.backends.mysql',
  261.             'USER': 'mysql_user',
  262.             'PASSWORD': 'swordfish',
  263.         },
  264.         'primary': {
  265.             'NAME': 'primary',
  266.             'ENGINE': 'django.db.backends.mysql',
  267.             'USER': 'mysql_user',
  268.             'PASSWORD': 'spam',
  269.         },
  270.         'replica1': {
  271.             'NAME': 'replica1',
  272.             'ENGINE': 'django.db.backends.mysql',
  273.             'USER': 'mysql_user',
  274.             'PASSWORD': 'eggs',
  275.         },
  276.         'replica2': {
  277.             'NAME': 'replica2',
  278.             'ENGINE': 'django.db.backends.mysql',
  279.             'USER': 'mysql_user',
  280.             'PASSWORD': 'bacon',
  281.         },
  282.     }
  283.  
  284. Now we'll need to handle routing. First we want a router that knows to
  285. send queries for the ``auth`` app to ``auth_db``::
  286.  
  287.     class AuthRouter(object):
  288.         """
  289.         A router to control all database operations on models in the
  290.         auth application.
  291.         """
  292.         def db_for_read(self, model, **hints):
  293.             """
  294.             Attempts to read auth models go to auth_db.
  295.             """
  296.             if model._meta.app_label == 'auth':
  297.                 return 'auth_db'
  298.             return None
  299.  
  300.         def db_for_write(self, model, **hints):
  301.             """
  302.             Attempts to write auth models go to auth_db.
  303.             """
  304.             if model._meta.app_label == 'auth':
  305.                 return 'auth_db'
  306.             return None
  307.  
  308.         def allow_relation(self, obj1, obj2, **hints):
  309.             """
  310.             Allow relations if a model in the auth app is involved.
  311.             """
  312.             if obj1._meta.app_label == 'auth' or \
  313.                obj2._meta.app_label == 'auth':
  314.                return True
  315.             return None
  316.  
  317.         def allow_migrate(self, db, app_label, model=None, **hints):
  318.             """
  319.             Make sure the auth app only appears in the 'auth_db'
  320.             database.
  321.             """
  322.             if app_label == 'auth':
  323.                 return db == 'auth_db'
  324.             return None
  325.  
  326. And we also want a router that sends all other apps to the
  327. primary/replica configuration, and randomly chooses a replica to read
  328. from::
  329.  
  330.     import random
  331.  
  332.     class PrimaryReplicaRouter(object):
  333.         def db_for_read(self, model, **hints):
  334.             """
  335.             Reads go to a randomly-chosen replica.
  336.             """
  337.             return random.choice(['replica1', 'replica2'])
  338.  
  339.         def db_for_write(self, model, **hints):
  340.             """
  341.             Writes always go to primary.
  342.             """
  343.             return 'primary'
  344.  
  345.         def allow_relation(self, obj1, obj2, **hints):
  346.             """
  347.             Relations between objects are allowed if both objects are
  348.             in the primary/replica pool.
  349.             """
  350.             db_list = ('primary', 'replica1', 'replica2')
  351.             if obj1._state.db in db_list and obj2._state.db in db_list:
  352.                 return True
  353.             return None
  354.  
  355.         def allow_migrate(self, db, app_label, model=None, **hints):
  356.             """
  357.             All non-auth models end up in this pool.
  358.             """
  359.             return True
  360.  
  361. Finally, in the settings file, we add the following (substituting
  362. ``path.to.`` with the actual python path to the module(s) where the
  363. routers are defined)::
  364.  
  365.     DATABASE_ROUTERS = ['path.to.AuthRouter', 'path.to.PrimaryReplicaRouter']
  366.  
  367. The order in which routers are processed is significant. Routers will
  368. be queried in the order the are listed in the
  369. :setting:`DATABASE_ROUTERS` setting . In this example, the
  370. ``AuthRouter`` is processed before the ``PrimaryReplicaRouter``, and as a
  371. result, decisions concerning the models in ``auth`` are processed
  372. before any other decision is made. If the :setting:`DATABASE_ROUTERS`
  373. setting listed the two routers in the other order,
  374. ``PrimaryReplicaRouter.allow_migrate()`` would be processed first. The
  375. catch-all nature of the PrimaryReplicaRouter implementation would mean
  376. that all models would be available on all databases.
  377.  
  378. With this setup installed, lets run some Django code::
  379.  
  380.     >>> # This retrieval will be performed on the 'auth_db' database
  381.     >>> fred = User.objects.get(username='fred')
  382.     >>> fred.first_name = 'Frederick'
  383.  
  384.     >>> # This save will also be directed to 'auth_db'
  385.     >>> fred.save()
  386.  
  387.     >>> # These retrieval will be randomly allocated to a replica database
  388.     >>> dna = Person.objects.get(name='Douglas Adams')
  389.  
  390.     >>> # A new object has no database allocation when created
  391.     >>> mh = Book(title='Mostly Harmless')
  392.  
  393.     >>> # This assignment will consult the router, and set mh onto
  394.     >>> # the same database as the author object
  395.     >>> mh.author = dna
  396.  
  397.     >>> # This save will force the 'mh' instance onto the primary database...
  398.     >>> mh.save()
  399.  
  400.     >>> # ... but if we re-retrieve the object, it will come back on a replica
  401.     >>> mh = Book.objects.get(title='Mostly Harmless')
  402.  
  403.  
  404. Manually selecting a database
  405. =============================
  406.  
  407. Django also provides an API that allows you to maintain complete control
  408. over database usage in your code. A manually specified database allocation
  409. will take priority over a database allocated by a router.
  410.  
  411. Manually selecting a database for a ``QuerySet``
  412. ------------------------------------------------
  413.  
  414. You can select the database for a ``QuerySet`` at any point in the
  415. ``QuerySet`` "chain." Just call ``using()`` on the ``QuerySet`` to get
  416. another ``QuerySet`` that uses the specified database.
  417.  
  418. ``using()`` takes a single argument: the alias of the database on
  419. which you want to run the query. For example::
  420.  
  421.     >>> # This will run on the 'default' database.
  422.     >>> Author.objects.all()
  423.  
  424.     >>> # So will this.
  425.     >>> Author.objects.using('default').all()
  426.  
  427.     >>> # This will run on the 'other' database.
  428.     >>> Author.objects.using('other').all()
  429.  
  430. Selecting a database for ``save()``
  431. -----------------------------------
  432.  
  433. Use the ``using`` keyword to ``Model.save()`` to specify to which
  434. database the data should be saved.
  435.  
  436. For example, to save an object to the ``legacy_users`` database, you'd
  437. use this::
  438.  
  439.     >>> my_object.save(using='legacy_users')
  440.  
  441. If you don't specify ``using``, the ``save()`` method will save into
  442. the default database allocated by the routers.
  443.  
  444. Moving an object from one database to another
  445. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  446.  
  447. If you've saved an instance to one database, it might be tempting to
  448. use ``save(using=...)`` as a way to migrate the instance to a new
  449. database. However, if you don't take appropriate steps, this could
  450. have some unexpected consequences.
  451.  
  452. Consider the following example::
  453.  
  454.     >>> p = Person(name='Fred')
  455.     >>> p.save(using='first')  # (statement 1)
  456.     >>> p.save(using='second') # (statement 2)
  457.  
  458. In statement 1, a new ``Person`` object is saved to the ``first``
  459. database. At this time, ``p`` doesn't have a primary key, so Django
  460. issues an SQL ``INSERT`` statement. This creates a primary key, and
  461. Django assigns that primary key to ``p``.
  462.  
  463. When the save occurs in statement 2, ``p`` already has a primary key
  464. value, and Django will attempt to use that primary key on the new
  465. database. If the primary key value isn't in use in the ``second``
  466. database, then you won't have any problems -- the object will be
  467. copied to the new database.
  468.  
  469. However, if the primary key of ``p`` is already in use on the
  470. ``second`` database, the existing object in the ``second`` database
  471. will be overridden when ``p`` is saved.
  472.  
  473. You can avoid this in two ways. First, you can clear the primary key
  474. of the instance. If an object has no primary key, Django will treat it
  475. as a new object, avoiding any loss of data on the ``second``
  476. database::
  477.  
  478.     >>> p = Person(name='Fred')
  479.     >>> p.save(using='first')
  480.     >>> p.pk = None # Clear the primary key.
  481.     >>> p.save(using='second') # Write a completely new object.
  482.  
  483. The second option is to use the ``force_insert`` option to ``save()``
  484. to ensure that Django does an SQL ``INSERT``::
  485.  
  486.     >>> p = Person(name='Fred')
  487.     >>> p.save(using='first')
  488.     >>> p.save(using='second', force_insert=True)
  489.  
  490. This will ensure that the person named ``Fred`` will have the same
  491. primary key on both databases. If that primary key is already in use
  492. when you try to save onto the ``second`` database, an error will be
  493. raised.
  494.  
  495. Selecting a database to delete from
  496. -----------------------------------
  497.  
  498. By default, a call to delete an existing object will be executed on
  499. the same database that was used to retrieve the object in the first
  500. place::
  501.  
  502.     >>> u = User.objects.using('legacy_users').get(username='fred')
  503.     >>> u.delete() # will delete from the `legacy_users` database
  504.  
  505. To specify the database from which a model will be deleted, pass a
  506. ``using`` keyword argument to the ``Model.delete()`` method. This
  507. argument works just like the ``using`` keyword argument to ``save()``.
  508.  
  509. For example, if you're migrating a user from the ``legacy_users``
  510. database to the ``new_users`` database, you might use these commands::
  511.  
  512.     >>> user_obj.save(using='new_users')
  513.     >>> user_obj.delete(using='legacy_users')
  514.  
  515. Using managers with multiple databases
  516. --------------------------------------
  517.  
  518. Use the ``db_manager()`` method on managers to give managers access to
  519. a non-default database.
  520.  
  521. For example, say you have a custom manager method that touches the
  522. database -- ``User.objects.create_user()``. Because ``create_user()``
  523. is a manager method, not a ``QuerySet`` method, you can't do
  524. ``User.objects.using('new_users').create_user()``. (The
  525. ``create_user()`` method is only available on ``User.objects``, the
  526. manager, not on ``QuerySet`` objects derived from the manager.) The
  527. solution is to use ``db_manager()``, like this::
  528.  
  529.     User.objects.db_manager('new_users').create_user(...)
  530.  
  531. ``db_manager()`` returns a copy of the manager bound to the database you specify.
  532.  
  533. Using ``get_queryset()`` with multiple databases
  534. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  535.  
  536. If you're overriding ``get_queryset()`` on your manager, be sure to
  537. either call the method on the parent (using ``super()``) or do the
  538. appropriate handling of the ``_db`` attribute on the manager (a string
  539. containing the name of the database to use).
  540.  
  541. For example, if you want to return a custom ``QuerySet`` class from
  542. the ``get_queryset`` method, you could do this::
  543.  
  544.     class MyManager(models.Manager):
  545.         def get_queryset(self):
  546.             qs = CustomQuerySet(self.model)
  547.             if self._db is not None:
  548.                 qs = qs.using(self._db)
  549.             return qs
  550.  
  551. Exposing multiple databases in Django's admin interface
  552. =======================================================
  553.  
  554. Django's admin doesn't have any explicit support for multiple
  555. databases. If you want to provide an admin interface for a model on a
  556. database other than that specified by your router chain, you'll
  557. need to write custom :class:`~django.contrib.admin.ModelAdmin` classes
  558. that will direct the admin to use a specific database for content.
  559.  
  560. ``ModelAdmin`` objects have five methods that require customization for
  561. multiple-database support::
  562.  
  563.     class MultiDBModelAdmin(admin.ModelAdmin):
  564.         # A handy constant for the name of the alternate database.
  565.         using = 'other'
  566.  
  567.         def save_model(self, request, obj, form, change):
  568.             # Tell Django to save objects to the 'other' database.
  569.             obj.save(using=self.using)
  570.  
  571.         def delete_model(self, request, obj):
  572.             # Tell Django to delete objects from the 'other' database
  573.             obj.delete(using=self.using)
  574.  
  575.         def get_queryset(self, request):
  576.             # Tell Django to look for objects on the 'other' database.
  577.             return super(MultiDBModelAdmin, self).get_queryset(request).using(self.using)
  578.  
  579.         def formfield_for_foreignkey(self, db_field, request=None, **kwargs):
  580.             # Tell Django to populate ForeignKey widgets using a query
  581.             # on the 'other' database.
  582.             return super(MultiDBModelAdmin, self).formfield_for_foreignkey(db_field, request=request, using=self.using, **kwargs)
  583.  
  584.         def formfield_for_manytomany(self, db_field, request=None, **kwargs):
  585.             # Tell Django to populate ManyToMany widgets using a query
  586.             # on the 'other' database.
  587.             return super(MultiDBModelAdmin, self).formfield_for_manytomany(db_field, request=request, using=self.using, **kwargs)
  588.  
  589. The implementation provided here implements a multi-database strategy
  590. where all objects of a given type are stored on a specific database
  591. (e.g., all ``User`` objects are in the ``other`` database). If your
  592. usage of multiple databases is more complex, your ``ModelAdmin`` will
  593. need to reflect that strategy.
  594.  
  595. Inlines can be handled in a similar fashion. They require three customized methods::
  596.  
  597.     class MultiDBTabularInline(admin.TabularInline):
  598.         using = 'other'
  599.  
  600.         def get_queryset(self, request):
  601.             # Tell Django to look for inline objects on the 'other' database.
  602.             return super(MultiDBTabularInline, self).get_queryset(request).using(self.using)
  603.  
  604.         def formfield_for_foreignkey(self, db_field, request=None, **kwargs):
  605.             # Tell Django to populate ForeignKey widgets using a query
  606.             # on the 'other' database.
  607.             return super(MultiDBTabularInline, self).formfield_for_foreignkey(db_field, request=request, using=self.using, **kwargs)
  608.  
  609.         def formfield_for_manytomany(self, db_field, request=None, **kwargs):
  610.             # Tell Django to populate ManyToMany widgets using a query
  611.             # on the 'other' database.
  612.             return super(MultiDBTabularInline, self).formfield_for_manytomany(db_field, request=request, using=self.using, **kwargs)
  613.  
  614. Once you've written your model admin definitions, they can be
  615. registered with any ``Admin`` instance::
  616.  
  617.     from django.contrib import admin
  618.  
  619.     # Specialize the multi-db admin objects for use with specific models.
  620.     class BookInline(MultiDBTabularInline):
  621.         model = Book
  622.  
  623.     class PublisherAdmin(MultiDBModelAdmin):
  624.         inlines = [BookInline]
  625.  
  626.     admin.site.register(Author, MultiDBModelAdmin)
  627.     admin.site.register(Publisher, PublisherAdmin)
  628.  
  629.     othersite = admin.AdminSite('othersite')
  630.     othersite.register(Publisher, MultiDBModelAdmin)
  631.  
  632. This example sets up two admin sites. On the first site, the
  633. ``Author`` and ``Publisher`` objects are exposed; ``Publisher``
  634. objects have an tabular inline showing books published by that
  635. publisher. The second site exposes just publishers, without the
  636. inlines.
  637.  
  638. Using raw cursors with multiple databases
  639. =========================================
  640.  
  641. If you are using more than one database you can use
  642. ``django.db.connections`` to obtain the connection (and cursor) for a
  643. specific database. ``django.db.connections`` is a dictionary-like
  644. object that allows you to retrieve a specific connection using its
  645. alias::
  646.  
  647.     from django.db import connections
  648.     cursor = connections['my_db_alias'].cursor()
  649.  
  650. Limitations of multiple databases
  651. =================================
  652.  
  653. .. _no_cross_database_relations:
  654.  
  655. Cross-database relations
  656. ------------------------
  657.  
  658. Django doesn't currently provide any support for foreign key or
  659. many-to-many relationships spanning multiple databases. If you
  660. have used a router to partition models to different databases,
  661. any foreign key and many-to-many relationships defined by those
  662. models must be internal to a single database.
  663.  
  664. This is because of referential integrity. In order to maintain a
  665. relationship between two objects, Django needs to know that the
  666. primary key of the related object is valid. If the primary key is
  667. stored on a separate database, it's not possible to easily evaluate
  668. the validity of a primary key.
  669.  
  670. If you're using Postgres, Oracle, or MySQL with InnoDB, this is
  671. enforced at the database integrity level -- database level key
  672. constraints prevent the creation of relations that can't be validated.
  673.  
  674. However, if you're using SQLite or MySQL with MyISAM tables, there is
  675. no enforced referential integrity; as a result, you may be able to
  676. 'fake' cross database foreign keys. However, this configuration is not
  677. officially supported by Django.
  678.  
  679. .. _contrib_app_multiple_databases:
  680.  
  681. Behavior of contrib apps
  682. ------------------------
  683.  
  684. Several contrib apps include models, and some apps depend on others. Since
  685. cross-database relationships are impossible, this creates some restrictions on
  686. how you can split these models across databases:
  687.  
  688. - each one of ``contenttypes.ContentType``, ``sessions.Session`` and
  689.   ``sites.Site`` can be stored in any database, given a suitable router.
  690. - ``auth`` models — ``User``, ``Group`` and ``Permission`` — are linked
  691.   together and linked to ``ContentType``, so they must be stored in the same
  692.   database as ``ContentType``.
  693. - ``admin`` depends on ``auth``, so their models must be in the same database
  694.   as ``auth``.
  695. - ``flatpages`` and ``redirects`` depend on ``sites``, so their models must be
  696.   in the same database as ``sites``.
  697.  
  698. In addition, some objects are automatically created just after
  699. :djadmin:`migrate` creates a table to hold them in a database:
  700.  
  701. - a default ``Site``,
  702. - a ``ContentType`` for each model (including those not stored in that
  703.   database),
  704. - three ``Permission`` for each model (including those not stored in that
  705.   database).
  706.  
  707. For common setups with multiple databases, it isn't useful to have these
  708. objects in more than one database. Common setups include primary/replica and
  709. connecting to external databases. Therefore, it's recommended to write a
  710. :ref:`database router<topics-db-multi-db-routing>` that allows synchronizing
  711. these three models to only one database. Use the same approach for contrib
  712. and third-party apps that don't need their tables in multiple databases.
  713.  
  714. .. warning::
  715.  
  716.     If you're synchronizing content types to more than one database, be aware
  717.     that their primary keys may not match across databases. This may result in
  718.     data corruption or

Paste-bin is for source code and general debugging text.

Login or Register to edit, delete and keep track of your pastes and more.

Raw Paste

Login or Register to edit or fork this paste. It's free.