| =============================== |
| Notes about supported databases |
| =============================== |
| |
| Django attempts to support as many features as possible on all database |
| backends. However, not all database backends are alike, and we've had to make |
| design decisions on which features to support and which assumptions we can make |
| safely. |
| |
| This file describes some of the features that might be relevant to Django |
| usage. Of course, it is not intended as a replacement for server-specific |
| documentation or reference manuals. |
| |
| MySQL notes |
| =========== |
| |
| Django expects the database to support transactions, referential integrity, |
| and Unicode support (UTF-8 encoding). Fortunately, MySQL_ has all these |
| features as available as far back as 3.23. While it may be possible to use |
| 3.23 or 4.0, you'll probably have less trouble if you use 4.1 or 5.0. |
| |
| MySQL 4.1 |
| --------- |
| |
| `MySQL 4.1`_ has greatly improved support for character sets. It is possible to |
| set different default character sets on the database, table, and column. |
| Previous versions have only a server-wide character set setting. It's also the |
| first version where the character set can be changed on the fly. 4.1 also has |
| support for views, but Django currently doesn't use views. |
| |
| MySQL 5.0 |
| --------- |
| |
| `MySQL 5.0`_ adds the ``information_schema`` database, which contains detailed |
| data on all database schema. Django's ``inspectdb`` feature uses this |
| ``information_schema`` if it's available. 5.0 also has support for stored |
| procedures, but Django currently doesn't use stored procedures. |
| |
| .. _MySQL: http://www.mysql.com/ |
| .. _MySQL 4.1: http://dev.mysql.com/doc/refman/4.1/en/index.html |
| .. _MySQL 5.0: http://dev.mysql.com/doc/refman/5.0/en/index.html |
| |
| Storage engines |
| --------------- |
| |
| MySQL has several `storage engines`_ (previously called table types). You can |
| change the default storage engine in the server configuration. |
| |
| The default engine is MyISAM_. The main drawback of MyISAM is that it doesn't |
| currently support transactions or foreign keys. On the plus side, it's |
| currently the only engine that supports full-text indexing and searching. |
| |
| The InnoDB_ engine is fully transactional and supports foreign key references. |
| |
| The BDB_ engine, like InnoDB, is also fully transactional and supports foreign |
| key references. However, its use seems to be deprecated. |
| |
| `Other storage engines`_, including SolidDB_ and Falcon_, are on the horizon. |
| For now, InnoDB is probably your best choice. |
| |
| .. _storage engines: http://dev.mysql.com/doc/refman/5.0/en/storage-engines.html |
| .. _MyISAM: http://dev.mysql.com/doc/refman/5.0/en/myisam-storage-engine.html |
| .. _BDB: http://dev.mysql.com/doc/refman/5.0/en/bdb-storage-engine.html |
| .. _InnoDB: http://dev.mysql.com/doc/refman/5.0/en/innodb.html |
| .. _Other storage engines: http://dev.mysql.com/doc/refman/5.1/en/storage-engines-other.html |
| .. _SolidDB: http://forge.mysql.com/projects/view.php?id=139 |
| .. _Falcon: http://dev.mysql.com/doc/falcon/en/index.html |
| |
| MySQLdb |
| ------- |
| |
| `MySQLdb`_ is the Python interface to MySQL. 1.2.1 is the first version that |
| has support for MySQL 4.1 and newer. If you are trying to use an older version |
| of MySQL, then 1.2.0 *might* work for you. |
| |
| .. _MySQLdb: http://sourceforge.net/projects/mysql-python |
| |
| Creating your database |
| ---------------------- |
| |
| You can `create your database`_ using the command-line tools and this SQL:: |
| |
| CREATE DATABASE <dbname> CHARACTER SET utf8; |
| |
| This ensures all tables and columns will use UTF-8 by default. |
| |
| .. _create your database: http://dev.mysql.com/doc/refman/5.0/en/create-database.html |
| |
| Connecting to the database |
| -------------------------- |
| |
| Refer to the `settings documentation`_. |
| |
| Connection settings are used in this order: |
| |
| 1. ``DATABASE_OPTIONS`` |
| 2. ``DATABASE_NAME``, ``DATABASE_USER``, ``DATABASE_PASSWORD``, ``DATABASE_HOST``, |
| ``DATABASE_PORT`` |
| 3. MySQL option files. |
| |
| In other words, if you set the name of the database in ``DATABASE_OPTIONS``, |
| this will take precedence over ``DATABASE_NAME``, which would override |
| anything in a `MySQL option file`_. |
| |
| Here's a sample configuration which uses a MySQL option file:: |
| |
| # settings.py |
| DATABASE_ENGINE = "mysql" |
| DATABASE_OPTIONS = { |
| 'read_default_file': '/path/to/my.cnf', |
| } |
| |
| # my.cnf |
| [client] |
| database = DATABASE_NAME |
| user = DATABASE_USER |
| passwd = DATABASE_PASSWORD |
| default-character-set = utf8 |
| |
| Several other MySQLdb connection options may be useful, such as ``ssl``, |
| ``use_unicode``, ``init_command``, and ``sql_mode``. Consult the |
| `MySQLdb documentation`_ for more details. |
| |
| .. _settings documentation: http://www.djangoproject.com/documentation/settings/#database-engine |
| .. _MySQL option file: http://dev.mysql.com/doc/refman/5.0/en/option-files.html |
| .. _MySQLdb documentation: http://mysql-python.sourceforge.net/ |
| |
| Creating your tables |
| -------------------- |
| |
| When Django generates the schema, it doesn't specify a storage engine, so |
| tables will be created with whatever default storage engine your database |
| server is configured for. The easiest solution is to set your database server's |
| default storage engine to the desired engine. |
| |
| If you're using a hosting service and can't change your server's default |
| storage engine, you have a couple of options. |
| |
| * After the tables are created, execute an ``ALTER TABLE`` statement to |
| convert a table to a new storage engine (such as InnoDB):: |
| |
| ALTER TABLE <tablename> ENGINE=INNODB; |
| |
| This can be tedious if you have a lot of tables. |
| |
| * Another option is to use the ``init_command`` option for MySQLdb prior to |
| creating your tables:: |
| |
| DATABASE_OPTIONS = { |
| # ... |
| "init_command": "SET storage_engine=INNODB", |
| # ... |
| } |
| |
| This sets the default storage engine upon connecting to the database. |
| After your tables have been created, you should remove this option. |
| |
| * Another method for changing the storage engine is described in |
| AlterModelOnSyncDB_. |
| |
| .. _AlterModelOnSyncDB: http://code.djangoproject.com/wiki/AlterModelOnSyncDB |
| |