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