diff --git a/docs/databases.txt b/docs/databases.txt index ff6abd7271..3545b58d47 100644 --- a/docs/databases.txt +++ b/docs/databases.txt @@ -1,56 +1,59 @@ =============================== -Notes About Supported Databases +Notes about supported databases =============================== -Django attempts to support as many features as possible on all databases. -However, since not all database servers are identical, there is obviously -going to be some variations. This file describes some of the -features that might relevant to Django usage. It is not intended as a -replacement for server-specific documentation or reference manuals. +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. -MySQL Notes +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 +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 will probably have less trouble if you use 4.1 or 5.0. +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 --------- -MySQL-4.1_ has greatly improved support for character sets. It is possible to +`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 these are not currently used by Django. +support for views, but Django currently doesn't use views. -MySQL-5.0 +MySQL 5.0 --------- -MySQL-5.0_ adds the ``information_schema`` database, which contains detailed -data on all database schema. This is used for Django's ``inspectdb`` feature, -when it is available. 5.0 also has support for stored procedures, but these -are not currently used by Django. +`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 +.. _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 +Storage engines --------------- MySQL has several `storage engines`_ (previously called table types). You can change the default storage engine in the server configuration. -The default one is MyISAM_. The main drawback of MyISAM is that it does not -currently have support for transactions or foreign keys. On the plus side, it -is currently the only engine that supports full-text indexing and searching. +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, it's use seems to be somewhat deprecated. +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. @@ -66,25 +69,25 @@ For now, InnoDB is probably your best choice. MySQLdb ------- -`MySQLdb`_ is the Python interface to MySQL. 1.2.1 is the first version which -has support for MySQL-4.1 and newer. If you are trying to use an older version -of MySQL, then 1.2.0 *may* work for you. +`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 CHARACTER SET utf8; - -This ensures all tables and columns will use utf8 by default. - + +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`_. @@ -106,7 +109,7 @@ Here's a sample configuration which uses a MySQL option file:: DATABASE_OPTIONS = { 'read_default_file': '/path/to/my.cnf', } - + # my.cnf [client] database = DATABASE_NAME @@ -114,49 +117,46 @@ Here's a sample configuration which uses a MySQL option file:: passwd = DATABASE_PASSWORD default-character-set = utf8 -There are several other MySQLdb connection options which may be useful, such -as ``ssl``, ``use_unicode``, ``init_command``, and ``sql_mode``; consult the +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 they -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. +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. -__ `storage engines`_ - -If you are using a hosting service and can't change your server's default +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 is created, all that is needed to convert it to a new storage -engine (such as InnoDB) is:: - - ALTER TABLE ENGINE=INNODB; + * After the tables are created, execute an ``ALTER TABLE`` statement to + convert a table to a new storage engine (such as InnoDB):: -With a lot of tables, this can be tedious. + ALTER TABLE ENGINE=INNODB; -Another option is to use the ``init_command`` option for MySQLdb prior to -creating your tables:: + This can be tedious if you have a lot of tables. - DATABASE_OPTIONS = { - ... - "init_command": "SET storage_engine=INNODB", - ... - } + * Another option is to use the ``init_command`` option for MySQLdb prior to + creating your tables:: -This sets the default storage engine upon connecting to the database. After -your tables are set up and running in production, you should remove this -option. + DATABASE_OPTIONS = { + # ... + "init_command": "SET storage_engine=INNODB", + # ... + } -Another method for changing the storage engine is described in -AlterModelOnSyncDB_. + 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