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

==================
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://postgis.net/docs/manual-2.1/postgis_installation.html#install_requirements

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.1.5.tar.gz
    $ tar xzf postgis-2.1.5.tar.gz
    $ cd postgis-2.1.5

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` for more information.

__ http://postgis.net/

Post-installation
=================

.. _spatialdb_template:
.. _spatialdb_template91:

Creating a spatial database
---------------------------

PostGIS 2 includes an extension for PostgreSQL that's used to enable spatial
functionality::

    $ createdb  <db name>
    $ psql <db name>
    > CREATE EXTENSION postgis;

The database user must be a superuser in order to run
``CREATE EXTENSION postgis;``. The command is run during the :djadmin:`migrate`
process. An alternative is to use a migration operation in your project::

    from django.contrib.postgresql.operations import CreateExtension
    from django.db import migrations

    class Migration(migrations.Migration):

        operations = [
            CreateExtension('postgis'),
            ...
        ]

GeoDjango does not currently leverage any `PostGIS topology functionality`__.
If you plan to use those features at some point, you can also install the
``postgis_topology`` extension by issuing ``CREATE EXTENSION
postgis_topology;``.

__ http://postgis.net/docs/Topology.html

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;