<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Installing PostGIS — Django 1.6.7 documentation</title>
<link rel="stylesheet" href="../../../../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../../../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../../../',
VERSION: '1.6.7',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../../../../_static/jquery.js"></script>
<script type="text/javascript" src="../../../../_static/underscore.js"></script>
<script type="text/javascript" src="../../../../_static/doctools.js"></script>
<link rel="top" title="Django 1.6.7 documentation" href="../../../../index.html" />
<link rel="up" title="GeoDjango Installation" href="index.html" />
<link rel="next" title="Installing Spatialite" href="spatialite.html" />
<link rel="prev" title="Installing Geospatial libraries" href="geolibs.html" />
<script type="text/javascript" src="../../../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../../../templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../../../index.html">Django 1.6.7 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../../../../index.html">Home</a> |
<a title="Table of contents" href="../../../../contents.html">Table of contents</a> |
<a title="Global index" href="../../../../genindex.html">Index</a> |
<a title="Module index" href="../../../../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="geolibs.html" title="Installing Geospatial libraries">previous</a>
|
<a href="../../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="spatialite.html" title="Installing Spatialite">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="ref-contrib-gis-install-postgis">
<div class="section" id="s-installing-postgis">
<span id="s-postgis"></span><span id="installing-postgis"></span><span id="postgis"></span><h1>Installing PostGIS<a class="headerlink" href="#installing-postgis" title="Permalink to this headline">¶</a></h1>
<p><a class="reference external" href="http://postgis.refractions.net/">PostGIS</a> adds geographic object support to PostgreSQL, turning it
into a spatial database. <a class="reference internal" href="geolibs.html#geosbuild"><em>GEOS</em></a>, <a class="reference internal" href="geolibs.html#proj4"><em>PROJ.4</em></a> and
<a class="reference internal" href="geolibs.html#gdalbuild"><em>GDAL</em></a> should be installed prior to building PostGIS. You
might also need additional libraries, see <a class="reference external" href="http://www.postgis.org/documentation/manual-2.0/postgis_installation.html#id554707">PostGIS requirements</a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <a class="reference external" href="http://initd.org/psycopg/">psycopg2</a> module is required for use as the database adaptor
when using GeoDjango with PostGIS.</p>
</div>
<p>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 <a class="reference internal" href="index.html#macosx"><em>Mac OS X</em></a>
or <a class="reference internal" href="index.html#windows"><em>Windows</em></a>.</p>
<div class="section" id="s-building-from-source">
<span id="building-from-source"></span><h2>Building from source<a class="headerlink" href="#building-from-source" title="Permalink to this headline">¶</a></h2>
<p>First download the source archive, and extract:</p>
<div class="highlight-python"><pre>$ 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</pre>
</div>
<p>Next, configure, make and install PostGIS:</p>
<div class="highlight-python"><pre>$ ./configure</pre>
</div>
<p>Finally, make and install:</p>
<div class="highlight-python"><pre>$ make
$ sudo make install
$ cd ..</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">GeoDjango does not automatically create a spatial database. Please consult
the section on <a class="reference internal" href="#spatialdb-template91"><em>Creating a spatial database with PostGIS 2.0 and PostgreSQL 9.1+</em></a> or
<a class="reference internal" href="#spatialdb-template-earlier"><em>Creating a spatial database template for earlier versions</em></a> for more information.</p>
</div>
</div>
<div class="section" id="s-post-installation">
<span id="post-installation"></span><h2>Post-installation<a class="headerlink" href="#post-installation" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-creating-a-spatial-database-with-postgis-2-0-and-postgresql-9-1">
<span id="s-spatialdb-template91"></span><span id="s-spatialdb-template"></span><span id="creating-a-spatial-database-with-postgis-2-0-and-postgresql-9-1"></span><span id="spatialdb-template91"></span><span id="spatialdb-template"></span><h3>Creating a spatial database with PostGIS 2.0 and PostgreSQL 9.1+<a class="headerlink" href="#creating-a-spatial-database-with-postgis-2-0-and-postgresql-9-1" title="Permalink to this headline">¶</a></h3>
<p>PostGIS 2 includes an extension for Postgres 9.1+ that can be used to enable
spatial functionality:</p>
<div class="highlight-python"><pre>$ createdb <db name>
$ psql <db name>
> CREATE EXTENSION postgis;
> CREATE EXTENSION postgis_topology;</pre>
</div>
<p>No PostGIS topology functionalities are yet available from GeoDjango, so the
creation of the <tt class="docutils literal"><span class="pre">postgis_topology</span></tt> extension is entirely optional.</p>
</div>
<div class="section" id="s-creating-a-spatial-database-template-for-earlier-versions">
<span id="s-spatialdb-template-earlier"></span><span id="creating-a-spatial-database-template-for-earlier-versions"></span><span id="spatialdb-template-earlier"></span><h3>Creating a spatial database template for earlier versions<a class="headerlink" href="#creating-a-spatial-database-template-for-earlier-versions" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>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.</p>
<p>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 <tt class="docutils literal"><span class="pre">postgres</span></tt> user:</p>
<div class="highlight-python"><pre>$ sudo su - postgres</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>The location <em>and</em> name of the PostGIS SQL files (e.g., from
<tt class="docutils literal"><span class="pre">POSTGIS_SQL_PATH</span></tt> below) depends on the version of PostGIS.
PostGIS versions 1.3 and below use <tt class="docutils literal"><span class="pre"><pg_sharedir>/contrib/lwpostgis.sql</span></tt>;
whereas version 1.4 uses <tt class="docutils literal"><span class="pre"><sharedir>/contrib/postgis.sql</span></tt> and
version 1.5 uses <tt class="docutils literal"><span class="pre"><sharedir>/contrib/postgis-1.5/postgis.sql</span></tt>.</p>
<p>To complicate matters, Debian/Ubuntu distributions have their own separate
directory naming system that might change with time. In this case, use the
<a class="reference download internal" href="../../../../_downloads/create_template_postgis-debian.sh"><tt class="xref download docutils literal"><span class="pre">create_template_postgis-debian.sh</span></tt></a> script.</p>
<p class="last">The example below assumes PostGIS 1.5, thus you may need to modify
<tt class="docutils literal"><span class="pre">POSTGIS_SQL_PATH</span></tt> and the name of the SQL file for the specific
version of PostGIS you are using.</p>
</div>
<p>Once you’re a database super user, then you may execute the following commands
to create a PostGIS spatial database template:</p>
<div class="highlight-python"><pre>$ 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;"</pre>
</div>
<p>These commands may be placed in a shell script for later use; for convenience
the following scripts are available:</p>
<table class="docutils">
<colgroup>
<col width="25%" />
<col width="75%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">PostGIS version</th>
<th class="head">Bash shell script</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>1.3</td>
<td><a class="reference download internal" href="../../../../_downloads/create_template_postgis-1.3.sh"><tt class="xref download docutils literal"><span class="pre">create_template_postgis-1.3.sh</span></tt></a></td>
</tr>
<tr class="row-odd"><td>1.4</td>
<td><a class="reference download internal" href="../../../../_downloads/create_template_postgis-1.4.sh"><tt class="xref download docutils literal"><span class="pre">create_template_postgis-1.4.sh</span></tt></a></td>
</tr>
<tr class="row-even"><td>1.5</td>
<td><a class="reference download internal" href="../../../../_downloads/create_template_postgis-1.5.sh"><tt class="xref download docutils literal"><span class="pre">create_template_postgis-1.5.sh</span></tt></a></td>
</tr>
<tr class="row-odd"><td>Debian/Ubuntu</td>
<td><a class="reference download internal" href="../../../../_downloads/create_template_postgis-debian.sh"><tt class="xref download docutils literal"><span class="pre">create_template_postgis-debian.sh</span></tt></a></td>
</tr>
</tbody>
</table>
<p>Afterwards, you may create a spatial database by simply specifying
<tt class="docutils literal"><span class="pre">template_postgis</span></tt> as the template to use (via the <tt class="docutils literal"><span class="pre">-T</span></tt> option):</p>
<div class="highlight-python"><pre>$ createdb -T template_postgis <db name></pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>While the <tt class="docutils literal"><span class="pre">createdb</span></tt> 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:</p>
<div class="last highlight-python"><pre>$ createuser --createdb <user></pre>
</div>
</div>
</div>
<div class="section" id="s-postgresql-s-createdb-fails">
<span id="postgresql-s-createdb-fails"></span><h3>PostgreSQL’s createdb fails<a class="headerlink" href="#postgresql-s-createdb-fails" title="Permalink to this headline">¶</a></h3>
<p>When the PostgreSQL cluster uses a non-UTF8 encoding, the
<tt class="file docutils literal"><span class="pre">create_template_postgis-*.sh</span></tt> script will fail when executing
<tt class="docutils literal"><span class="pre">createdb</span></tt>:</p>
<div class="highlight-python"><pre>createdb: database creation failed: ERROR: new encoding (UTF8) is incompatible
with the encoding of the template database (SQL_ASCII)</pre>
</div>
<p>The <a class="reference external" href="http://jacobian.org/writing/pg-encoding-ubuntu/">current workaround</a> is to re-create the cluster using UTF8 (back up any
databases before dropping the cluster).</p>
</div>
<div class="section" id="s-managing-the-database">
<span id="managing-the-database"></span><h3>Managing the database<a class="headerlink" href="#managing-the-database" title="Permalink to this headline">¶</a></h3>
<p>To administer the database, you can either use the pgAdmin III program
(<em class="menuselection">Start ‣ PostgreSQL 9.x ‣ pgAdmin III</em>) or the
SQL Shell (<em class="menuselection">Start ‣ PostgreSQL 9.x ‣ SQL Shell</em>).
For example, to create a <tt class="docutils literal"><span class="pre">geodjango</span></tt> spatial database and user, the following
may be executed from the SQL Shell as the <tt class="docutils literal"><span class="pre">postgres</span></tt> user:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">postgres</span><span class="c"># CREATE USER geodjango PASSWORD 'my_passwd';</span>
<span class="n">postgres</span><span class="c"># CREATE DATABASE geodjango OWNER geodjango TEMPLATE template_postgis ENCODING 'utf8';</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../../../../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Installing PostGIS</a><ul>
<li><a class="reference internal" href="#building-from-source">Building from source</a></li>
<li><a class="reference internal" href="#post-installation">Post-installation</a><ul>
<li><a class="reference internal" href="#creating-a-spatial-database-with-postgis-2-0-and-postgresql-9-1">Creating a spatial database with PostGIS 2.0 and PostgreSQL 9.1+</a></li>
<li><a class="reference internal" href="#creating-a-spatial-database-template-for-earlier-versions">Creating a spatial database template for earlier versions</a></li>
<li><a class="reference internal" href="#postgresql-s-createdb-fails">PostgreSQL’s createdb fails</a></li>
<li><a class="reference internal" href="#managing-the-database">Managing the database</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="geolibs.html">Installing Geospatial libraries</a></li>
<li>Next: <a href="spatialite.html">Installing Spatialite</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../../../../index.html">Django 1.6.7 documentation</a>
<ul><li><a href="../../../index.html">API Reference</a>
<ul><li><a href="../../index.html"><tt class="docutils literal"><span class="pre">contrib</span></tt> packages</a>
<ul><li><a href="../index.html">GeoDjango</a>
<ul><li><a href="index.html">GeoDjango Installation</a>
<ul><li>Installing PostGIS</li></ul>
</li></ul></li></ul></li></ul></li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../../../_sources/ref/contrib/gis/install/postgis.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../../../../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Sep 26, 2014</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="geolibs.html" title="Installing Geospatial libraries">previous</a>
|
<a href="../../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="spatialite.html" title="Installing Spatialite">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
