mirror of https://github.com/django/django.git
166 lines
6.0 KiB
Plaintext
166 lines
6.0 KiB
Plaintext
===============================
|
|
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. Version 1.2.1p2 or later is
|
|
required for full MySQL support in Django. Earlier versions will not work with
|
|
the ``mysql`` backend.
|
|
|
|
If you are trying to use an older version of MySQL and the ``mysql_old``
|
|
backend, 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
|
|
|