From efc1ff2004b533f3c2eac95499c19ee00b81d25d Mon Sep 17 00:00:00 2001 From: Adrian Holovaty Date: Fri, 30 Nov 2007 05:03:32 +0000 Subject: [PATCH] Edited docs/databases.txt Oracle changes from [6432] git-svn-id: http://code.djangoproject.com/svn/django/trunk@6763 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/databases.txt | 70 ++++++++++++++++++++++++++-------------------- 1 file changed, 40 insertions(+), 30 deletions(-) diff --git a/docs/databases.txt b/docs/databases.txt index 4530a1b896..d4853f75f8 100644 --- a/docs/databases.txt +++ b/docs/databases.txt @@ -172,22 +172,32 @@ storage engine, you have a couple of options. .. _AlterModelOnSyncDB: http://code.djangoproject.com/wiki/AlterModelOnSyncDB -Oracle Notes +Oracle notes ============ -Django supports `Oracle Database Server`_ versions 9i and higher. Oracle +Django supports `Oracle Database Server`_ versions 9i and higher. Oracle version 10g or later is required to use Django's ``regex`` and ``iregex`` query -operators. You will also need the `cx_Oracle`_ driver, version 4.3.1 or newer. +operators. You will also need the `cx_Oracle`_ driver, version 4.3.1 or newer. .. _`Oracle Database Server`: http://www.oracle.com/ .. _`cx_Oracle`: http://cx-oracle.sourceforge.net/ -To run ``python manage.py syncdb``, you'll need to create an Oracle database -user with CREATE TABLE, CREATE SEQUENCE, CREATE PROCEDURE, and CREATE TRIGGER -privileges. To run Django's test suite, the user also needs -CREATE and DROP DATABASE and CREATE and DROP TABLESPACE privileges. +In order for the ``python manage.py syncdb`` command to work, your Oracle +database user must have privileges to run the following commands: -Connecting to the Database + * CREATE TABLE + * CREATE SEQUENCE + * CREATE PROCEDURE + * CREATE TRIGGER + +To run Django's test suite, the user needs these *additional* privileges: + + * CREATE DATABASE + * DROP DATABASE + * CREATE TABLESPACE + * DROP TABLESPACE + +Connecting to the database -------------------------- Your Django settings.py file should look something like this for Oracle:: @@ -213,29 +223,29 @@ and ``DATABASE_PORT`` like so:: You should supply both ``DATABASE_HOST`` and ``DATABASE_PORT``, or leave both as empty strings. -Tablespace Options +Tablespace options ------------------ A common paradigm for optimizing performance in Oracle-based systems is the use of `tablespaces`_ to organize disk layout. The Oracle backend supports this use case by adding ``db_tablespace`` options to the ``Meta`` and -``Field`` classes. (When using a backend that lacks support for tablespaces, -these options are ignored.) +``Field`` classes. (When you use a backend that lacks support for tablespaces, +Django ignores these options.) .. _`tablespaces`: http://en.wikipedia.org/wiki/Tablespace A tablespace can be specified for the table(s) generated by a model by -supplying the ``db_tablespace`` option inside the model's ``Meta`` class. -Additionally, the ``db_tablespace`` option can be passed to a ``Field`` +supplying the ``db_tablespace`` option inside the model's ``class Meta``. +Additionally, you can pass the ``db_tablespace`` option to a ``Field`` constructor to specify an alternate tablespace for the ``Field``'s column -index. If no index would be created for the column, the ``db_tablespace`` +index. If no index would be created for the column, the ``db_tablespace`` option is ignored. :: class TablespaceExample(models.Model): - name = models.CharField(maxlength=30, db_index=True, db_tablespace="indexes") - data = models.CharField(maxlength=255, db_index=True) + name = models.CharField(max_length=30, db_index=True, db_tablespace="indexes") + data = models.CharField(max_length=255, db_index=True) edges = models.ManyToManyField(to="self", db_tablespace="indexes") class Meta: @@ -243,46 +253,46 @@ option is ignored. In this example, the tables generated by the ``TablespaceExample`` model (i.e., the model table and the many-to-many table) would be stored in the -``tables`` tablespace. The index for the name field and the indexes on the -many-to-many table would be stored in the ``indexes`` tablespace. The ``data`` +``tables`` tablespace. The index for the name field and the indexes on the +many-to-many table would be stored in the ``indexes`` tablespace. The ``data`` field would also generate an index, but no tablespace for it is specified, so it would be stored in the model tablespace ``tables`` by default. -Django does not create the tablespaces for you. Please refer to `Oracle's +Django does not create the tablespaces for you. Please refer to `Oracle's documentation`_ for details on creating and managing tablespaces. .. _`Oracle's documentation`: http://download.oracle.com/docs/cd/B19306_01/server.102/b14200/statements_7003.htm#SQLRF01403 -Naming Issues +Naming issues ------------- -Oracle imposes a name length limit of 30 characters. To accommodate this, the +Oracle imposes a name length limit of 30 characters. To accommodate this, the backend truncates database identifiers to fit, replacing the final four characters of the truncated name with a repeatable MD5 hash value. -NULL and Empty Strings +NULL and empty strings ---------------------- Django generally prefers to use the empty string ('') rather than NULL, but -Oracle treats both identically. To get around this, the Oracle backend +Oracle treats both identically. To get around this, the Oracle backend coerces the ``null=True`` option on fields that permit the empty string as a -value. When fetching from the database, it is assumed that a NULL value in +value. When fetching from the database, it is assumed that a NULL value in one of these fields really means the empty string, and the data is silently converted to reflect this assumption. -TextField Limitations ---------------------- +``TextField`` limitations +------------------------- -The Oracle backend stores ``TextFields`` as ``NCLOB`` columns. Oracle imposes +The Oracle backend stores ``TextFields`` as ``NCLOB`` columns. Oracle imposes some limitations on the usage of such LOB columns in general: * LOB columns may not be used as primary keys. * LOB columns may not be used in indexes. - * LOB columns may not be used in a ``SELECT DISTINCT`` list. This means that + * LOB columns may not be used in a ``SELECT DISTINCT`` list. This means that attempting to use the ``QuerySet.distinct`` method on a model that includes ``TextField`` columns will result in an error when run against - Oracle. A workaround to this is to keep ``TextField`` columns out of any - models that you foresee performing ``.distinct`` queries on, and to + Oracle. A workaround to this is to keep ``TextField`` columns out of any + models that you foresee performing ``distinct()`` queries on, and to include the ``TextField`` in a related model instead.