== Multiple Database Support ==

Work is underway on a patch for #1142, which will add support for multiple database connections. This page documents my current plan and progress towards a fully working patch.

=== Current status ===

'''HIGHLY UNSTABLE''' The branch is in the middle of major implementation changes, some of which are waiting to merge refactoring from trunk. It will be unstable and unusable for at least a few days.

Several aspects of the design outlined below have changed, after discusson on the developer's list. I'm hoping to be able to update the code and this page within the next few days.
 
Work is ongoing in the multiple-db-support branch, which you can check out thusly:

{{{
svn co http://code.djangoproject.com/svn/django/branches/multiple-db-support
}}}

Most of the basic implementation is done, with the exception of the items in this todo list:

||'''TODO'''||'''status'''||
||OTHER_DATABASES not DATABASES||||
||MODELS entry in OTHER_DATABASES not model._meta.db_connection||||
||Move connection info to manager||||
||Tests for thread/request isolation||||
||Generate sql for dropping tables in django.db.backends.sql.ansi||||
||Generate sql for resetting sequences in postgres backend SchemaBuilder subclass||||
||When validating models, warn user if a model references another model that is configure to use a different connection||||
||Create mutliple_db.txt doc documenting use of settings, transactions, etc.||||
||Link to multiple db doc from other docs where appropriate||||
||Review tests and extend where appropriate||||

=== The plan ===

 * Avoid any change that impacts backward compatibility. The intent is to add new functionality for those who need it, not to change the most common use case of a single database connection.

 * Add a new settings variable, DATABASES. DATABASES is a dict of named database connection parameter sets. In each set, the keys are the same as the standard database connection settings variables.
{{{
#!python
DATABASES = { 
    'a': { 'DATABASE_ENGINE': 'sqlite3',
           'DATABASE_NAME': '/tmp/dba.db'
    },
    'b': { 'DATABASE_ENGINE': 'sqlite3',
           'DATABASE_NAME': '/tmp/dbb.db'
    }}
}}}   

  

 * Add db_connection to Meta. This allows model classes to specify which connection they should use.
{{{
#!python
class Artist(models.Model):
    name = models.CharField(maxlength=100)
    alive = models.BooleanField(default=True)

    def __str__(self):
        return self.name

    class Meta:
        db_connection = 'a'
        
class Widget(models.Model):
    code = models.CharField(maxlength=10, unique=True)
    weight = models.IntegerField()

    def __str__(self):
        return self.code
    
    class Meta:
        db_connection = 'b'
}}}

 * Allow transaction decorators, etc to take optional connections argument. Without that argument, transactions will apply across all connections already in use.
  
 * Move generation of schema manipulating sql (CREATE TABLE, etc) from django.core.management into backend.creation.

 * Add methods to Manager to support per-model installation. This will enable each model to be installed using the connection that it specifies. It causes some complications, mainly in determining the correct order in which to install. My current solution is to depend on the developer already having figure that out by defining her models in a sensible order; and, when that fails, punting any unresolved  constraints to the end of the syncdb or install process. The manager methods will delegate to each model's backend to do the sql creation.