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 .. _MySQLdb: http://sourceforge.net/projects/mysql-python
  80
  81 Creating your database
  82 ----------------------
  83
  84 You can `create your database`_ using the command-line tools and this SQL::
  85
  86   CREATE DATABASE <dbname> CHARACTER SET utf8;
  87
  88 This ensures all tables and columns will use UTF-8 by default.
  89
  90 .. _create your database: http://dev.mysql.com/doc/refman/5.0/en/create-database.html
  91
  92 Connecting to the database
  93 --------------------------
  94
  95 Refer to the `settings documentation`_.
  96
  97 Connection settings are used in this order:
  98
  99  1. ``DATABASE_OPTIONS``
 100  2. ``DATABASE_NAME``, ``DATABASE_USER``, ``DATABASE_PASSWORD``, ``DATABASE_HOST``,
 101     ``DATABASE_PORT``
 102  3. MySQL option files.
 103
 104 In other words, if you set the name of the database in ``DATABASE_OPTIONS``,
 105 this will take precedence over ``DATABASE_NAME``, which would override
 106 anything in a `MySQL option file`_.
 107
 108 Here's a sample configuration which uses a MySQL option file::
 109
 110   # settings.py
 111   DATABASE_ENGINE = "mysql"
 112   DATABASE_OPTIONS = {
 113       'read_default_file': '/path/to/my.cnf',
 114       }
 115
 116   # my.cnf
 117   [client]
 118   database = DATABASE_NAME
 119   user = DATABASE_USER
 120   passwd = DATABASE_PASSWORD
 121   default-character-set = utf8
 122
 123 Several other MySQLdb connection options may be useful, such as ``ssl``,
 124 ``use_unicode``, ``init_command``, and ``sql_mode``. Consult the
 125 `MySQLdb documentation`_ for more details.
 126
 127 .. _settings documentation: http://www.djangoproject.com/documentation/settings/#database-engine
 128 .. _MySQL option file: http://dev.mysql.com/doc/refman/5.0/en/option-files.html
 129 .. _MySQLdb documentation: http://mysql-python.sourceforge.net/
 130
 131 Creating your tables
 132 --------------------
 133
 134 When Django generates the schema, it doesn't specify a storage engine, so
 135 tables will be created with whatever default storage engine your database
 136 server is configured for. The easiest solution is to set your database server's
 137 default storage engine to the desired engine.
 138
 139 If you're using a hosting service and can't change your server's default
 140 storage engine, you have a couple of options.
 141
 142     * After the tables are created, execute an ``ALTER TABLE`` statement to
 143       convert a table to a new storage engine (such as InnoDB)::
 144
 145           ALTER TABLE <tablename> ENGINE=INNODB;
 146
 147       This can be tedious if you have a lot of tables.
 148
 149     * Another option is to use the ``init_command`` option for MySQLdb prior to
 150       creating your tables::
 151
 152           DATABASE_OPTIONS = {
 153               # ...
 154              "init_command": "SET storage_engine=INNODB",
 155               # ...
 156           }
 157
 158       This sets the default storage engine upon connecting to the database.
 159       After your tables have been created, you should remove this option.
 160
 161     * Another method for changing the storage engine is described in
 162       AlterModelOnSyncDB_.
 163
 164 .. _AlterModelOnSyncDB: http://code.djangoproject.com/wiki/AlterModelOnSyncDB
 165