Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Cleaned up docs/databases.txt

git-svn-id: http://code.djangoproject.com/svn/django/trunk@4749 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit f765aa4e4475d7c3df20beb1c6e0f1ef5c4edc27 1 parent cecd520
@adrianholovaty adrianholovaty authored
Showing with 61 additions and 61 deletions.
  1. +61 −61 docs/databases.txt
View
122 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 <dbname> 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 <tablename> 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 <tablename> 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::
+
+ DATABASE_OPTIONS = {
+ # ...
+ "init_command": "SET storage_engine=INNODB",
+ # ...
+ }
-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.
+ 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_.
+ * Another method for changing the storage engine is described in
+ AlterModelOnSyncDB_.
.. _AlterModelOnSyncDB: http://code.djangoproject.com/wiki/AlterModelOnSyncDB
Please sign in to comment.
Something went wrong with that request. Please try again.