docs/databases.txt

   1 ===============================
   2 Notes about supported databases
   3 ===============================
   4
   5 Django attempts to support as many features as possible on all database
   6 backends. However, not all database backends are alike, and we've had to make
   7 design decisions on which features to support and which assumptions we can make
   8 safely.
   9
  10 This file describes some of the features that might be relevant to Django
  11 usage. Of course, it is not intended as a replacement for server-specific
  12 documentation or reference manuals.
  13
  14 MySQL notes
  15 ===========
  16
  17 Django expects the database to support transactions, referential integrity,
  18 and Unicode support (UTF-8 encoding). Fortunately, MySQL_ has all these
  19 features as available as far back as 3.23. While it may be possible to use
  20 3.23 or 4.0, you'll probably have less trouble if you use 4.1 or 5.0.
  21
  22 MySQL 4.1
  23 ---------
  24
  25 `MySQL 4.1`_ has greatly improved support for character sets. It is possible to
  26 set different default character sets on the database, table, and column.
  27 Previous versions have only a server-wide character set setting. It's also the
  28 first version where the character set can be changed on the fly. 4.1 also has
  29 support for views, but Django currently doesn't use views.
  30
  31 MySQL 5.0
  32 ---------
  33
  34 `MySQL 5.0`_ adds the ``information_schema`` database, which contains detailed
  35 data on all database schema. Django's ``inspectdb`` feature uses this
  36 ``information_schema`` if it's available. 5.0 also has support for stored
  37 procedures, but Django currently doesn't use stored procedures.
  38
  39 .. _MySQL: http://www.mysql.com/
  40 .. _MySQL 4.1: http://dev.mysql.com/doc/refman/4.1/en/index.html
  41 .. _MySQL 5.0: http://dev.mysql.com/doc/refman/5.0/en/index.html
  42
  43 Storage engines
  44 ---------------
  45
  46 MySQL has several `storage engines`_ (previously called table types). You can
  47 change the default storage engine in the server configuration.
  48
  49 The default engine is MyISAM_. The main drawback of MyISAM is that it doesn't
  50 currently support transactions or foreign keys. On the plus side, it's
  51 currently the only engine that supports full-text indexing and searching.
  52
  53 The InnoDB_ engine is fully transactional and supports foreign key references.
  54
  55 The BDB_ engine, like InnoDB, is also fully transactional and supports foreign
  56 key references. However, its use seems to be deprecated.
  57
  58 `Other storage engines`_, including SolidDB_ and Falcon_, are on the horizon.
  59 For now, InnoDB is probably your best choice.
  60
  61 .. _storage engines: http://dev.mysql.com/doc/refman/5.0/en/storage-engines.html
  62 .. _MyISAM: http://dev.mysql.com/doc/refman/5.0/en/myisam-storage-engine.html
  63 .. _BDB: http://dev.mysql.com/doc/refman/5.0/en/bdb-storage-engine.html
  64 .. _InnoDB: http://dev.mysql.com/doc/refman/5.0/en/innodb.html
  65 .. _Other storage engines: http://dev.mysql.com/doc/refman/5.1/en/storage-engines-other.html
  66 .. _SolidDB: http://forge.mysql.com/projects/view.php?id=139
  67 .. _Falcon: http://dev.mysql.com/doc/falcon/en/index.html
  68
  69 MySQLdb
  70 -------
  71
  72 `MySQLdb`_ is the Python interface to MySQL. Version 1.2.1p2 or later is
  73 required for full MySQL support in Django. Earlier versions will not work with
  74 the ``mysql`` backend.
  75
  76 If you are trying to use an older version of MySQL and the ``mysql_old``
  77 backend, then 1.2.0 *might* work for you.
  78
  79 .. note::
  80     If you see ``ImportError: cannot import name ImmutableSet`` when trying to
  81     use Django, your MySQLdb installation may contain an outdated ``sets.py``
  82     file that conflicts with the built-in module of the same name from Python
  83     2.4 and later. To fix this, verify that you have installed MySQLdb version
  84     1.2.1p2 or newer, then delete the ``sets.py`` file in the MySQLdb
  85     directory that was left by an earlier version.
  86
  87 .. _MySQLdb: http://sourceforge.net/projects/mysql-python
  88
  89 Creating your database
  90 ----------------------
  91
  92 You can `create your database`_ using the command-line tools and this SQL::
  93
  94   CREATE DATABASE <dbname> CHARACTER SET utf8;
  95
  96 This ensures all tables and columns will use UTF-8 by default.
  97
  98 .. _create your database: http://dev.mysql.com/doc/refman/5.0/en/create-database.html
  99
 100 Connecting to the database
 101 --------------------------
 102
 103 Refer to the `settings documentation`_.
 104
 105 Connection settings are used in this order:
 106
 107  1. ``DATABASE_OPTIONS``
 108  2. ``DATABASE_NAME``, ``DATABASE_USER``, ``DATABASE_PASSWORD``, ``DATABASE_HOST``,
 109     ``DATABASE_PORT``
 110  3. MySQL option files.
 111
 112 In other words, if you set the name of the database in ``DATABASE_OPTIONS``,
 113 this will take precedence over ``DATABASE_NAME``, which would override
 114 anything in a `MySQL option file`_.
 115
 116 Here's a sample configuration which uses a MySQL option file::
 117
 118   # settings.py
 119   DATABASE_ENGINE = "mysql"
 120   DATABASE_OPTIONS = {
 121       'read_default_file': '/path/to/my.cnf',
 122       }
 123
 124   # my.cnf
 125   [client]
 126   database = DATABASE_NAME
 127   user = DATABASE_USER
 128   password = DATABASE_PASSWORD
 129   default-character-set = utf8
 130
 131 Several other MySQLdb connection options may be useful, such as ``ssl``,
 132 ``use_unicode``, ``init_command``, and ``sql_mode``. Consult the
 133 `MySQLdb documentation`_ for more details.
 134
 135 .. _settings documentation: ../settings/#database-engine
 136 .. _MySQL option file: http://dev.mysql.com/doc/refman/5.0/en/option-files.html
 137 .. _MySQLdb documentation: http://mysql-python.sourceforge.net/
 138
 139 Creating your tables
 140 --------------------
 141
 142 When Django generates the schema, it doesn't specify a storage engine, so
 143 tables will be created with whatever default storage engine your database
 144 server is configured for. The easiest solution is to set your database server's
 145 default storage engine to the desired engine.
 146
 147 If you're using a hosting service and can't change your server's default
 148 storage engine, you have a couple of options.
 149
 150     * After the tables are created, execute an ``ALTER TABLE`` statement to
 151       convert a table to a new storage engine (such as InnoDB)::
 152
 153           ALTER TABLE <tablename> ENGINE=INNODB;
 154
 155       This can be tedious if you have a lot of tables.
 156
 157     * Another option is to use the ``init_command`` option for MySQLdb prior to
 158       creating your tables::
 159
 160           DATABASE_OPTIONS = {
 161               # ...
 162              "init_command": "SET storage_engine=INNODB",
 163               # ...
 164           }
 165
 166       This sets the default storage engine upon connecting to the database.
 167       After your tables have been created, you should remove this option.
 168
 169     * Another method for changing the storage engine is described in
 170       AlterModelOnSyncDB_.
 171
 172 .. _AlterModelOnSyncDB: http://code.djangoproject.com/wiki/AlterModelOnSyncDB
 173
 174
 175 Oracle Notes
 176 ============
 177
 178 Django supports `Oracle Database Server`_ versions 9i and higher.  Oracle
 179 version 10g or later is required to use Django's ``regex`` and ``iregex`` query
 180 operators.  You will also need the `cx_Oracle`_ driver, version 4.3.1 or newer.
 181
 182 .. _`Oracle Database Server`: http://www.oracle.com/
 183 .. _`cx_Oracle`: http://cx-oracle.sourceforge.net/
 184
 185 To run ``python manage.py syncdb``, you'll need to create an Oracle database
 186 user with CREATE TABLE, CREATE SEQUENCE, CREATE PROCEDURE, and CREATE TRIGGER
 187 privileges.  To run Django's test suite, the user also needs
 188 CREATE and DROP DATABASE and CREATE and DROP TABLESPACE privileges.
 189
 190 Connecting to the Database
 191 --------------------------
 192
 193 Your Django settings.py file should look something like this for Oracle::
 194
 195     DATABASE_ENGINE = 'oracle'
 196     DATABASE_NAME = 'xe'
 197     DATABASE_USER = 'a_user'
 198     DATABASE_PASSWORD = 'a_password'
 199     DATABASE_HOST = ''
 200     DATABASE_PORT = ''
 201
 202 If you don't use a ``tnsnames.ora`` file or a similar naming method that
 203 recognizes the SID ("xe" in this example), then fill in both ``DATABASE_HOST``
 204 and ``DATABASE_PORT`` like so::
 205
 206     DATABASE_ENGINE = 'oracle'
 207     DATABASE_NAME = 'xe'
 208     DATABASE_USER = 'a_user'
 209     DATABASE_PASSWORD = 'a_password'
 210     DATABASE_HOST = 'dbprod01ned.mycompany.com'
 211     DATABASE_PORT = '1540'
 212
 213 You should supply both ``DATABASE_HOST`` and ``DATABASE_PORT``, or leave both
 214 as empty strings.
 215
 216 Tablespace Options
 217 ------------------
 218
 219 A common paradigm for optimizing performance in Oracle-based systems is the
 220 use of `tablespaces`_ to organize disk layout. The Oracle backend supports
 221 this use case by adding ``db_tablespace`` options to the ``Meta`` and
 222 ``Field`` classes.  (When using a backend that lacks support for tablespaces,
 223 these options are ignored.)
 224
 225 .. _`tablespaces`: http://en.wikipedia.org/wiki/Tablespace
 226
 227 A tablespace can be specified for the table(s) generated by a model by
 228 supplying the ``db_tablespace`` option inside the model's ``Meta`` class.
 229 Additionally, the ``db_tablespace`` option can be passed to a ``Field``
 230 constructor to specify an alternate tablespace for the ``Field``'s column
 231 index.  If no index would be created for the column, the ``db_tablespace``
 232 option is ignored.
 233
 234 ::
 235
 236     class TablespaceExample(models.Model):
 237         name = models.CharField(maxlength=30, db_index=True, db_tablespace="indexes")
 238         data = models.CharField(maxlength=255, db_index=True)
 239         edges = models.ManyToManyField(to="self", db_tablespace="indexes")
 240
 241         class Meta:
 242             db_tablespace = "tables"
 243
 244 In this example, the tables generated by the ``TablespaceExample`` model
 245 (i.e., the model table and the many-to-many table) would be stored in the
 246 ``tables`` tablespace.  The index for the name field and the indexes on the
 247 many-to-many table would be stored in the ``indexes`` tablespace.  The ``data``
 248 field would also generate an index, but no tablespace for it is specified, so
 249 it would be stored in the model tablespace ``tables`` by default.
 250
 251 Django does not create the tablespaces for you.  Please refer to `Oracle's
 252 documentation`_ for details on creating and managing tablespaces.
 253
 254 .. _`Oracle's documentation`: http://download.oracle.com/docs/cd/B19306_01/server.102/b14200/statements_7003.htm#SQLRF01403
 255
 256 Naming Issues
 257 -------------
 258
 259 Oracle imposes a name length limit of 30 characters.  To accommodate this, the
 260 backend truncates database identifiers to fit, replacing the final four
 261 characters of the truncated name with a repeatable MD5 hash value.
 262
 263 NULL and Empty Strings
 264 ----------------------
 265
 266 Django generally prefers to use the empty string ('') rather than NULL, but
 267 Oracle treats both identically.  To get around this, the Oracle backend
 268 coerces the ``null=True`` option on fields that permit the empty string as a
 269 value.  When fetching from the database, it is assumed that a NULL value in
 270 one of these fields really means the empty string, and the data is silently
 271 converted to reflect this assumption.
 272
 273 TextField Limitations
 274 ---------------------
 275
 276 The Oracle backend stores ``TextFields`` as ``NCLOB`` columns.  Oracle imposes
 277 some limitations on the usage of such LOB columns in general:
 278
 279   * LOB columns may not be used as primary keys.
 280
 281   * LOB columns may not be used in indexes.
 282
 283   * LOB columns may not be used in a ``SELECT DISTINCT`` list.  This means that
 284     attempting to use the ``QuerySet.distinct`` method on a model that
 285     includes ``TextField`` columns will result in an error when run against
 286     Oracle.  A workaround to this is to keep ``TextField`` columns out of any
 287     models that you foresee performing ``.distinct`` queries on, and to
 288     include the ``TextField`` in a related model instead.