← Back to branch summary

~ubuntu-branches/ubuntu/quantal/python-django/quantal-security

« back to all changes in this revision

Viewing changes to docs/ref/contrib/gis/testing.txt

  • Committer: Bazaar Package Importer
  • Author(s): Chris Lamb
  • Date: 2010-05-21 07:52:55 UTC
  • mfrom: (1.3.6 upstream)
  • mto: This revision was merged to the branch mainline in revision 28.
  • Revision ID: james.westby@ubuntu.com-20100521075255-ii78v1dyfmyu3uzx
Tags: upstream-1.2
Import upstream version 1.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/ref/contrib/gis/testing.txt
 
1
======================
 
2
Testing GeoDjango Apps
 
3
======================
 
4
 
 
5
.. versionchanged:: 1.2
 
6
 
 
7
In Django 1.2, the addition of :ref:`spatial-backends`
 
8
simplified the process of testing GeoDjango applications.  Specifically, testing
 
9
GeoDjango applications is now the same as :ref:`topics-testing`.
 
10
 
 
11
Included in this documentation are some additional notes and settings
 
12
for :ref:`testing-postgis` and :ref:`testing-spatialite` users.
 
13
 
 
14
.. note::
 
15
 
 
16
    Django 1.1 users are still required to use a custom :setting:`TEST_RUNNER`.
 
17
    See the :ref:`testing-1.1` section for more details.
 
18
 
 
19
.. _testing-postgis:
 
20
 
 
21
PostGIS
 
22
=======
 
23
 
 
24
Settings
 
25
--------
 
26
 
 
27
.. note::
 
28
 
 
29
    The settings below have sensible defaults, and shouldn't require manual setting.
 
30
 
 
31
.. setting:: POSTGIS_TEMPLATE
 
32
 
 
33
``POSTGIS_TEMPLATE``
 
34
^^^^^^^^^^^^^^^^^^^^
 
35
 
 
36
.. versionadded:: 1.1
 
37
 
 
38
.. versionchanged:: 1.2
 
39
 
 
40
This setting may be used to customize the name of the PostGIS template
 
41
database to use.  In Django versions 1.2 and above, it automatically
 
42
defaults to ``'template_postgis'`` (the same name used in the
 
43
:ref:`installation documentation <spatialdb_template>`).
 
44
 
 
45
.. note::
 
46
 
 
47
    Django 1.1 users will still have to define the :setting:`POSTGIS_TEMPLATE`
 
48
    with a value, for example::
 
49
 
 
50
        POSTGIS_TEMPLATE='template_postgis'
 
51
 
 
52
.. setting:: POSTGIS_VERSION
 
53
 
 
54
``POSTGIS_VERSION``
 
55
^^^^^^^^^^^^^^^^^^^
 
56
.. versionadded:: 1.1
 
57
 
 
58
When GeoDjango's spatial backend initializes on PostGIS, it has to perform
 
59
a SQL query to determine the version.  Setting the version manually
 
60
prevents this query to the database::
 
61
 
 
62
    POSTGIS_VERSION=('1.3.6', 1, 3, 6)
 
63
 
 
64
Obtaining Sufficient Privileges
 
65
-------------------------------
 
66
 
 
67
Depending on your configuration, this section describes several methods to
 
68
configure a database user with sufficient privileges to run tests for
 
69
GeoDjango applications on PostgreSQL.  If your
 
70
:ref:`spatial database template <spatialdb_template>`
 
71
was created like in the instructions, then your testing database user
 
72
only needs to have the ability to create databases.  In other configurations,
 
73
you may be required to use a database superuser.
 
74
 
 
75
Create Database User
 
76
^^^^^^^^^^^^^^^^^^^^
 
77
To make database user with the ability to create databases, use the
 
78
following command::
 
79
 
 
80
    $ createuser --createdb -R -S <user_name>
 
81
 
 
82
The ``-R -S`` flags indicate that we do not want the user to have the ability
 
83
to create additional users (roles) or to be a superuser, respectively.
 
84
 
 
85
Alternatively, you may alter an existing user's role from the SQL shell
 
86
(assuming this is done from an existing superuser account)::
 
87
 
 
88
    postgres# ALTER ROLE <user_name> CREATEDB NOSUPERUSER NOCREATEROLE;
 
89
 
 
90
Create Database Superuser
 
91
^^^^^^^^^^^^^^^^^^^^^^^^^
 
92
This may be done at the time the user is created, for example::
 
93
 
 
94
    $ createuser --superuser <user_name>
 
95
 
 
96
Or you may alter the user's role from the SQL shell (assuming this
 
97
is done from an existing superuser account)::
 
98
 
 
99
    postgres# ALTER ROLE <user_name> SUPERUSER;
 
100
 
 
101
 
 
102
Create Local PostgreSQL Database
 
103
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
104
 
 
105
1. Initialize database: ``initdb -D /path/to/user/db``
 
106
 
 
107
2. If there's already a Postgres instance on the machine, it will need
 
108
   to use a different TCP port than 5432. Edit ``postgresql.conf`` (in
 
109
   ``/path/to/user/db``) to change the database port (e.g. ``port = 5433``).
 
110
 
 
111
3. Start this database ``pg_ctl -D /path/to/user/db start``
 
112
 
 
113
Windows
 
114
-------
 
115
On Windows platforms the pgAdmin III utility may also be used as
 
116
a simple way to add superuser privileges to your database user.
 
117
 
 
118
By default, the PostGIS installer on Windows includes a template
 
119
spatial database entitled ``template_postgis``.
 
120
 
 
121
.. _testing-spatialite:
 
122
 
 
123
SpatiaLite
 
124
==========
 
125
 
 
126
.. versionadded:: 1.1
 
127
 
 
128
You will need to download the `initialization SQL`__ script for SpatiaLite::
 
129
 
 
130
    $ wget http://www.gaia-gis.it/spatialite/init_spatialite-2.3.zip
 
131
    $ unzip init_spatialite-2.3.zip
 
132
 
 
133
If ``init_spatialite-2.3.sql`` is in the same path as your project's ``manage.py``,
 
134
then all you have to do is::
 
135
 
 
136
    $ python manage.py test 
 
137
 
 
138
Settings
 
139
--------
 
140
 
 
141
.. setting:: SPATIALITE_SQL
 
142
 
 
143
``SPATIALITE_SQL``
 
144
^^^^^^^^^^^^^^^^^^
 
145
.. versionadded:: 1.1
 
146
 
 
147
By default, the GeoDjango test runner looks for the SpatiaLite SQL in the
 
148
same directory where it was invoked (by default the same directory where
 
149
``manage.py`` is located).  If you want to use a different location, then
 
150
you may add the following to your settings::
 
151
 
 
152
    SPATIALITE_SQL='/path/to/init_spatialite-2.3.sql'
 
153
 
 
154
__ http://www.gaia-gis.it/spatialite/init_spatialite-2.3.zip
 
155
 
 
156
.. _testing-1.1:
 
157
 
 
158
Testing GeoDjango Applications in 1.1
 
159
=====================================
 
160
 
 
161
In Django 1.1, to accommodate the extra steps required to scaffalod a
 
162
spatial database automatically, a test runner customized for GeoDjango
 
163
must be used.  To use this runner, configure :setting:`TEST_RUNNER` as follows::
 
164
 
 
165
    TEST_RUNNER='django.contrib.gis.tests.run_tests'
 
166
 
 
167
.. note::
 
168
 
 
169
    In order to create a spatial database, the :setting:`DATABASE_USER` setting
 
170
    (or :setting:`TEST_DATABASE_USER`, if optionally defined on Oracle) requires
 
171
    elevated privileges.  When using PostGIS or MySQL, the database user 
 
172
    must have at least the ability to create databases.  When testing on Oracle,
 
173
    the user should be a superuser.
 
174
 
 
175
GeoDjango Test Suite
 
176
====================
 
177
 
 
178
To run GeoDjango's own internal test suite, configure the
 
179
:setting:`TEST_RUNNER` setting as follows::
 
180
 
 
181
    TEST_RUNNER='django.contrib.gis.tests.run_gis_tests'