| | 1 | {{{ |
| | 2 | #!text/x-rst |
| | 3 | ============================== |
| | 4 | Preparing an Oracle test setup |
| | 5 | ============================== |
| | 6 | |
| | 7 | **This document is work in progress** |
| | 8 | |
| | 9 | This document attempt to ease the task of running the Django test suite against |
| | 10 | Oracle by: |
| | 11 | |
| | 12 | * Providing a step by step setup guide to achieve that. |
| | 13 | * Hopefully collecting information (best practices, tuning tips) to do that |
| | 14 | as efficiently as possible. chosen is GNU/Debian Linux, things should also work with Ubuntu Linux. |
| | 15 | |
| | 16 | The system isn't going to be dedicated exclusively to run Oracle so we will |
| | 17 | leave things set up so it is necessary to start it manually before a test-debug |
| | 18 | session. |
| | 19 | |
| | 20 | Obtain and install Oracle XE |
| | 21 | ============================ |
| | 22 | |
| | 23 | We will be roughly following the `Oracle installation documentation`_. |
| | 24 | |
| | 25 | #. Download the **oracle-xe-universal_10.2.0.1-1.0_i386.deb** package file from |
| | 26 | http://www.oracle.com/technetwork/database/express-edition/downloads/index.html |
| | 27 | (*Oracle Database 10g Express Edition for Linux x86*). You need to have an |
| | 28 | *Oracle Developer Network* account. |
| | 29 | Contrarily to what is suggested in some places_ I've found the newer `.deb` package |
| | 30 | you can get here_ and installable by using high level Debian/Ubuntu package management |
| | 31 | tools (APT, Aptitude, ...) didn't install things like the ``/etc/init.d/oracle-xe`` init |
| | 32 | script and some files under the ``/usr/lib/oracle`` hierarchy so I went with the older |
| | 33 | package plus dpkg and taking care of dependencies manually. |
| | 34 | |
| | 35 | #. Install the prerequisite packages, if you fail to do so the installation won't |
| | 36 | be :: |
| | 37 | |
| | 38 | $ sudo apt-get install bc libaio1 |
| | 39 | |
| | 40 | #. Make sure you have enough swap space. If you fail to do this, the Oracle |
| | 41 | package installation will abort with an error message about this unmet |
| | 42 | condition. |
| | 43 | |
| | 44 | #. Install the package you downloaded:: |
| | 45 | |
| | 46 | $ sudo dpkg -i oracle-xe-universal_10.2.0.1-1.0_i386.deb |
| | 47 | |
| | 48 | #. Configure the DB engine:: |
| | 49 | |
| | 50 | $ sudo /etc/init.d/oracle-xe configure |
| | 51 | |
| | 52 | It will ask you a serie of questions, namely: |
| | 53 | |
| | 54 | * A TCP port for the Oracle Database XE graphical user interface (default: 8080) |
| | 55 | * A TCP port for the Oracle database listener (default: 1521) |
| | 56 | * A password for the SYS and SYSTEM administrative user accounts. Take note of the value you choose. |
| | 57 | * Whether you want the database to start automatically when the computer starts -- I chose **NO** here, see next step. |
| | 58 | |
| | 59 | #. **Optional** -- Create an alternate init script -- If you've answered NO to the question |
| | 60 | about running the Oracle DB engine automatically on system start then |
| | 61 | it won't be possible to start it manually because that flag is stored |
| | 62 | (among others) in the ``/etc/default/oracle-xe`` configuration file and we |
| | 63 | would be using the same script as the one excuted when the system boots |
| | 64 | (``/etc/init.d/oracle-xe``) that always examines these values. |
| | 65 | |
| | 66 | What we can do is to create a slightly modified ``/etc/init.d/xe`` script |
| | 67 | that ignores that flag and allows us to control the Oracle process at will:: |
| | 68 | |
| | 69 | $ cd /etc/init.d |
| | 70 | $ sudo cp -a oracle-xe xe |
| | 71 | $ sudo patch < /home/myuser/oracle-xe-script.diff |
| | 72 | |
| | 73 | This is the ``oracle-xe-script.diff`` patch file (you can also download it):: |
| | 74 | |
| | 75 | --- oracle-xe 2006-02-24 17:23:15.000000000 -0300 |
| | 76 | +++ xe 2010-11-03 07:58:43.000000000 -0300 |
| | 77 | @@ -596,13 +596,8 @@ |
| | 78 | # See how we were called |
| | 79 | case "$1" in |
| | 80 | start) |
| | 81 | - if test -f "$CONFIGURATION" |
| | 82 | + if test ! -f "$CONFIGURATION" |
| | 83 | then |
| | 84 | - if test "$ORACLE_DBENABLED" != "true" |
| | 85 | - then |
| | 86 | - exit 0 |
| | 87 | - fi |
| | 88 | - else |
| | 89 | echo "Oracle Database 10g Express Edition is not configured. You must run |
| | 90 | '/etc/init.d/oracle-xe configure' as the root user to configure the database." |
| | 91 | exit 0 |
| | 92 | @@ -613,13 +608,8 @@ |
| | 93 | configure |
| | 94 | ;; |
| | 95 | stop) |
| | 96 | - if test -f "$CONFIGURATION" |
| | 97 | + if test ! -f "$CONFIGURATION" |
| | 98 | then |
| | 99 | - if test "$ORACLE_DBENABLED" != "true" |
| | 100 | - then |
| | 101 | - exit 0 |
| | 102 | - fi |
| | 103 | - else |
| | 104 | echo "Oracle Database 10g Express Edition is not configured. You must run |
| | 105 | '/etc/init.d/oracle-xe configure' as the root user to configure the database." |
| | 106 | exit 0 |
| | 107 | |
| | 108 | Now we can start/stop Oracle manually using it:: |
| | 109 | |
| | 110 | $ sudo /etc/init.d/xe start |
| | 111 | Starting Oracle Net Listener. |
| | 112 | Starting Oracle Database 10g Express Edition Instance. |
| | 113 | |
| | 114 | $ sudo /etc/init.d/xe stop |
| | 115 | Shutting down Oracle Database 10g Express Edition Instance. |
| | 116 | Stopping Oracle Net Listener. |
| | 117 | |
| | 118 | (in newer versions of Debian/Ubuntu we can use the shorter version |
| | 119 | ``sudo service xe start``) |
| | 120 | |
| | 121 | #. Make sure the needed Oracle environment vars are set for the client |
| | 122 | libraries (Bash shell):: |
| | 123 | |
| | 124 | $ echo "source /usr/lib/oracle/xe/app/oracle/product/10.2.0/server/bin/oracle_env.sh" >> ~/.bashrc |
| | 125 | $ source /usr/lib/oracle/xe/app/oracle/product/10.2.0/server/bin/oracle_env.sh |
| | 126 | |
| | 127 | #. Access the DB engine administration web app by pointing our Web browser to ``http://localhost:8080/apex`` |
| | 128 | and using the ``SYSTEM`` user and the password you chose above. |
| | 129 | |
| | 130 | #. Create an user to be used for running the tests. (e.g. ``djangotest``) -- Go to *Home > Administration > Database Users > CREATE* |
| | 131 | assing it a password (e.g. ``foo``) |
| | 132 | |
| | 133 | #. Give the user the needed privileges. |
| | 134 | |
| | 135 | * Roles: ``CONNECT``, ``RESOURCE`` and ``DBA`` |
| | 136 | * *Directly Granted System Privileges*: ``CREATE TABLE``, ``CREATE PROCEDURE``, ``CREATE SEQUENCE`` and ``CREATE TARIGGER`` |
| | 137 | |
| | 138 | .. _Oracle installation documentation: http://www.oracle.com/pls/xe102/to_toc?pathname=install.102%2Fb25144%2Ftoc.htm&remark=portal+%28Getting+Started%29 |
| | 139 | .. _places: http://blog.schmehl.info/Debian/oracle-xe |
| | 140 | .. _here: http://oss.oracle.com/debian/dists/unstable/non-free/binary-i386/ |
| | 141 | |
| | 142 | #. We don't need to install the Oracle client stack because we are going to run the Django tests in the same system. |
| | 143 | |
| | 144 | Install cx_Oracle |
| | 145 | ================= |
| | 146 | :: |
| | 147 | |
| | 148 | $ sudo apt-get install python-dev |
| | 149 | $ ... |
| | 150 | |
| | 151 | Create the Django settings file |
| | 152 | =============================== |
| | 153 | :: |
| | 154 | |
| | 155 | $ cat oracle.py |
| | 156 | |
| | 157 | DATABASES = { |
| | 158 | 'default': { |
| | 159 | 'ENGINE': 'django.db.backends.oracle', |
| | 160 | 'NAME': 'xe', |
| | 161 | 'USER': 'djangotest', |
| | 162 | 'PASSWORD': 'foo', |
| | 163 | }, |
| | 164 | 'other': { |
| | 165 | 'ENGINE': 'django.db.backends.oracle', |
| | 166 | 'NAME': 'xeother', |
| | 167 | 'USER': 'djangotest2', |
| | 168 | 'PASSWORD': 'bar', |
| | 169 | #'TEST_USER_CREATE': False, |
| | 170 | 'TEST_TBLSPACE': 'tblspace_other', |
| | 171 | 'TEST_TBLSPACE_TMP': 'tblspace_tmp_other', |
| | 172 | }, |
| | 173 | } |
| | 174 | |
| | 175 | Test things |
| | 176 | =========== |
| | 177 | :: |
| | 178 | |
| | 179 | $ sudo /etc/init.d/xe start |
| | 180 | |
| | 181 | $ ./runtests --settings=oracle.py basic |
| | 182 | |
| | 183 | Creating test database 'default'... |
| | 184 | Creating test user... |
| | 185 | Creating test database 'other'... |
| | 186 | Creating test user... |
| | 187 | .......s... |
| | 188 | ---------------------------------------------------------------------- |
| | 189 | Ran 11 tests in 2.279s |
| | 190 | |
| | 191 | OK (skipped=1) |
| | 192 | Destroying test database 'default'... |
| | 193 | Destroying test user... |
| | 194 | Destroying test database tables... |
| | 195 | Destroying test database 'other'... |
| | 196 | Destroying test user... |
| | 197 | Destroying test database tables... |
| | 198 | |
| | 199 | Notes |
| | 200 | ===== |
| | 201 | |
| | 202 | In my particular case I've implemented this setup by using a KVM virtual machine |
| | 203 | (host syste, is a workstation running Debian unstable *Sid*). The VM got two CPUs, 1 GiB of RAM |
| | 204 | and a 30 GiB hard disk. Platform is GNU/Debian Linux 5.0 aka *Lenny* (stable as of Nov 2010) |
| | 205 | because it still is in its support period and as a bonus contains Python 2.4 in pre-packaged |
| | 206 | form. Things should also work with Ubuntu Linux. |
| | 207 | |
| | 208 | Things to review: |
| | 209 | |
| | 210 | * How muchdoes 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. |
| | 211 | * 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. |
| | 212 | |
| | 213 | To do |
| | 214 | ===== |
| | 215 | |
| | 216 | 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. |
| | 217 | }}} |