{{{ #!text/x-rst ============================== Preparing an Oracle test setup ============================== **This document is work in progress** This document attempt to ease the task of running the Django test suite against Oracle by: * Providing a step by step setup guide to achieve that. * Hopefully collecting information (best practices, tuning tips) to do that as efficiently as possible. Chosen is GNU/Debian Linux, things should also work with Ubuntu Linux. The system isn't going to be dedicated exclusively to run Oracle so we will leave things set up so it is necessary to start it manually before a test-debug session. Obtain and install Oracle XE ============================ We will be roughly following the `Oracle installation documentation`_. #. Download the **oracle-xe-universal_10.2.0.1-1.0_i386.deb** package file from http://www.oracle.com/technetwork/database/express-edition/downloads/index.html (*Oracle Database 10g Express Edition for Linux x86*). You need to have an *Oracle Developer Network* account. Contrarily to what is suggested in some places_ I've found the newer `.deb` package you can get here_ and installable by using high level Debian/Ubuntu package management tools (APT, Aptitude, ...) didn't install things like the ``/etc/init.d/oracle-xe`` init script and some files under the ``/usr/lib/oracle`` hierarchy so I went with the older package plus dpkg and taking care of dependencies manually. #. Install the prerequisite packages, if you fail to do so the installation won't be successful but won't abort either:: $ sudo apt-get install bc libaio1 #. Make sure you have enough swap space. If you fail to do this, the Oracle package installation will abort with an error message about this unmet condition. ================ ====================== **RAM [MiB]** **Swap size required** ================ ====================== 0 > RAM >= 256 3 * RAM 256 > RAM > 512 2 * RAM RAM >= 512 1 GiB ================ ====================== #. Install the package you downloaded:: $ sudo dpkg -i oracle-xe-universal_10.2.0.1-1.0_i386.deb #. Configure the DB engine:: $ sudo /etc/init.d/oracle-xe configure It will ask you a number of questions, namely: * A TCP port for the Oracle Database XE graphical user interface (default: 8080) * A TCP port for the Oracle database listener (default: 1521) * A password for the SYS and SYSTEM administrative user accounts. Take note of the value you choose. * Whether you want the database to start automatically when the computer starts -- I chose **NO** here, see next step. #. **Optional** -- Create an alternate init script -- If you've answered NO to the question about running the Oracle DB engine automatically on system start then it won't be possible to start it manually because that flag is stored (among others) in the ``/etc/default/oracle-xe`` configuration file and we would be using the same script as the one executed when the system boots (``/etc/init.d/oracle-xe``) that always examines these values. What we can do is to create a slightly modified ``/etc/init.d/xe`` script that ignores that flag and allows us to control the Oracle process at will:: $ cd /etc/init.d $ sudo cp -a oracle-xe xe $ sudo patch < /home/myuser/oracle-xe-script.diff This is the ``oracle-xe-script.diff`` patch file (you can also download it):: --- oracle-xe 2006-02-24 17:23:15.000000000 -0300 +++ xe 2010-11-03 07:58:43.000000000 -0300 @@ -596,13 +596,8 @@ # See how we were called case "$1" in start) - if test -f "$CONFIGURATION" + if test ! -f "$CONFIGURATION" then - if test "$ORACLE_DBENABLED" != "true" - then - exit 0 - fi - else echo "Oracle Database 10g Express Edition is not configured. You must run '/etc/init.d/oracle-xe configure' as the root user to configure the database." exit 0 @@ -613,13 +608,8 @@ configure ;; stop) - if test -f "$CONFIGURATION" + if test ! -f "$CONFIGURATION" then - if test "$ORACLE_DBENABLED" != "true" - then - exit 0 - fi - else echo "Oracle Database 10g Express Edition is not configured. You must run '/etc/init.d/oracle-xe configure' as the root user to configure the database." exit 0 Now we can start/stop Oracle manually using it:: $ sudo /etc/init.d/xe start Starting Oracle Net Listener. Starting Oracle Database 10g Express Edition Instance. $ sudo /etc/init.d/xe stop Shutting down Oracle Database 10g Express Edition Instance. Stopping Oracle Net Listener. (in newer versions of Debian/Ubuntu we can use the shorter version ``sudo service xe start``) #. Make sure the needed Oracle environment vars needed by its client libraries are set (Bash shell):: $ echo "source /usr/lib/oracle/xe/app/oracle/product/10.2.0/server/bin/oracle_env.sh" >> ~/.bashrc $ source /usr/lib/oracle/xe/app/oracle/product/10.2.0/server/bin/oracle_env.sh #. Access the DB engine administration web app by pointing our Web browser to ``http://localhost:8080/apex`` and using the ``SYSTEM`` user and the password you chose above. #. Create an user to be used for running the tests. (e.g. ``djangotest``) -- Go to *Home > Administration > Database Users > CREATE* assign it a password (e.g. ``foo``) #. Give the user the needed privileges. * Roles: ``CONNECT``, ``RESOURCE`` and ``DBA`` * *Directly Granted System Privileges*: ``CREATE TABLE``, ``CREATE PROCEDURE``, ``CREATE SEQUENCE`` and ``CREATE TARIGGER`` #. We don't need to install the Oracle client stack because we are going to run the Django tests in the same system. .. _Oracle installation documentation: http://www.oracle.com/pls/xe102/to_toc?pathname=install.102%2Fb25144%2Ftoc.htm&remark=portal+%28Getting+Started%29 .. _places: http://blog.schmehl.info/Debian/oracle-xe .. _here: http://oss.oracle.com/debian/dists/unstable/non-free/binary-i386/ Install cx_Oracle ================= :: $ sudo apt-get install python-dev $ ... Create the Django settings file =============================== :: $ cat oracle.py DATABASES = { 'default': { 'ENGINE': 'django.db.backends.oracle', 'NAME': 'xe', 'USER': 'djangotest', 'PASSWORD': 'foo', }, 'other': { 'ENGINE': 'django.db.backends.oracle', 'NAME': 'xeother', 'USER': 'djangotest2', 'PASSWORD': 'bar', #'TEST_USER_CREATE': False, 'TEST_TBLSPACE': 'tblspace_other', 'TEST_TBLSPACE_TMP': 'tblspace_tmp_other', }, } Test things =========== :: $ sudo /etc/init.d/xe start $ ./runtests --settings=oracle.py basic Creating test database 'default'... Creating test user... Creating test database 'other'... Creating test user... .......s... ---------------------------------------------------------------------- Ran 11 tests in 2.279s OK (skipped=1) Destroying test database 'default'... Destroying test user... Destroying test database tables... Destroying test database 'other'... Destroying test user... Destroying test database tables... Notes ===== In my particular case I've implemented this setup by using a KVM virtual machine (host system is a workstation running Debian unstable *Sid*). The VM got two CPUs, 1 GiB of RAM and a 30 GiB hard disk. Platform is GNU/Debian Linux 5.0 aka *Lenny* (stable as of Nov 2010) because it still is in its support period and as a bonus contains Python 2.4 in pre-packaged form. Things should also work with Ubuntu Linux. Things to review: * How much does the Oracle installation pollutes the system?. If it result to be confined and easy to undo/cleanup, maybe this setup doesn't need to be done inside a VM. * System resource (CPU, RAM usage while running the full test suite). Maybe I can reduce the RAM assigned to the VM to 512 MiB and the virtual CPU count from two to one. To do ===== Finish the multi-db setup by crafting a correct Django settings file (``oracle.py`` above) that allows us to run the entire suite with errors. }}}