1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
.. _postgis:
==================
Installing PostGIS
==================
`PostGIS`__ adds geographic object support to PostgreSQL, turning it
into a spatial database. :ref:`geosbuild`, :ref:`proj4` and
:ref:`gdalbuild` should be installed prior to building PostGIS. You
might also need additional libraries, see `PostGIS requirements`_.
.. note::
The `psycopg2`_ module is required for use as the database adapter
when using GeoDjango with PostGIS.
.. _psycopg2: http://initd.org/psycopg/
.. _PostGIS requirements: http://www.postgis.org/documentation/manual-2.0/postgis_installation.html#id554707
On Debian/Ubuntu, you are advised to install the following packages:
postgresql-x.x, postgresql-x.x-postgis, postgresql-server-dev-x.x,
python-psycopg2 (x.x matching the PostgreSQL version you want to install).
Please also consult platform-specific instructions if you are on :ref:`macosx`
or :ref:`windows`.
Building from source
====================
First download the source archive, and extract::
$ wget http://download.osgeo.org/postgis/source/postgis-2.0.3.tar.gz
$ tar xzf postgis-2.0.3.tar.gz
$ cd postgis-2.0.3
Next, configure, make and install PostGIS::
$ ./configure
Finally, make and install::
$ make
$ sudo make install
$ cd ..
.. note::
GeoDjango does not automatically create a spatial database. Please consult
the section on :ref:`spatialdb_template91` or
:ref:`spatialdb_template_earlier` for more information.
__ http://postgis.refractions.net/
Post-installation
=================
.. _spatialdb_template:
.. _spatialdb_template91:
Creating a spatial database with PostGIS 2.0 and PostgreSQL 9.1+
----------------------------------------------------------------
PostGIS 2 includes an extension for Postgres 9.1+ that can be used to enable
spatial functionality::
$ createdb <db name>
$ psql <db name>
> CREATE EXTENSION postgis;
> CREATE EXTENSION postgis_topology;
No PostGIS topology functionalities are yet available from GeoDjango, so the
creation of the ``postgis_topology`` extension is entirely optional.
.. _spatialdb_template_earlier:
Creating a spatial database template for earlier versions
---------------------------------------------------------
If you have an earlier version of PostGIS or PostgreSQL, the CREATE
EXTENSION isn't available and you need to create the spatial database
using the following instructions.
Creating a spatial database with PostGIS is different than normal because
additional SQL must be loaded to enable spatial functionality. Because of
the steps in this process, it's better to create a database template that
can be reused later.
First, you need to be able to execute the commands as a privileged database
user. For example, you can use the following to become the ``postgres`` user::
$ sudo su - postgres
.. note::
The location *and* name of the PostGIS SQL files (e.g., from
``POSTGIS_SQL_PATH`` below) depends on the version of PostGIS.
PostGIS versions 1.3 and below use ``<pg_sharedir>/contrib/lwpostgis.sql``;
whereas version 1.4 uses ``<sharedir>/contrib/postgis.sql`` and
version 1.5 uses ``<sharedir>/contrib/postgis-1.5/postgis.sql``.
To complicate matters, Debian/Ubuntu distributions have their own separate
directory naming system that might change with time. In this case, use the
:download:`create_template_postgis-debian.sh` script.
The example below assumes PostGIS 1.5, thus you may need to modify
``POSTGIS_SQL_PATH`` and the name of the SQL file for the specific
version of PostGIS you are using.
Once you're a database super user, then you may execute the following commands
to create a PostGIS spatial database template::
$ POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-2.0
# Creating the template spatial database.
$ createdb -E UTF8 template_postgis
$ createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
# Allows non-superusers the ability to create from this template
$ psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
# Loading the PostGIS SQL routines
$ psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql
$ psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
# Enabling users to alter spatial tables.
$ psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;"
$ psql -d template_postgis -c "GRANT ALL ON geography_columns TO PUBLIC;"
$ psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
These commands may be placed in a shell script for later use; for convenience
the following scripts are available:
=============== =============================================
PostGIS version Bash shell script
=============== =============================================
1.3 :download:`create_template_postgis-1.3.sh`
1.4 :download:`create_template_postgis-1.4.sh`
1.5 :download:`create_template_postgis-1.5.sh`
Debian/Ubuntu :download:`create_template_postgis-debian.sh`
=============== =============================================
Afterwards, you may create a spatial database by simply specifying
``template_postgis`` as the template to use (via the ``-T`` option)::
$ createdb -T template_postgis <db name>
.. note::
While the ``createdb`` command does not require database super-user privileges,
it must be executed by a database user that has permissions to create databases.
You can create such a user with the following command::
$ createuser --createdb <user>
PostgreSQL's createdb fails
---------------------------
When the PostgreSQL cluster uses a non-UTF8 encoding, the
:file:`create_template_postgis-*.sh` script will fail when executing
``createdb``::
createdb: database creation failed: ERROR: new encoding (UTF8) is incompatible
with the encoding of the template database (SQL_ASCII)
The `current workaround`__ is to re-create the cluster using UTF8 (back up any
databases before dropping the cluster).
__ http://jacobian.org/writing/pg-encoding-ubuntu/
Managing the database
---------------------
To administer the database, you can either use the pgAdmin III program
(:menuselection:`Start --> PostgreSQL 9.x --> pgAdmin III`) or the
SQL Shell (:menuselection:`Start --> PostgreSQL 9.x --> SQL Shell`).
For example, to create a ``geodjango`` spatial database and user, the following
may be executed from the SQL Shell as the ``postgres`` user::
postgres# CREATE USER geodjango PASSWORD 'my_passwd';
postgres# CREATE DATABASE geodjango OWNER geodjango TEMPLATE template_postgis ENCODING 'utf8';
|
