mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-10-24 14:16:09 +00:00
Code Issues 32 Releases Wiki Activity

[soc2009/multidb] Renaming of database attributes - you now use NAME, ENGINE, etc rather than DATABASE_NAME, DATABASE_ENGINE inside DATABASES. Also deprecates the use of short names (.e.g., `sqlite3` for backends in ENGINE). Patch from Russell Keith-Magee.

Browse Source 
Conflicts:

	docs/releases/1.2.txt

git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2009/multidb@11775 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Alex Gaynor
2009-11-23 16:45:41 +00:00
parent 3e6ae729bc
commit 4e36fffab2
55 changed files with 628 additions and 425 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
docs/ref/databases.txt
View File

@@ -44,18 +44,20 @@ Autocommit mode
.. versionadded:: 1.1
If your application is particularly read-heavy and doesn't make many database
writes, the overhead of a constantly open transaction can sometimes be
noticeable. For those situations, if you're using the ``postgresql_psycopg2``
backend, you can configure Django to use *"autocommit"* behavior for the
connection, meaning that each database operation will normally be in its own
transaction, rather than having the transaction extend over multiple
operations. In this case, you can still manually start a transaction if you're
doing something that requires consistency across multiple database operations.
The autocommit behavior is enabled by setting the ``autocommit`` key in the
``DATABASE_OPTIONS`` part of your database in :setting:`DATABASES`::
If your application is particularly read-heavy and doesn't make many
database writes, the overhead of a constantly open transaction can
sometimes be noticeable. For those situations, if you're using the
``postgresql_psycopg2`` backend, you can configure Django to use
*"autocommit"* behavior for the connection, meaning that each database
operation will normally be in its own transaction, rather than having
the transaction extend over multiple operations. In this case, you can
still manually start a transaction if you're doing something that
requires consistency across multiple database operations. The
autocommit behavior is enabled by setting the ``autocommit`` key in
the :setting:`OPTIONS` part of your database configuration in
:setting:`DATABASES`::
DATABASE_OPTIONS = {
OPTIONS = {
"autocommit": True,
}
@@ -67,11 +69,11 @@ objects are changed or none of them are.
.. admonition:: This is database-level autocommit
This functionality is not the same as the
:ref:`topics-db-transactions-autocommit` decorator. That decorator is a
Django-level implementation that commits automatically after data changing
operations. The feature enabled using the ``DATABASE_OPTIONS`` option
provides autocommit behavior at the database adapter level. It commits
after *every* operation.
:ref:`topics-db-transactions-autocommit` decorator. That decorator
is a Django-level implementation that commits automatically after
data changing operations. The feature enabled using the
:setting:`OPTIONS` option provides autocommit behavior at the
database adapter level. It commits after *every* operation.
If you are using this feature and performing an operation akin to delete or
updating that requires multiple operations, you are strongly recommended to
@@ -234,14 +236,13 @@ Refer to the :ref:`settings documentation <ref-settings>`.
Connection settings are used in this order:
1. ``DATABASE_OPTIONS``.
2. ``DATABASE_NAME``, ``DATABASE_USER``,
``DATABASE_PASSWORD``, ``DATABASE_HOST``,
``DATABASE_PORT``
1. :setting:`OPTIONS`.
2. :setting:`NAME`, :setting:`USER`, :setting:`PASSWORD`,
:setting:`HOST`, :setting:`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
In other words, if you set the name of the database in ``OPTIONS``,
this will take precedence over ``NAME``, which would override
anything in a `MySQL option file`_.
Here's a sample configuration which uses a MySQL option file::
@@ -249,8 +250,8 @@ Here's a sample configuration which uses a MySQL option file::
# settings.py
DATABASES = {
'default': {
'DATABASE_ENGINE': "mysql",
'DATABASE_OPTIONS': {
'ENGINE': 'django.db.backends.mysql',
'OPTIONS': {
'read_default_file': '/path/to/my.cnf',
},
}
@@ -258,9 +259,9 @@ Here's a sample configuration which uses a MySQL option file::
# my.cnf
[client]
database = DATABASE_NAME
user = DATABASE_USER
password = DATABASE_PASSWORD
database = NAME
user = USER
password = PASSWORD
default-character-set = utf8
Several other MySQLdb connection options may be useful, such as ``ssl``,
@@ -291,7 +292,7 @@ storage engine, you have a couple of options.
* Another option is to use the ``init_command`` option for MySQLdb prior to
creating your tables::
DATABASE_OPTIONS = {
OPTIONS = {
"init_command": "SET storage_engine=INNODB",
}
@@ -456,7 +457,7 @@ If you're getting this error, you can solve it by:
* Increase the default timeout value by setting the ``timeout`` database
option option::
DATABASE_OPTIONS = {
OPTIONS = {
# ...
"timeout": 20,
# ...
@@ -511,32 +512,32 @@ Your Django settings.py file should look something like this for Oracle::
DATABASES = {
'default': {
'DATABASE_ENGINE': 'oracle',
'DATABASE_NAME': 'xe',
'DATABASE_USER': 'a_user',
'DATABASE_PASSWORD': 'a_password',
'DATABASE_HOST': '',
'DATABASE_PORT': '' ,
'ENGINE': 'django.db.backends.oracle',
'NAME': 'xe',
'USER': 'a_user',
'PASSWORD': 'a_password',
'HOST': '',
'PORT': '' ,
}
}
If you don't use a ``tnsnames.ora`` file or a similar naming method that
recognizes the SID ("xe" in this example), then fill in both
``DATABASE_HOST`` and ``DATABASE_PORT`` like so::
``HOST`` and ``PORT`` like so::
DATABASES = {
'default': {
'DATABASE_ENGINE': 'oracle',
'DATABASE_NAME': 'xe',
'DATABASE_USER': 'a_user',
'DATABASE_PASSWORD': 'a_password',
'DATABASE_HOST': 'dbprod01ned.mycompany.com',
'DATABASE_PORT': '1540',
'ENGINE': 'django.db.backends.oracle',
'NAME': 'xe',
'USER': 'a_user',
'PASSWORD': 'a_password',
'HOST': 'dbprod01ned.mycompany.com',
'PORT': '1540',
}
}
You should supply both ``DATABASE_HOST`` and ``DATABASE_PORT``, or leave both
You should supply both ``HOST`` and ``PORT``, or leave both
as empty strings.
Tablespace options

6
docs/ref/django-admin.txt
View File

@@ -160,8 +160,8 @@ dbshell
.. django-admin:: dbshell
Runs the command-line client for the database engine specified in your
``DATABASE_ENGINE`` setting, with the connection parameters specified in your
``DATABASE_USER``, ``DATABASE_PASSWORD``, etc., settings.
``ENGINE`` setting, with the connection parameters specified in your
``USER``, ``PASSWORD``, etc., settings.
* For PostgreSQL, this runs the ``psql`` command-line client.
* For MySQL, this runs the ``mysql`` command-line client.
@@ -265,7 +265,7 @@ inspectdb
.. django-admin:: inspectdb
Introspects the database tables in the database pointed-to by the
``DATABASE_NAME`` setting and outputs a Django model module (a ``models.py``
``NAME`` setting and outputs a Django model module (a ``models.py``
file) to standard output.
Use this if you have a legacy database with which you'd like to use Django.

185
docs/ref/settings.txt
View File

@@ -195,41 +195,60 @@ end users) indicating the reason the request was rejected. See
DATABASES
---------
.. versionadded: 1.2
Default: ``{}`` (Empty dictionary)
This is a dictionary containg the settings for all databases to be used with
Django. It is a nested dictionary who's contents maps aliases to a dictionary
containing the options for an individual database. The following inner options
are used:
A dictionary containing the settings for all databases to be used with
Django. It is a nested dictionary who's contents maps database aliases
to a dictionary containing the options for an individual database.
.. deprecated: 1.2
The :setting:`DATABASES` setting must configure a ``default`` database;
any number of additional databases may also be specified.
In versions of Django prior to 1.2 each of the following were
individual settings. The usage of the standalone database settings
has been deprecated, and will be removed in Django 1.4.
The simplest possible settings file is for a single-database setup using
SQLite. This can be configured using the following::
DATABASES = {
'default': {
'BACKEND': 'django.db.backends.sqlite3',
'NAME': 'mydatabase'
}
}
.. setting:: DATABASE_ENGINE
For other database backends, or more complex SQLite configurations, other options
will be required. The following inner options are available.
DATABASE_ENGINE
~~~~~~~~~~~~~~~
.. setting:: ENGINE
ENGINE
~~~~~~
Default: ``''`` (Empty string)
The database backend to use. The built-in database backends are
``'postgresql_psycopg2'``, ``'postgresql'``, ``'mysql'``, ``'sqlite3'``, and
``'oracle'``.
The database backend to use. The built-in database backends are:
* ``'django.db.backends.postgresql_psycopg2'``
* ``'django.db.backends.postgresql'``
* ``'django.db.backends.mysql'``
* ``'django.db.backends.sqlite3'``
* ``'django.db.backends.oracle'``
You can use a database backend that doesn't ship with Django by setting
``DATABASE_ENGINE`` to a fully-qualified path (i.e.
``ENGINE`` to a fully-qualified path (i.e.
``mypackage.backends.whatever``). Writing a whole new database backend from
scratch is left as an exercise to the reader; see the other backends for
examples.
.. versionadded:: 1.0
Support for external database backends is new in 1.0.
.. note::
Prior to Django 1.2, you could use a short version of the backend name
to reference the built-in database backends (e.g., you could use
``'sqlite3'`` to refer to the SQLite backend). This format has been
deprecated, and will be removed in Django 1.4.
DATABASE_HOST
~~~~~~~~~~~~~
.. setting:: HOST
HOST
~~~~
Default: ``''`` (Empty string)
@@ -239,7 +258,7 @@ localhost. Not used with SQLite.
If this value starts with a forward slash (``'/'``) and you're using MySQL,
MySQL will connect via a Unix socket to the specified socket. For example::
"DATABASE_HOST": '/var/run/mysql'
"HOST": '/var/run/mysql'
If you're using MySQL and this value *doesn't* start with a forward slash, then
this value is assumed to be the host.
@@ -249,8 +268,10 @@ for the connection, rather than a network connection to localhost. If you
explicitly need to use a TCP/IP connection on the local machine with
PostgreSQL, specify ``localhost`` here.
DATABASE_NAME
~~~~~~~~~~~~~
.. setting:: NAME
NAME
~~~~
Default: ``''`` (Empty string)
@@ -258,41 +279,48 @@ The name of the database to use. For SQLite, it's the full path to the database
file. When specifying the path, always use forward slashes, even on Windows
(e.g. ``C:/homes/user/mysite/sqlite3.db``).
DATABASE_OPTIONS
~~~~~~~~~~~~~~~~
.. setting:: OPTIONS
OPTIONS
~~~~~~~
Default: ``{}`` (Empty dictionary)
Extra parameters to use when connecting to the database. Consult backend
module's document for available keywords.
DATABASE_PASSWORD
~~~~~~~~~~~~~~~~~
.. setting:: PASSWORD
PASSWORD
~~~~~~~~
Default: ``''`` (Empty string)
The password to use when connecting to the database. Not used with SQLite.
DATABASE_PORT
~~~~~~~~~~~~~
.. setting:: PORT
PORT
~~~~
Default: ``''`` (Empty string)
The port to use when connecting to the database. An empty string means the
default port. Not used with SQLite.
DATABASE_USER
~~~~~~~~~~~~~
.. setting:: USER
USER
~~~~
Default: ``''`` (Empty string)
The username to use when connecting to the database. Not used with SQLite.
.. setting:: TEST_CHARSET
TEST_DATABASE_CHARSET
~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 1.0
TEST_CHARSET
~~~~~~~~~~~~
Default: ``None``
@@ -306,11 +334,10 @@ MySQL_ (``mysql``) backends.
.. _PostgreSQL: http://www.postgresql.org/docs/8.2/static/multibyte.html
.. _MySQL: http://www.mysql.org/doc/refman/5.0/en/charset-database.html
.. setting:: TEST_COLLATION
TEST_DATABASE_COLLATION
~~~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 1.0
TEST_COLLATION
~~~~~~~~~~~~~~
Default: ``None``
@@ -322,8 +349,10 @@ manual for details).
.. _section 10.3.2: http://www.mysql.org/doc/refman/5.0/en/charset-database.html
TEST_DATABASE_NAME
~~~~~~~~~~~~~~~~~~
.. setting:: TEST_NAME
TEST_NAME
~~~~~~~~~
Default: ``None``
@@ -1292,3 +1321,79 @@ Different locales have different formats. For example, U.S. English would say
See :ttag:`allowed date format strings <now>`. See also ``DATE_FORMAT``,
``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``MONTH_DAY_FORMAT``.
Deprecated settings
===================
.. setting:: DATABASE_ENGINE
DATABASE_ENGINE
---------------
.. deprecated:: 1.2
This setting has been replaced by :setting:`ENGINE` in
:setting:`DATABASES`.
DATABASE_HOST
-------------
.. deprecated:: 1.2
This setting has been replaced by :setting:`HOST` in
:setting:`DATABASES`.
DATABASE_NAME
-------------
.. deprecated:: 1.2
This setting has been replaced by :setting:`NAME` in
:setting:`DATABASES`.
DATABASE_OPTIONS
----------------
.. deprecated:: 1.2
This setting has been replaced by :setting:`OPTIONS` in
:setting:`DATABASES`.
DATABASE_PASSWORD
-----------------
.. deprecated:: 1.2
This setting has been replaced by :setting:`PASSWORD` in
:setting:`DATABASES`.
DATABASE_PORT
-------------
.. deprecated:: 1.2
This setting has been replaced by :setting:`PORT` in
:setting:`DATABASES`.
DATABASE_USER
-------------
.. deprecated:: 1.2
This setting has been replaced by :setting:`USER` in
:setting:`DATABASES`.
TEST_DATABASE_CHARSET
---------------------
.. deprecated:: 1.2
This setting has been replaced by :setting:`TEST_CHARSET` in
:setting:`DATABASES`.
TEST_DATABASE_COLLATION
-----------------------
.. deprecated:: 1.2
This setting has been replaced by :setting:`TEST_COLLATION` in
:setting:`DATABASES`.
TEST_DATABASE_NAME
------------------
.. deprecated:: 1.2
This setting has been replaced by :setting:`TEST_NAME` in
:setting:`DATABASES`.