| 1 |
================== |
| 2 |
Installing PostGIS |
| 3 |
================== |
| 4 |
|
| 5 |
`PostGIS`_ adds geographic object support to PostgreSQL, turning it |
| 6 |
into a spatial database. :ref:`geosbuild`, :ref:`proj4` and |
| 7 |
:ref:`gdalbuild` should be installed prior to building PostGIS. You |
| 8 |
might also need additional libraries, see `PostGIS requirements`_. |
| 9 |
|
| 10 |
The `psycopg`_ or `psycopg2`_ module is required for use as the database |
| 11 |
adapter when using GeoDjango with PostGIS. |
| 12 |
|
| 13 |
On Debian/Ubuntu, you are advised to install the following packages: |
| 14 |
``postgresql-x``, ``postgresql-x-postgis-3``, ``postgresql-server-dev-x``, |
| 15 |
and ``python3-psycopg3`` (x matching the PostgreSQL version you want to |
| 16 |
install). Alternately, you can `build from source`_. Consult the |
| 17 |
platform-specific instructions if you are on :ref:`macos` or :ref:`windows`. |
| 18 |
|
| 19 |
.. _PostGIS: https://postgis.net/ |
| 20 |
.. _psycopg: https://www.psycopg.org/psycopg3/ |
| 21 |
.. _psycopg2: https://www.psycopg.org/ |
| 22 |
.. _PostGIS requirements: https://postgis.net/docs/postgis_installation.html#install_requirements |
| 23 |
.. _build from source: https://postgis.net/docs/postgis_installation.html#install_short_version |
| 24 |
|
| 25 |
Post-installation |
| 26 |
================= |
| 27 |
|
| 28 |
.. _spatialdb_template: |
| 29 |
|
| 30 |
Creating a spatial database |
| 31 |
--------------------------- |
| 32 |
|
| 33 |
PostGIS includes an extension for PostgreSQL that's used to enable spatial |
| 34 |
functionality: |
| 35 |
|
| 36 |
.. code-block:: shell |
| 37 |
|
| 38 |
$ createdb <db name> |
| 39 |
$ psql <db name> |
| 40 |
> CREATE EXTENSION postgis; |
| 41 |
|
| 42 |
The database user must be a superuser in order to run |
| 43 |
``CREATE EXTENSION postgis;``. The command is run during the :djadmin:`migrate` |
| 44 |
process. An alternative is to use a migration operation in your project:: |
| 45 |
|
| 46 |
from django.contrib.postgres.operations import CreateExtension |
| 47 |
from django.db import migrations |
| 48 |
|
| 49 |
|
| 50 |
class Migration(migrations.Migration): |
| 51 |
operations = [CreateExtension("postgis"), ...] |
| 52 |
|
| 53 |
If you plan to use PostGIS raster functionality, you should also activate the |
| 54 |
``postgis_raster`` extension. You can install the extension using the |
| 55 |
:class:`~django.contrib.postgres.operations.CreateExtension` migration |
| 56 |
operation, or directly by running ``CREATE EXTENSION postgis_raster;``. |
| 57 |
|
| 58 |
GeoDjango does not currently leverage any `PostGIS topology functionality`__. |
| 59 |
If you plan to use those features at some point, you can also install the |
| 60 |
``postgis_topology`` extension by issuing ``CREATE EXTENSION |
| 61 |
postgis_topology;``. |
| 62 |
|
| 63 |
__ https://postgis.net/docs/Topology.html |
| 64 |
|
| 65 |
Managing the database |
| 66 |
--------------------- |
| 67 |
|
| 68 |
To administer the database, you can either use the pgAdmin III program |
| 69 |
(:menuselection:`Start --> PostgreSQL X --> pgAdmin III`) or the SQL Shell |
| 70 |
(:menuselection:`Start --> PostgreSQL X --> SQL Shell`). For example, to create |
| 71 |
a ``geodjango`` spatial database and user, the following may be executed from |
| 72 |
the SQL Shell as the ``postgres`` user: |
| 73 |
|
| 74 |
.. code-block:: psql |
| 75 |
|
| 76 |
postgres# CREATE USER geodjango PASSWORD 'my_passwd'; |
| 77 |
postgres# CREATE DATABASE geodjango OWNER geodjango; |