Debian Codegraph @

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

raw
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;