This topic guide describes Django’s support for interacting with\nmultiple databases. Most of the rest of Django’s documentation assumes\nyou are interacting with a single database. If you want to interact\nwith multiple databases, you’ll need to take some additional steps.
\n\nThe first step to using more than one database with Django is to tell\nDjango about the database servers you’ll be using. This is done using\nthe DATABASES setting. This setting maps database aliases,\nwhich are a way to refer to a specific database throughout Django, to\na dictionary of settings for that specific connection. The settings in\nthe inner dictionaries are described fully in the DATABASES\ndocumentation.
Databases can have any alias you choose. However, the alias\ndefault has special significance. Django uses the database with\nthe alias of default when no other database has been selected.
The following is an example settings.py snippet defining two\ndatabases – a default PostgreSQL database and a MySQL database called\nusers:
DATABASES = {\n 'default': {\n 'NAME': 'app_data',\n 'ENGINE': 'django.db.backends.postgresql',\n 'USER': 'postgres_user',\n 'PASSWORD': 's3krit'\n },\n 'users': {\n 'NAME': 'user_data',\n 'ENGINE': 'django.db.backends.mysql',\n 'USER': 'mysql_user',\n 'PASSWORD': 'priv4te'\n }\n}\nIf the concept of a default database doesn’t make sense in the context\nof your project, you need to be careful to always specify the database\nthat you want to use. Django requires that a default database entry\nbe defined, but the parameters dictionary can be left blank if it will not be\nused. To do this, you must set up DATABASE_ROUTERS for all of your\napps’ models, including those in any contrib and third-party apps you’re using,\nso that no queries are routed to the default database. The following is an\nexample settings.py snippet defining two non-default databases, with the\ndefault entry intentionally left empty:
DATABASES = {\n 'default': {},\n 'users': {\n 'NAME': 'user_data',\n 'ENGINE': 'django.db.backends.mysql',\n 'USER': 'mysql_user',\n 'PASSWORD': 'superS3cret'\n },\n 'customers': {\n 'NAME': 'customer_data',\n 'ENGINE': 'django.db.backends.mysql',\n 'USER': 'mysql_cust',\n 'PASSWORD': 'veryPriv@ate'\n }\n}\nIf you attempt to access a database that you haven’t defined in your\nDATABASES setting, Django will raise a\ndjango.utils.connection.ConnectionDoesNotExist exception.
The migrate management command operates on one database at a\ntime. By default, it operates on the default database, but by\nproviding the --database option, you can tell it\nto synchronize a different database. So, to synchronize all models onto\nall databases in the first example above, you would need to call:
$ ./manage.py migrate\n$ ./manage.py migrate --database=users\nIf you don’t want every application to be synchronized onto a\nparticular database, you can define a database\nrouter that implements a policy\nconstraining the availability of particular models.
\nIf, as in the second example above, you’ve left the default database empty,\nyou must provide a database name each time you run migrate. Omitting\nthe database name would raise an error. For the second example:
$ ./manage.py migrate --database=users\n$ ./manage.py migrate --database=customers\nMost other django-admin commands that interact with the database operate in\nthe same way as migrate – they only ever operate on one database at\na time, using --database to control the database used.
An exception to this rule is the makemigrations command. It\nvalidates the migration history in the databases to catch problems with the\nexisting migration files (which could be caused by editing them) before\ncreating new migrations. By default, it checks only the default database,\nbut it consults the allow_migrate() method of routers if any are installed.
The easiest way to use multiple databases is to set up a database\nrouting scheme. The default routing scheme ensures that objects remain\n‘sticky’ to their original database (i.e., an object retrieved from\nthe foo database will be saved on the same database). The default\nrouting scheme ensures that if a database isn’t specified, all queries\nfall back to the default database.
You don’t have to do anything to activate the default routing scheme\n– it is provided ‘out of the box’ on every Django project. However,\nif you want to implement more interesting database allocation\nbehaviors, you can define and install your own database routers.
\nA database Router is a class that provides up to four methods:
\nSuggest the database that should be used for read operations for\nobjects of type model.
If a database operation is able to provide any additional\ninformation that might assist in selecting a database, it will be\nprovided in the hints dictionary. Details on valid hints are\nprovided below.
어떤 제안도 없으면 “None”을 반환합니다.
\nSuggest the database that should be used for writes of objects of\ntype Model.
\nIf a database operation is able to provide any additional\ninformation that might assist in selecting a database, it will be\nprovided in the hints dictionary. Details on valid hints are\nprovided below.
어떤 제안도 없으면 “None”을 반환합니다.
\nReturn True if a relation between obj1 and obj2 should be\nallowed, False if the relation should be prevented, or None if\nthe router has no opinion. This is purely a validation operation,\nused by foreign key and many to many operations to determine if a\nrelation should be allowed between two objects.
If no router has an opinion (i.e. all routers return None), only\nrelations within the same database are allowed.
Determine if the migration operation is allowed to run on the database with\nalias db. Return True if the operation should run, False if it\nshouldn’t run, or None if the router has no opinion.
The app_label positional argument is the label of the application\nbeing migrated.
model_name is set by most migration operations to the value of\nmodel._meta.model_name (the lowercased version of the model\n__name__) of the model being migrated. Its value is None for the\nRunPython and\nRunSQL operations unless they\nprovide it using hints.
hints are used by certain operations to communicate additional\ninformation to the router.
When model_name is set, hints normally contains the model class\nunder the key 'model'. Note that it may be a historical model, and thus not have any custom attributes, methods, or\nmanagers. You should only rely on _meta.
This method can also be used to determine the availability of a model on a\ngiven database.
\nmakemigrations always creates migrations for model changes, but\nif allow_migrate() returns False, any migration operations for the\nmodel_name will be silently skipped when running migrate on\nthe db. Changing the behavior of allow_migrate() for models that\nalready have migrations may result in broken foreign keys, extra tables,\nor missing tables. When makemigrations verifies the migration\nhistory, it skips databases where no app is allowed to migrate.
A router doesn’t have to provide all these methods – it may omit one\nor more of them. If one of the methods is omitted, Django will skip\nthat router when performing the relevant check.
\nThe hints received by the database router can be used to decide which\ndatabase should receive a given request.
\nAt present, the only hint that will be provided is instance, an\nobject instance that is related to the read or write operation that is\nunderway. This might be the instance that is being saved, or it might\nbe an instance that is being added in a many-to-many relation. In some\ncases, no instance hint will be provided at all. The router checks for\nthe existence of an instance hint, and determine if that hint should be\nused to alter routing behavior.
Database routers are installed using the DATABASE_ROUTERS\nsetting. This setting defines a list of class names, each specifying a\nrouter that should be used by the master router\n(django.db.router).
The master router is used by Django’s database operations to allocate\ndatabase usage. Whenever a query needs to know which database to use,\nit calls the master router, providing a model and a hint (if\navailable). Django then tries each router in turn until a database\nsuggestion can be found. If no suggestion can be found, it tries the\ncurrent instance._state.db of the hint\ninstance. If a hint instance wasn’t provided, or instance._state.db is None, the master router will allocate\nthe default database.
So - what does this mean in practice? Let’s consider another sample\nconfiguration. This one will have several databases: one for the\nauth application, and all other apps using a primary/replica setup\nwith two read replicas. Here are the settings specifying these\ndatabases:
DATABASES = {\n 'default': {},\n 'auth_db': {\n 'NAME': 'auth_db_name',\n 'ENGINE': 'django.db.backends.mysql',\n 'USER': 'mysql_user',\n 'PASSWORD': 'swordfish',\n },\n 'primary': {\n 'NAME': 'primary_name',\n 'ENGINE': 'django.db.backends.mysql',\n 'USER': 'mysql_user',\n 'PASSWORD': 'spam',\n },\n 'replica1': {\n 'NAME': 'replica1_name',\n 'ENGINE': 'django.db.backends.mysql',\n 'USER': 'mysql_user',\n 'PASSWORD': 'eggs',\n },\n 'replica2': {\n 'NAME': 'replica2_name',\n 'ENGINE': 'django.db.backends.mysql',\n 'USER': 'mysql_user',\n 'PASSWORD': 'bacon',\n },\n}\nNow we’ll need to handle routing. First we want a router that knows to\nsend queries for the auth and contenttypes apps to auth_db\n(auth models are linked to ContentType, so they must be stored in the\nsame database):
class AuthRouter:\n """\n A router to control all database operations on models in the\n auth and contenttypes applications.\n """\n route_app_labels = {'auth', 'contenttypes'}\n\n def db_for_read(self, model, **hints):\n """\n Attempts to read auth and contenttypes models go to auth_db.\n """\n if model._meta.app_label in self.route_app_labels:\n return 'auth_db'\n return None\n\n def db_for_write(self, model, **hints):\n """\n Attempts to write auth and contenttypes models go to auth_db.\n """\n if model._meta.app_label in self.route_app_labels:\n return 'auth_db'\n return None\n\n def allow_relation(self, obj1, obj2, **hints):\n """\n Allow relations if a model in the auth or contenttypes apps is\n involved.\n """\n if (\n obj1._meta.app_label in self.route_app_labels or\n obj2._meta.app_label in self.route_app_labels\n ):\n return True\n return None\n\n def allow_migrate(self, db, app_label, model_name=None, **hints):\n """\n Make sure the auth and contenttypes apps only appear in the\n 'auth_db' database.\n """\n if app_label in self.route_app_labels:\n return db == 'auth_db'\n return None\nAnd we also want a router that sends all other apps to the\nprimary/replica configuration, and randomly chooses a replica to read\nfrom:
\nimport random\n\nclass PrimaryReplicaRouter:\n def db_for_read(self, model, **hints):\n """\n Reads go to a randomly-chosen replica.\n """\n return random.choice(['replica1', 'replica2'])\n\n def db_for_write(self, model, **hints):\n """\n Writes always go to primary.\n """\n return 'primary'\n\n def allow_relation(self, obj1, obj2, **hints):\n """\n Relations between objects are allowed if both objects are\n in the primary/replica pool.\n """\n db_set = {'primary', 'replica1', 'replica2'}\n if obj1._state.db in db_set and obj2._state.db in db_set:\n return True\n return None\n\n def allow_migrate(self, db, app_label, model_name=None, **hints):\n """\n All non-auth models end up in this pool.\n """\n return True\nFinally, in the settings file, we add the following (substituting\npath.to. with the actual Python path to the module(s) where the\nrouters are defined):
DATABASE_ROUTERS = ['path.to.AuthRouter', 'path.to.PrimaryReplicaRouter']\nThe order in which routers are processed is significant. Routers will\nbe queried in the order they are listed in the\nDATABASE_ROUTERS setting. In this example, the\nAuthRouter is processed before the PrimaryReplicaRouter, and as a\nresult, decisions concerning the models in auth are processed\nbefore any other decision is made. If the DATABASE_ROUTERS\nsetting listed the two routers in the other order,\nPrimaryReplicaRouter.allow_migrate() would be processed first. The\ncatch-all nature of the PrimaryReplicaRouter implementation would mean\nthat all models would be available on all databases.
With this setup installed, and all databases migrated as per\n데이터베이스 연동, lets run some Django code:
\n>>> # This retrieval will be performed on the 'auth_db' database\n>>> fred = User.objects.get(username='fred')\n>>> fred.first_name = 'Frederick'\n\n>>> # This save will also be directed to 'auth_db'\n>>> fred.save()\n\n>>> # These retrieval will be randomly allocated to a replica database\n>>> dna = Person.objects.get(name='Douglas Adams')\n\n>>> # A new object has no database allocation when created\n>>> mh = Book(title='Mostly Harmless')\n\n>>> # This assignment will consult the router, and set mh onto\n>>> # the same database as the author object\n>>> mh.author = dna\n\n>>> # This save will force the 'mh' instance onto the primary database...\n>>> mh.save()\n\n>>> # ... but if we re-retrieve the object, it will come back on a replica\n>>> mh = Book.objects.get(title='Mostly Harmless')\nThis example defined a router to handle interaction with models from the\nauth app, and other routers to handle interaction with all other apps. If\nyou left your default database empty and don’t want to define a catch-all\ndatabase router to handle all apps not otherwise specified, your routers must\nhandle the names of all apps in INSTALLED_APPS before you migrate.\nSee Behavior of contrib apps for information about contrib apps\nthat must be together in one database.
Django also provides an API that allows you to maintain complete control\nover database usage in your code. A manually specified database allocation\nwill take priority over a database allocated by a router.
\nYou can select the database for a QuerySet at any point in the\nQuerySet “chain.” Call using() on the QuerySet to get another\nQuerySet that uses the specified database.
using() takes a single argument: the alias of the database on\nwhich you want to run the query. For example:
>>> # This will run on the 'default' database.\n>>> Author.objects.all()\n\n>>> # So will this.\n>>> Author.objects.using('default').all()\n\n>>> # This will run on the 'other' database.\n>>> Author.objects.using('other').all()\nsave()Link to this heading#Use the using keyword to Model.save() to specify to which\ndatabase the data should be saved.
For example, to save an object to the legacy_users database, you’d\nuse this:
>>> my_object.save(using='legacy_users')\nIf you don’t specify using, the save() method will save into\nthe default database allocated by the routers.
If you’ve saved an instance to one database, it might be tempting to\nuse save(using=...) as a way to migrate the instance to a new\ndatabase. However, if you don’t take appropriate steps, this could\nhave some unexpected consequences.
다음 예제를 참고하세요:
\n>>> p = Person(name='Fred')\n>>> p.save(using='first') # (statement 1)\n>>> p.save(using='second') # (statement 2)\nIn statement 1, a new Person object is saved to the first\ndatabase. At this time, p doesn’t have a primary key, so Django\nissues an SQL INSERT statement. This creates a primary key, and\nDjango assigns that primary key to p.
When the save occurs in statement 2, p already has a primary key\nvalue, and Django will attempt to use that primary key on the new\ndatabase. If the primary key value isn’t in use in the second\ndatabase, then you won’t have any problems – the object will be\ncopied to the new database.
However, if the primary key of p is already in use on the\nsecond database, the existing object in the second database\nwill be overridden when p is saved.
You can avoid this in two ways. First, you can clear the primary key\nof the instance. If an object has no primary key, Django will treat it\nas a new object, avoiding any loss of data on the second\ndatabase:
>>> p = Person(name='Fred')\n>>> p.save(using='first')\n>>> p.pk = None # Clear the primary key.\n>>> p.save(using='second') # Write a completely new object.\nThe second option is to use the force_insert option to save()\nto ensure that Django does an SQL INSERT:
>>> p = Person(name='Fred')\n>>> p.save(using='first')\n>>> p.save(using='second', force_insert=True)\nThis will ensure that the person named Fred will have the same\nprimary key on both databases. If that primary key is already in use\nwhen you try to save onto the second database, an error will be\nraised.
By default, a call to delete an existing object will be executed on\nthe same database that was used to retrieve the object in the first\nplace:
\n>>> u = User.objects.using('legacy_users').get(username='fred')\n>>> u.delete() # will delete from the `legacy_users` database\nTo specify the database from which a model will be deleted, pass a\nusing keyword argument to the Model.delete() method. This\nargument works just like the using keyword argument to save().
For example, if you’re migrating a user from the legacy_users\ndatabase to the new_users database, you might use these commands:
>>> user_obj.save(using='new_users')\n>>> user_obj.delete(using='legacy_users')\nUse the db_manager() method on managers to give managers access to\na non-default database.
For example, say you have a custom manager method that touches the\ndatabase – User.objects.create_user(). Because create_user()\nis a manager method, not a QuerySet method, you can’t do\nUser.objects.using('new_users').create_user(). (The\ncreate_user() method is only available on User.objects, the\nmanager, not on QuerySet objects derived from the manager.) The\nsolution is to use db_manager(), like this:
User.objects.db_manager('new_users').create_user(...)\ndb_manager() returns a copy of the manager bound to the database you specify.
get_queryset() with multiple databasesLink to this heading#If you’re overriding get_queryset() on your manager, be sure to\neither call the method on the parent (using super()) or do the\nappropriate handling of the _db attribute on the manager (a string\ncontaining the name of the database to use).
For example, if you want to return a custom QuerySet class from\nthe get_queryset method, you could do this:
class MyManager(models.Manager):\n def get_queryset(self):\n qs = CustomQuerySet(self.model)\n if self._db is not None:\n qs = qs.using(self._db)\n return qs\nDjango’s admin doesn’t have any explicit support for multiple\ndatabases. If you want to provide an admin interface for a model on a\ndatabase other than that specified by your router chain, you’ll\nneed to write custom ModelAdmin classes\nthat will direct the admin to use a specific database for content.
ModelAdmin objects have five methods that require customization for\nmultiple-database support:
class MultiDBModelAdmin(admin.ModelAdmin):\n # A handy constant for the name of the alternate database.\n using = 'other'\n\n def save_model(self, request, obj, form, change):\n # Tell Django to save objects to the 'other' database.\n obj.save(using=self.using)\n\n def delete_model(self, request, obj):\n # Tell Django to delete objects from the 'other' database\n obj.delete(using=self.using)\n\n def get_queryset(self, request):\n # Tell Django to look for objects on the 'other' database.\n return super().get_queryset(request).using(self.using)\n\n def formfield_for_foreignkey(self, db_field, request, **kwargs):\n # Tell Django to populate ForeignKey widgets using a query\n # on the 'other' database.\n return super().formfield_for_foreignkey(db_field, request, using=self.using, **kwargs)\n\n def formfield_for_manytomany(self, db_field, request, **kwargs):\n # Tell Django to populate ManyToMany widgets using a query\n # on the 'other' database.\n return super().formfield_for_manytomany(db_field, request, using=self.using, **kwargs)\nThe implementation provided here implements a multi-database strategy\nwhere all objects of a given type are stored on a specific database\n(e.g., all User objects are in the other database). If your\nusage of multiple databases is more complex, your ModelAdmin will\nneed to reflect that strategy.
InlineModelAdmin objects can be handled in a\nsimilar fashion. They require three customized methods:
class MultiDBTabularInline(admin.TabularInline):\n using = 'other'\n\n def get_queryset(self, request):\n # Tell Django to look for inline objects on the 'other' database.\n return super().get_queryset(request).using(self.using)\n\n def formfield_for_foreignkey(self, db_field, request, **kwargs):\n # Tell Django to populate ForeignKey widgets using a query\n # on the 'other' database.\n return super().formfield_for_foreignkey(db_field, request, using=self.using, **kwargs)\n\n def formfield_for_manytomany(self, db_field, request, **kwargs):\n # Tell Django to populate ManyToMany widgets using a query\n # on the 'other' database.\n return super().formfield_for_manytomany(db_field, request, using=self.using, **kwargs)\nOnce you’ve written your model admin definitions, they can be\nregistered with any Admin instance:
from django.contrib import admin\n\n# Specialize the multi-db admin objects for use with specific models.\nclass BookInline(MultiDBTabularInline):\n model = Book\n\nclass PublisherAdmin(MultiDBModelAdmin):\n inlines = [BookInline]\n\nadmin.site.register(Author, MultiDBModelAdmin)\nadmin.site.register(Publisher, PublisherAdmin)\n\nothersite = admin.AdminSite('othersite')\nothersite.register(Publisher, MultiDBModelAdmin)\nThis example sets up two admin sites. On the first site, the\nAuthor and Publisher objects are exposed; Publisher\nobjects have a tabular inline showing books published by that\npublisher. The second site exposes just publishers, without the\ninlines.
If you are using more than one database you can use\ndjango.db.connections to obtain the connection (and cursor) for a\nspecific database. django.db.connections is a dictionary-like\nobject that allows you to retrieve a specific connection using its\nalias:
from django.db import connections\nwith connections['my_db_alias'].cursor() as cursor:\n ...\nDjango doesn’t currently provide any support for foreign key or\nmany-to-many relationships spanning multiple databases. If you\nhave used a router to partition models to different databases,\nany foreign key and many-to-many relationships defined by those\nmodels must be internal to a single database.
\nThis is because of referential integrity. In order to maintain a\nrelationship between two objects, Django needs to know that the\nprimary key of the related object is valid. If the primary key is\nstored on a separate database, it’s not possible to easily evaluate\nthe validity of a primary key.
\nIf you’re using Postgres, Oracle, or MySQL with InnoDB, this is\nenforced at the database integrity level – database level key\nconstraints prevent the creation of relations that can’t be validated.
\nHowever, if you’re using SQLite or MySQL with MyISAM tables, there is\nno enforced referential integrity; as a result, you may be able to\n‘fake’ cross database foreign keys. However, this configuration is not\nofficially supported by Django.
\nSeveral contrib apps include models, and some apps depend on others. Since\ncross-database relationships are impossible, this creates some restrictions on\nhow you can split these models across databases:
\neach one of contenttypes.ContentType, sessions.Session and\nsites.Site can be stored in any database, given a suitable router.
auth models — User, Group and Permission — are linked\ntogether and linked to ContentType, so they must be stored in the same\ndatabase as ContentType.
admin depends on auth, so its models must be in the same database\nas auth.
flatpages and redirects depend on sites, so their models must be\nin the same database as sites.
In addition, some objects are automatically created just after\nmigrate creates a table to hold them in a database:
a default Site,
a ContentType for each model (including those not stored in that\ndatabase),
the Permissions for each model (including those not stored in that\ndatabase).
For common setups with multiple databases, it isn’t useful to have these\nobjects in more than one database. Common setups include primary/replica and\nconnecting to external databases. Therefore, it’s recommended to write a\ndatabase router that allows synchronizing\nthese three models to only one database. Use the same approach for contrib\nand third-party apps that don’t need their tables in multiple databases.
\n\n