{{{
#!text/x-rst
==============================
Preparing an Oracle test setup
==============================

This document attempts to ease the task of running Django's (or your own app's) test suite against Oracle by providing a step by step setup guide to achieve that.

Using the Oracle Developer Day pre-installed VM
===============================================

Oracle provides pre-built virtual machine images with Oracle Database 11g Release 2 Enterprise Edition for developers in form of an OVA archive which can be imported by VirtualBox. The archive can be downloaded `here`__ (or alternately a different one can be chosen from `this list`__) after signing up for an *Oracle Developer Network* account.

.. __: http://www.oracle.com/technetwork/database/enterprise-edition/databaseappdev-vm-161299.html
.. __: http://www.oracle.com/technetwork/community/developer-vm/index.html

The server will probably be somewhat slower than if you install it directly on the host machine, but using a VM has a slightly simpler setup, there's a somewhat smaller chance you'll pollute your host system completely and in case something goes wrong, you can always just remove the virtual machine, import a fresh copy and start again.

#. Download the OVA file from http://www.oracle.com/technetwork/database/enterprise-edition/databaseappdev-vm-161299.html and import it into VirtualBox. You'll have to accept an extensive license agreement.

#. By default, the VM will be configured to have one NAT network interface. The database server itself starts automatically and listens on port 1521. You'll have to set up port forwarding in VirtualBox in order to access the server. Open the settings of the emulated network adapter and under *Advanced* open *Port Forwarding*. Insert a new rule with host IP set to 127.0.0.1, host port and destination port 1521 and an empty guest IP.

#. The server comes with a number of user accounts created beforehand but I only found out how to access two of them. There's ``sys``, which is a "sysdba" account (whatever that means), and ``system``. The password for both of these is ``oracle`` and both have full privileges. Since the ``sys`` account is "sysdba", I'm not sure it can be used to run the tests (it spits out an error message on login attempt) but ``system`` seems to work just fine.

   As for other credentials on the virtual machine, if you want to login as a regular user, just use ``oracle``/``oracle``, the root password is ``oracle`` as well. However, in order to run the test suite, you just need to boot the machine up, you don't need to start anything manually.

#. Install *instantclient* on your host system (the one where you'll be running the test suite). On Gentoo there is an ebuild, which means it is just a matter of ``emerge -av oracle-instantclient-basic`` and fetching the appropriate zip archives from the Oracle download site as instructed.

  On Debian or Ubuntu you can download the RPM package ("Instant Client Package - Basic"), convert it to a DEB package and install using alien::

   $ sudo alien -i oracle-instantclient-basic*.rpm

  After installing the client, you will need to install the "Instant Client Package - SDK". After downloading, unzip and copy it to the client install directory::
     
    $ unzip instantclient-sdk-linux.x64-*.zip
    $ sudo cp -R instantclient_11_2/* /usr/lib/oracle/11.2/client64/

#. Start a new shell and install cx_Oracle in your testing virtualenv::

    $ pip install cx_Oracle

   The new shell is necessary because the *instantclient* package sets various environment variables required to build the adapter. On Debian/Ubuntu, you'll need to set the variables manually::

    $ export ORACLE_HOME=/usr/lib/oracle/11.2/client64/

   If you get an error installing cx_oracle (``/usr/bin/ld: cannot find -lclntsh``), you may also need to create this link::

    $ sudo ln -s /usr/lib/oracle/11.2/client64/lib/libclntsh.so.11.1 /usr/lib/oracle/11.2/client64/lib/libclntsh.so

#. Create a settings file, the following example seems to work for me::

    DATABASES = {
        'default': {
            'ENGINE': 'django.db.backends.oracle',
            'HOST': '127.0.0.1',
            'PORT': '1521',
            'NAME': 'orcl',
            'USER': 'system',
            'PASSWORD': 'oracle',
            'TEST': {
                'USER': 'django',
                'TBLSPACE': 'django_test',
                'TBLSPACE_TMP': 'django_test_tmp',
            },
        },
        'other': {
            'ENGINE': 'django.db.backends.oracle',
            'HOST': '127.0.0.1',
            'PORT': '1521',
            'NAME': 'orcl',
            'USER': 'system',
            'PASSWORD': 'oracle',
            'TEST': {
                'USER': 'other',
                'TBLSPACE': 'other_test',
                'TBLSPACE_TMP': 'other_test_tmp',
            },
        },
    }

    SECRET_KEY = "django_tests_secret_key"

   As opposed to the XE server whose installation is outlined above, the server provided on the VM image uses ``orcl`` as its SID.

#. Profit::

    $ # may be need on Debian/Ubuntu
    $ export LD_LIBRARY_PATH=/usr/lib/oracle/11.2/client64/lib
    $ # for error "libaio.so.1: cannot open shared object file"
    $ sudo apt-get install libaio1

    $ ./runtests.py --settings=test_oracle
    Creating test database for alias 'default'...
    Creating test user...
    Creating test database for alias 'other'...
    ...
    ----------------------------------------------------------------------
    Ran XXX tests in XXXs

    OK (skipped=X, expected failures=X)
    Destroying test database for alias 'default'...
    Destroying test user...
    Destroying test database tables...
    Destroying test database for alias 'other'...
}}}