django1/docs/ref/contrib/gis/install/postgis.txt

176 lines
6.6 KiB
Plaintext

.. _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';