<?xml version="1.0" encoding="UTF-8"?>
<chapter id="postgis_installation">
  <title>PostGIS Installation</title>

  <para>
	This chapter details the steps required to install PostGIS.
  </para>

  <sect1 id="install_short_version">
	<title>Short Version</title>
	<para>To compile assuming you have all the dependencies in your search path:</para>
	<programlisting>tar xvfz postgis-&last_release_version;.tar.gz
cd postgis-&last_release_version;
./configure
make
make install</programlisting>
	<para>Once postgis is installed, it needs to be enabled in each individual database you want to use it in.</para>
	<note><para>The raster support is currently optional, but installed by default. For enabling using the PostgreSQL 9.1+ extensions model raster is required. Using the extension enable process is preferred and more user-friendly. To spatially enable your database:</para></note>
	<programlisting>psql -d yourdatabase -c "CREATE EXTENSION postgis;"
psql -d yourdatabase -c "CREATE EXTENSION postgis_topology;"
-- if you built with sfcgal support --
psql -d yourdatabase -c "CREATE EXTENSION postgis_sfcgal;"

-- if you want to install tiger geocoder --
psql -d yourdatabase -c "CREATE EXTENSION fuzzystrmatch"
psql -d yourdatabase -c "CREATE EXTENSION postgis_tiger_geocoder;"

-- if you installed with pcre
-- you should have address standardizer extension as well
psql -d yourdatabase -c "CREATE EXTENSION address_standardizer;"
</programlisting>


	<para>Please refer to <xref linkend="make_install_postgis_extensions" /> for more details about querying installed/available extensions and upgrading extensions, or switching from a non-extension install to an extension install.</para>

	<para>For those running who decided for some reason not to compile with raster support, or just are old-fashioned, here are longer more painful instructions for you:</para>
	<para>All the .sql files once installed will be installed in share/contrib/postgis-&last_minor_version; folder
		of your PostgreSQL install</para>

	<programlisting>createdb yourdatabase
createlang plpgsql yourdatabase
psql -d yourdatabase -f postgis.sql
psql -d yourdatabase -f postgis_comments.sql
psql -d yourdatabase -f spatial_ref_sys.sql
psql -d yourdatabase -f topology.sql
psql -d yourdatabase -f topology_comments.sql

-- only if you compiled with raster (GDAL)
psql -d yourdatabase -f rtpostgis.sql
psql -d yourdatabase -f raster_comments.sql

--if you built with sfcgal support --
psql -d yourdatabase -f sfcgal.sql
psql -d yourdatabase -f sfcgal_comments.sql
</programlisting>

	<para>
	  The rest of this chapter goes into detail each of the above installation
	  steps.
	</para>

	<para>As of PostGIS 2.1.3, out-of-db rasters and all raster drivers are disabled by default. In order to re-enable these, you need to set the following environment variables
	<varname>POSTGIS_GDAL_ENABLED_DRIVERS</varname> and <varname>POSTGIS_ENABLE_OUTDB_RASTERS</varname> in the server environment. For PostGIS 2.2, you can use the more cross-platform approach of setting the corresponding <xref linkend="PostGIS_GUC" />.</para>

	<para>If you want to enable offline raster:</para>
	<programlisting>POSTGIS_ENABLE_OUTDB_RASTERS=1</programlisting>
	<para>Any other setting or no setting at all will disable out of db rasters.</para>
	<para>In order to enable all GDAL drivers available in your GDAL install, set this environment variable as follows</para>
	<programlisting>POSTGIS_GDAL_ENABLED_DRIVERS=ENABLE_ALL</programlisting>
	<para>If you want to only enable specific drivers, set your environment variable as follows:</para>
	<programlisting>POSTGIS_GDAL_ENABLED_DRIVERS="GTiff PNG JPEG GIF XYZ"</programlisting>

	<note><para>If you are on windows, do not quote the driver list</para></note>

	<para>Setting environment variables varies depending on OS.  For PostgreSQL installed on Ubuntu or Debian via apt-postgresql, the preferred way is to
	edit <filename>/etc/postgresql/<replaceable>10</replaceable>/<replaceable>main</replaceable>/environment</filename> where 9.3 refers to version of PostgreSQL and main refers to the cluster.</para>

	<para>On windows, if you are running as a service, you can set via System variables which for Windows 7 you can get to by right-clicking on Computer-&gt;Properties Advanced System Settings or in explorer navigating to <varname>Control Panel\All Control Panel Items\System</varname>.
	Then clicking <emphasis>Advanced System Settings -&gt;Advanced->Environment Variables</emphasis> and adding new system variables.</para>
	<para>After you set the environment variables, you'll need to restart your PostgreSQL service for the changes to take effect.</para>
  </sect1>

  <sect1 id="install_requirements">
	<title>Install Requirements</title>

	<para>
	  PostGIS has the following requirements for building and usage:
	</para>

	<para>
	  <emphasis role="bold">Required</emphasis>
	</para>

	<itemizedlist>
	  <listitem>
		<para>
		  PostgreSQL &min_postgres_version; or higher. A complete installation
		  of PostgreSQL (including server headers) is required. PostgreSQL
		  is available from
		  <ulink url="http://www.postgresql.org">
			http://www.postgresql.org
		  </ulink>
		  .
		</para>
		<para>For a full PostgreSQL / PostGIS support matrix and PostGIS/GEOS support matrix refer to
			<ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS">http://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS</ulink>
		</para>
	  </listitem>

	  <listitem>
		<para>
		  GNU C compiler (<filename>gcc</filename>). Some other ANSI C compilers
		  can be used to compile PostGIS, but we find far fewer problems when
		  compiling with <filename>gcc</filename>.
		</para>
	  </listitem>

	  <listitem>
		<para>
		  GNU Make (<filename>gmake</filename> or <filename>make</filename>).
		  For many systems, GNU <filename>make</filename> is the default version
		  of make. Check the version by invoking <filename>make -v</filename>.
		  Other versions of <filename>make</filename> may not process the
		  PostGIS <filename>Makefile</filename> properly.
		</para>
	  </listitem>

	  <listitem>
		<para>
		  Proj4 reprojection library, version 4.9.0 or greater. Proj4 4.9 or above is needed to take advantage of improved geodetic.
			The Proj4 library is used to provide coordinate reprojection support within
		  PostGIS. Proj4 is available for download from
		  <ulink url="http://trac.osgeo.org/proj/">
			http://trac.osgeo.org/proj/
		  </ulink>
		  .
		</para>
	  </listitem>

	  <listitem>
		<para>
		  GEOS geometry library, version 3.5 or greater, but GEOS 3.7+ is recommended to take full advantage of all the new functions and features.  You should have at least GEOS 3.5,
			without which you will be missing some major enhancements such as <xref linkend="ST_ClipByBox2D" /> and <xref linkend="ST_Subdivide" />. GEOS is available for download from
		  <ulink url="http://trac.osgeo.org/geos/">
			http://trac.osgeo.org/geos/
		  </ulink> and 3.5+ is backward-compatible with older versions so fairly safe to upgrade.
		</para>
	  </listitem>
	  <listitem>
		<para>
		  LibXML2, version 2.5.x or higher. LibXML2 is currently used in some imports
		  functions (ST_GeomFromGML and ST_GeomFromKML). LibXML2 is available for download from
		  <ulink url="http://xmlsoft.org/downloads.html">http://xmlsoft.org/downloads.html</ulink>.
		</para>
	  </listitem>
	  <listitem>
		<para>
		  JSON-C, version 0.9 or higher. JSON-C is currently used to import GeoJSON via the
		  function ST_GeomFromGeoJson. JSON-C is available for download from
		  <ulink url="https://github.com/json-c/json-c/releases">https://github.com/json-c/json-c/releases/</ulink>.
		</para>
	  </listitem>

	  <listitem>
		<para>
		  GDAL, version 1.8 or higher (1.9 or higher is strongly recommended since some things will not work well or behavior differently with lower versions).  This is required for raster support and to be able to install with <code>CREATE EXTENSION postgis</code> so highly recommended for those running 9.1+.
		  <ulink url="http://trac.osgeo.org/gdal/wiki/DownloadSource">http://trac.osgeo.org/gdal/wiki/DownloadSource</ulink>.
		</para>
	  </listitem>

		<listitem>
		<para>
		  If compiling with PostgreSQL+JIT, LLVM version &gt;=6 is required
		  <ulink url="https://trac.osgeo.org/postgis/ticket/4125">https://trac.osgeo.org/postgis/ticket/4125</ulink>.
		</para>
	  </listitem>
	</itemizedlist>

	<para>
	  <emphasis role="bold">Optional</emphasis>
	</para>

	<itemizedlist>
	  <listitem>
		<para>
		  GDAL (pseudo optional) only if you don't want raster and don't care about installing with <code>CREATE EXTENSION postgis</code> can you leave it out.
		  Keep in mind other extensions may have a requires postgis extension which will prevent you from installing them unless you install postgis as an extension. So it is highly recommended you compile with GDAL support.
		</para>
		<para>Also make sure to enable the drivers you want to use as described in <xref linkend="install_short_version" />.</para>
	  </listitem>
	  <listitem>
		<para>
		  GTK (requires GTK+2.0, 2.8+) to compile the shp2pgsql-gui shape file loader.
		  <ulink url="http://www.gtk.org/">
			http://www.gtk.org/
		  </ulink>
		  .
		</para>
	  </listitem>

	  <listitem>
		<para>
                  SFCGAL, version 1.1 (or higher) could be used to provide additional 2D and 3D advanced analysis functions to PostGIS cf <xref linkend="reference_sfcgal" />. And also allow to use SFCGAL rather than GEOS for some 2D functions provided by both backends (like ST_Intersection or ST_Area, for instance). A PostgreSQL configuration variable <code>postgis.backend</code> allow end user to control which backend he want to use if SFCGAL is installed (GEOS by default). Nota: SFCGAL 1.2 require at least CGAL 4.3 and Boost 1.54 (cf: <ulink url="http://oslandia.github.io/SFCGAL/installation.html">http://oslandia.github.io/SFCGAL/installation.html</ulink>)

		  <ulink url="https://github.com/Oslandia/SFCGAL">https://github.com/Oslandia/SFCGAL</ulink>.
		</para>
	  </listitem>

	 <listitem>
			<para>
				In order to build the <xref linkend="Address_Standardizer" /> you will also need PCRE <ulink url="http://www.pcre.org">http://www.pcre.org</ulink> (which generally is already installed on nix systems).  <code>Regex::Assemble</code> perl CPAN package is only needed if you want to rebuild the data encoded in <filename>parseaddress-stcities.h</filename>.
				<xref linkend="Address_Standardizer" /> will automatically be built if it detects a PCRE library, or you pass in a valid <varname>--with-pcre-dir=/path/to/pcre</varname> during configure.
			</para>
		</listitem>

		<listitem>
			<para>
			  To enable ST_AsMVT protobuf-c library (for usage) and the protoc-c compiler (for building) are required.
				Also, pkg-config is required to verify the correct minimum version of protobuf-c.
				See <ulink url="https://github.com/protobuf-c/protobuf-c">protobuf-c</ulink>.
			</para>
		</listitem>

	  <listitem>
		<para>
		 CUnit (<filename>CUnit</filename>). This is needed for regression testing. <ulink url="http://cunit.sourceforge.net/">http://cunit.sourceforge.net/</ulink>
		</para>
	  </listitem>

	  <listitem>
		<para>
		  DocBook (<filename>xsltproc</filename>) is required for building the
		  documentation. Docbook is available from
		  <ulink url="http://www.docbook.org/">
			http://www.docbook.org/
		  </ulink>
		  .
		</para>
	  </listitem>

	  <listitem>
		<para>
		  DBLatex (<filename>dblatex</filename>) is required for building the
		  documentation in PDF format. DBLatex is available from
		  <ulink url="http://dblatex.sourceforge.net/">
			http://dblatex.sourceforge.net/
		  </ulink>
		  .
		</para>
	  </listitem>

	  <listitem>
		<para>
		  ImageMagick (<filename>convert</filename>) is required to generate the
		  images used in the documentation. ImageMagick is available from
		  <ulink url="http://www.imagemagick.org/">
			http://www.imagemagick.org/
		  </ulink>
		  .
		</para>
	  </listitem>
	</itemizedlist>
  </sect1>

  <sect1 id="install_getting_source">
	<title>Getting the Source</title>

	<para>
	  Retrieve the PostGIS source archive from the downloads website
	  <ulink url="&postgis_download_url;">
		&postgis_download_url;
	  </ulink>
	</para>

	<programlisting>wget &postgis_download_url;
tar -xvzf postgis-&last_release_version;.tar.gz</programlisting>

	<para>
	  This will create a directory called
	  <varname>postgis-&last_release_version;</varname> in the current working
	  directory.
	</para>

	<para>
	  Alternatively, checkout the source from the
	  <ulink url="http://subversion.apache.org/">
		svn
	  </ulink>
	  repository
	  <ulink url="http://svn.osgeo.org/postgis/trunk/">
		http://svn.osgeo.org/postgis/trunk/
	  </ulink>
	  .
	</para>

	<programlisting>svn checkout http://svn.osgeo.org/postgis/trunk/ postgis-&last_release_version;</programlisting>

	<para>
	  Change into the newly created
	  <varname>postgis-&last_release_version;</varname> directory to continue
	  the installation.
	</para>
  </sect1>

  <sect1 id="PGInstall">
	<title>Compiling and Install from Source: Detailed</title>

	<note>
	  <para>
		Many OS systems now include pre-built packages for PostgreSQL/PostGIS.
		In many cases compilation is only necessary if you want the most
		bleeding edge versions or you are a package maintainer.
	  </para>
	  <para>This section includes general compilation instructions, if you are compiling for Windows etc
		or another OS, you may find additional more detailed help at <ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiInstall">PostGIS User contributed compile guides</ulink> and <ulink url="http://trac.osgeo.org/postgis/wiki/DevWikiMain">PostGIS Dev Wiki</ulink>.</para>
	  <para>Pre-Built Packages for various OS are listed in <ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiPackages">PostGIS Pre-built Packages</ulink></para>
	  <para>If you are a windows user, you can get stable builds via Stackbuilder or <ulink url="https://postgis.net/windows_downloads">PostGIS Windows download site</ulink>
	  We also have <ulink url="https://postgis.net/windows_downloads">very bleeding-edge windows experimental builds</ulink> that are built usually once or twice a week or whenever anything exciting happens.  You can
	  use these to experiment with the in progress releases of PostGIS</para>
	</note>

	<para>
	  The PostGIS module is an extension to the PostgreSQL backend server. As
	  such, PostGIS &last_release_version; <emphasis>requires</emphasis> full
	  PostgreSQL server headers access in order to compile. It can be built
	  against PostgreSQL versions &min_postgres_version; or higher. Earlier
	  versions of PostgreSQL are <emphasis>not</emphasis> supported.
	</para>

	<para>
	  Refer to the PostgreSQL installation guides if you haven't already
	  installed PostgreSQL.
	  <ulink url="http://www.postgresql.org">
		http://www.postgresql.org
	  </ulink>
	  .
	</para>

	<note>
	  <para>
		For GEOS functionality, when you install PostgresSQL you may need to
		explicitly link PostgreSQL against the standard C++ library:
	  </para>

	  <programlisting>LDFLAGS=-lstdc++ ./configure [YOUR OPTIONS HERE]</programlisting>

	  <para>
		This is a workaround for bogus C++ exceptions interaction with older
		development tools. If you experience weird problems (backend
		unexpectedly closed or similar things) try this trick. This will require
		recompiling your PostgreSQL from scratch, of course.
	  </para>
	</note>

	<para>
	  The following steps outline the configuration and compilation of the
	  PostGIS source. They are written for Linux users and will not work on
	  Windows or Mac.
	</para>

	<sect2 id="installation_configuration">
	  <title>Configuration</title>

	  <para>
		As with most linux installations, the first step is to generate the
		Makefile that will be used to build the source code. This is done by
		running the shell script
	  </para>

	  <para>
		<command>./configure</command>
	  </para>

	  <para>
		With no additional parameters, this command will attempt to
		automatically locate the required components and libraries needed to
		build the PostGIS source code on your system. Although this is the most
		common usage of <command>./configure</command>, the script accepts
		several parameters for those who have the required libraries and
		programs in non-standard locations.
	  </para>

	  <para>
		The following list shows only the most commonly used parameters. For a
		complete list, use the <command>--help</command> or
		<command>--help=short</command> parameters.
	  </para>

	  <variablelist>
		<varlistentry>
		  <term><command>--prefix=PREFIX</command></term>
		  <listitem>
			<para>
			  This is the location the PostGIS libraries and SQL scripts will be
			  installed to. By default, this location is the same as the
			  detected PostgreSQL installation.
			</para>

			<caution>
			  <para>
				This parameter is currently broken, as the package will only
				install into the PostgreSQL installation directory. Visit
				<ulink url="http://trac.osgeo.org/postgis/ticket/635">
				  http://trac.osgeo.org/postgis/ticket/635
				</ulink>
				to track this bug.
			  </para>
			</caution>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term><command>--with-pgconfig=FILE</command></term>
		  <listitem>
			<para>
			  PostgreSQL provides a utility called <command>pg_config</command>
			  to enable extensions like PostGIS to locate the PostgreSQL
			  installation directory. Use this parameter
			  (<command>--with-pgconfig=/path/to/pg_config</command>) to
			  manually specify a particular PostgreSQL installation that PostGIS
			  will build against.
			</para>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term><command>--with-gdalconfig=FILE</command></term>
		  <listitem>
			<para>
			  GDAL, a required library, provides functionality needed for raster support
			  <command>gdal-config</command> to enable software installations to
			  locate the GDAL installation directory. Use this parameter
			  (<command>--with-gdalconfig=/path/to/gdal-config</command>) to
			  manually specify a particular GDAL installation that PostGIS will
			  build against.
			</para>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term><command>--with-geosconfig=FILE</command></term>
		  <listitem>
			<para>
			  GEOS, a required geometry library, provides a utility called
			  <command>geos-config</command> to enable software installations to
			  locate the GEOS installation directory. Use this parameter
			  (<command>--with-geosconfig=/path/to/geos-config</command>) to
			  manually specify a particular GEOS installation that PostGIS will
			  build against.
			</para>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term><command>--with-xml2config=FILE</command></term>
		  <listitem>
			<para>
			  LibXML is the library required for doing GeomFromKML/GML processes.
			  It normally is found if you have libxml installed, but if not or you want
			  a specific version used, you'll need to point PostGIS at a specific
			  <filename>xml2-config</filename> confi file to enable software installations to
			  locate the LibXML installation directory. Use this parameter
			  (<command>>--with-xml2config=/path/to/xml2-config</command>) to
			  manually specify a particular LibXML installation that PostGIS will
			  build against.
			</para>
		  </listitem>
		</varlistentry>



		<varlistentry>
		  <term><command>--with-projdir=DIR</command></term>
		  <listitem>
			<para>
			  Proj4 is a reprojection library required by PostGIS. Use this
			  parameter (<command>--with-projdir=/path/to/projdir</command>) to
			  manually specify a particular Proj4 installation directory that
			  PostGIS will build against.
			</para>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term><command>--with-libiconv=DIR</command></term>
		  <listitem>
			<para>
			  Directory where iconv is installed.
			</para>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term><command>--with-jsondir=DIR</command></term>
		  <listitem>
			<para>
			  <ulink url="http://oss.metaparadigm.com/json-c/">JSON-C</ulink> is an MIT-licensed JSON library required by PostGIS ST_GeomFromJSON support. Use this
			  parameter (<command>--with-jsondir=/path/to/jsondir</command>) to
			  manually specify a particular JSON-C installation directory that
			  PostGIS will build against.
			</para>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term><command>--with-pcredir=DIR</command></term>
		  <listitem>
			<para>
			  <ulink url="http://www.pcre.org/">PCRE</ulink> is an BSD-licensed Perl Compatible Regular Expression library required by address_standardizer extension. Use this
			  parameter (<command>--with-pcredir=/path/to/pcredir</command>) to
			  manually specify a particular PCRE installation directory that
			  PostGIS will build against.
			</para>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term><command>--with-gui</command></term>
		  <listitem>
			<para>
			  Compile the data import GUI (requires GTK+2.0).  This will create shp2pgsql-gui graphical interface
			  to shp2pgsql.
			</para>
		  </listitem>
		</varlistentry>
		<varlistentry>
		  <term><command>--with-raster</command></term>
		  <listitem>
			<para>
			  Compile with raster support.  This will build rtpostgis-&last_release_version; library and rtpostgis.sql file.  This may not
			  be required in final release as plan is to build in raster support by default.
			</para>
		  </listitem>
		</varlistentry>
		<varlistentry>
		  <term><command>--without-topology</command></term>
		  <listitem>
			<para>
			  Disable topology support. There is no corresponding library
			  as all logic needed for topology is in postgis-&last_release_version; library.
			</para>
		  </listitem>
		</varlistentry>
		<varlistentry>
		  <term><command>--with-gettext=no</command></term>
		  <listitem>
			<para>
			  By default PostGIS will try to detect gettext support and compile with it, however if you run into incompatibility issues that
			  cause breakage of loader, you can disable it entirely with this command.  Refer to ticket <ulink url="http://trac.osgeo.org/postgis/ticket/748">http://trac.osgeo.org/postgis/ticket/748</ulink> for an example issue solved by configuring with this.
			  NOTE: that you aren't missing much by turning this off.  This is used for international help/label support for the GUI loader which is not yet documented
			  and still experimental.
			</para>
		  </listitem>
		</varlistentry>
		<varlistentry>
		  <term><command>--with-sfcgal=PATH</command></term>
		  <listitem>
			<para>
			  By default PostGIS will not install with sfcgal support without this switch.
			  <varname>PATH</varname> is an optional argument that allows to specify an alternate PATH to sfcgal-config.
			</para>
		  </listitem>
		</varlistentry>
	  </variablelist>
	  <note>
		<para>
		  If you obtained PostGIS from the SVN
		  <ulink url="http://svn.osgeo.org/postgis/trunk/">
			repository
		  </ulink>
		  , the first step is really to run the script
		</para>

		<para>
		  <command>./autogen.sh</command>
		</para>

		<para>
		  This script will generate the <command>configure</command> script that
		  in turn is used to customize the installation of PostGIS.
		</para>

		<para>
		  If you instead obtained PostGIS as a tarball, running
		  <command>./autogen.sh</command> is not necessary as
		  <command>configure</command> has already been generated.
		</para>
	  </note>
	</sect2>

	<sect2>
	  <title>Building</title>

	  <para>
		Once the Makefile has been generated, building PostGIS is as simple as
		running
	  </para>

	  <para>
		<command>make</command>
	  </para>

	  <para>
		The last line of the output should be "<code>PostGIS was built
		successfully. Ready to install.</code>"
	  </para>

	  <para>
		As of PostGIS v1.4.0, all the functions have comments generated from the
		documentation. If you wish to install these comments into your spatial
		databases later, run the command which requires docbook.  The postgis_comments.sql and other
		package comments files raster_comments.sql, topology_comments.sql are
			also packaged in the tar.gz distribution in the doc folder so no need to make comments
			if installing from the tar ball.  Comments are also included as part of the CREATE EXTENSION install.
	  </para>

	  <para>
		<command>make comments</command>
	  </para>

	  <para>
		Introduced in PostGIS 2.0. This generates html cheat sheets suitable for quick reference or for student handouts.
		This requires xsltproc to build and will generate 4 files in doc folder <filename>topology_cheatsheet.html</filename>, <filename>tiger_geocoder_cheatsheet.html</filename>,
			<filename>raster_cheatsheet.html</filename>, <filename>postgis_cheatsheet.html</filename>
	  </para>
	  <para>You can download some pre-built ones available in html and pdf from <ulink url="http://www.postgis.us/study_guides">PostGIS / PostgreSQL Study Guides</ulink></para>

	  <para>
		<command>make cheatsheets</command>
	  </para>
	</sect2>

	<sect2 id="make_install_postgis_extensions">
	  <title>Building PostGIS Extensions and Deploying them</title>

	  <para>
		The PostGIS extensions are built and installed automatically if you are using PostgreSQL 9.1+.
	  </para>
	  <para>If you are building from source repository, you need to build the function descriptions first. These get built if you have docbook installed. You can also manually build with the statement:
    </para>
	  <para>
	  <command>make comments</command>
    </para>
	  <para>Building the comments is not necessary if you are building from a release tar ball since these are packaged pre-built with the tar ball already.</para>
	  <para>If you are building against PostgreSQL 9.1, the extensions should automatically build as part of the make install process.  You can if needed build from the extensions
	  folders or copy files if you need them on a different server. </para>
	  <programlisting>cd extensions
cd postgis
make clean
make
make install
cd ..
cd postgis_topology
make clean
make
make install
cd ..
cd postgis_sfcgal
make clean
make
make install

cd ..
cd address_standardizer
make clean
make
make install
make installcheck

cd ..
cd postgis_tiger_geocoder
make clean
make
make install
make installcheck
	  </programlisting>
	  <para>The extension files will always be the same for the same version of PostGIS regardless of OS, so it is fine to copy over the extension files from one OS to another as long as you
	  have the PostGIS binaries already installed on your servers. </para>
		<para>If you want to install the extensions manually on a separate server different from your development,
		You need to copy the following files from the extensions folder into the <filename>PostgreSQL / share / extension</filename> folder
		of your PostgreSQL install as well as the needed binaries for regular PostGIS if you don't have them already on the server.
	  </para>

	  <itemizedlist>
		<listitem>
		  <para>
			These are the control files that denote information such as the version of the extension to install if not specified.
			<filename>postgis.control, postgis_topology.control</filename>.
		  </para>
		</listitem>
		<listitem>
		  <para>
			All the files in the /sql folder of each extension.  Note that these need to be copied to the root of the PostgreSQL share/extension folder
			<filename>extensions/postgis/sql/*.sql</filename>, <filename>extensions/postgis_topology/sql/*.sql</filename>
		  </para>
		</listitem>
	 </itemizedlist>
	 <para>Once you do that, you should see <varname>postgis</varname>, <varname>postgis_topology</varname> as available extensions in PgAdmin -> extensions.</para>
	 <para>If you are using psql, you can verify that the extensions are installed by running this query:</para>
	 <programlisting>SELECT name, default_version,installed_version
FROM pg_available_extensions WHERE name LIKE 'postgis%' or name LIKE 'address%';

             name             | default_version | installed_version
------------------------------+-----------------+-------------------
 address_standardizer         | &last_release_version;         | &last_release_version;
 address_standardizer_data_us | &last_release_version;         | &last_release_version;
 postgis                      | &last_release_version;         | &last_release_version;
 postgis_sfcgal               | &last_release_version;         |
 postgis_tiger_geocoder       | &last_release_version;         | &last_release_version;
 postgis_topology             | &last_release_version;         |
(6 rows)</programlisting>

<para>If you have the extension installed in the database you are querying, you'll see mention in the <varname>installed_version</varname> column.
If you get no records back, it means you don't have postgis extensions installed on the server at all.  PgAdmin III 1.14+ will also provide this information
in the <varname>extensions</varname> section of the database browser tree and will even allow upgrade or uninstall by right-clicking.</para>

<para>If you have the extensions available, you can install postgis extension in your database of choice by either using pgAdmin extension interface or running these sql commands:</para>
<programlisting>CREATE EXTENSION postgis;
CREATE EXTENSION postgis_sfcgal;
CREATE EXTENSION fuzzystrmatch; --needed for postgis_tiger_geocoder
--optional used by postgis_tiger_geocoder, or can be used standalone
CREATE EXTENSION address_standardizer;
CREATE EXTENSION address_standardizer_data_us;
CREATE EXTENSION postgis_tiger_geocoder;
CREATE EXTENSION postgis_topology;</programlisting>

<para>In psql you can use to see what versions you have installed and also what schema they are installed. </para>
<programlisting>\connect mygisdb
\x
\dx postgis*</programlisting>

<screen>List of installed extensions
-[ RECORD 1 ]-------------------------------------------------
-
Name        | postgis
Version     | &last_release_version;
Schema      | public
Description | PostGIS geometry, geography, and raster spat..
-[ RECORD 2 ]-------------------------------------------------
-
Name        | postgis_tiger_geocoder
Version     | &last_release_version;
Schema      | tiger
Description | PostGIS tiger geocoder and reverse geocoder
-[ RECORD 3 ]-------------------------------------------------
-
Name        | postgis_topology
Version     | &last_release_version;
Schema      | topology
Description | PostGIS topology spatial types and functions</screen>

<warning><para>Extension tables <varname>spatial_ref_sys</varname>, <varname>layer</varname>, <varname>topology</varname> can not be explicitly backed up.  They can only
be backed up when the respective <varname>postgis</varname> or <varname>postgis_topology</varname> extension is backed up, which only seems to happen when you backup the whole database.
As of PostGIS 2.0.1, only srid records not packaged with PostGIS are backed up when the database is backed up so don't go around changing srids we package and expect your changes to be there. Put in a ticket if you find an issue.  The structures of extension tables are never backed up since they are created with <code>CREATE EXTENSION</code>
and assumed to be the same for a given version of an extension. These behaviors are built into the current PostgreSQL extension model, so nothing we can do about it.</para></warning>

<para>If you installed &last_release_version;, without using our wonderful extension system, you can change it to be extension based by first upgrading to the latest micro version running the upgrade scripts: <filename>postgis_upgrade_22_minor.sql</filename>,<filename>raster_upgrade_22_minor.sql</filename>,<filename>topology_upgrade_22_minor.sql</filename>.</para>
<para>If you installed postgis without raster support, you'll need to install raster support first (using the full <filename>rtpostgis.sql</filename></para>
<para>Then you can run the below commands to package the functions in their respective extension.</para>
<programlisting>CREATE EXTENSION postgis FROM unpackaged;
CREATE EXTENSION postgis_topology FROM unpackaged;
CREATE EXTENSION postgis_tiger_geocoder FROM unpackaged;</programlisting>

	</sect2>


	<sect2>
	  <title>Testing</title>

	  <para>
		If you wish to test the PostGIS build, run
	  </para>

	  <para>
		<command>make check</command>
	  </para>

	  <para>
		The above command will run through various checks and regression tests
		using the generated library against an actual PostgreSQL database.
	  </para>

	  <note>
		<para>
		  If you configured PostGIS using non-standard PostgreSQL, GEOS, or
		  Proj4 locations, you may need to add their library locations to the
		  LD_LIBRARY_PATH environment variable.
		</para>
	  </note>

	  <caution>
		<para>
		  Currently, the <command>make check</command> relies on the
		  <code>PATH</code> and <code>PGPORT</code> environment variables when
		  performing the checks - it does <emphasis>not</emphasis> use the
		  PostgreSQL version that may have been specified using the
		  configuration parameter <command>--with-pgconfig</command>. So make
		  sure to modify your PATH to match the detected PostgreSQL installation
		  during configuration or be prepared to deal with the impending
		  headaches.
		</para>
	  </caution>

	  <para>
		If successful, the output of the test should be similar to the
		following:
	  </para>

	  <programlisting>    CUnit - A unit testing framework for C - Version 2.1-2
     http://cunit.sourceforge.net/


Suite: computational_geometry
  Test: test_lw_segment_side ...passed
  Test: test_lw_segment_intersects ...passed
  Test: test_lwline_crossing_short_lines ...passed
  Test: test_lwline_crossing_long_lines ...passed
  Test: test_lwline_crossing_bugs ...passed
  Test: test_lwpoint_set_ordinate ...passed
  Test: test_lwpoint_get_ordinate ...passed
  Test: test_point_interpolate ...passed
  Test: test_lwline_clip ...passed
  Test: test_lwline_clip_big ...passed
  Test: test_lwmline_clip ...passed
  Test: test_geohash_point ...passed
  Test: test_geohash_precision ...passed
  Test: test_geohash ...passed
  Test: test_geohash_point_as_int ...passed
  Test: test_isclosed ...passed
  Test: test_lwgeom_simplify ...passed
Suite: buildarea
  Test: buildarea1 ...passed
  Test: buildarea2 ...passed
  Test: buildarea3 ...passed
  Test: buildarea4 ...passed
  Test: buildarea4b ...passed
  Test: buildarea5 ...passed
  Test: buildarea6 ...passed
  Test: buildarea7 ...passed
Suite: geometry_clean
  Test: test_lwgeom_make_valid ...passed
Suite: clip_by_rectangle
  Test: test_lwgeom_clip_by_rect ...passed
Suite: force_sfs
  Test: test_sfs_11 ...passed
  Test: test_sfs_12 ...passed
  Test: test_sqlmm ...passed
Suite: geodetic
  Test: test_sphere_direction ...passed
  Test: test_sphere_project ...passed
  Test: test_lwgeom_area_sphere ...passed
  Test: test_signum ...passed
  Test: test_gbox_from_spherical_coordinates ...passed
  Test: test_gserialized_get_gbox_geocentric ...passed
  Test: test_clairaut ...passed
  Test: test_edge_intersection ...passed
  Test: test_edge_intersects ...passed
  Test: test_edge_distance_to_point ...passed
  Test: test_edge_distance_to_edge ...passed
  Test: test_lwgeom_distance_sphere ...passed
  Test: test_lwgeom_check_geodetic ...passed
  Test: test_gserialized_from_lwgeom ...passed
  Test: test_spheroid_distance ...passed
  Test: test_spheroid_area ...passed
  Test: test_lwpoly_covers_point2d ...passed
  Test: test_gbox_utils ...passed
  Test: test_vector_angle ...passed
  Test: test_vector_rotate ...passed
  Test: test_lwgeom_segmentize_sphere ...passed
  Test: test_ptarray_contains_point_sphere ...passed
  Test: test_ptarray_contains_point_sphere_iowa ...passed
Suite: GEOS
  Test: test_geos_noop ...passed
  Test: test_geos_subdivide ...passed
  Test: test_geos_linemerge ...passed
Suite: Clustering
  Test: basic_test ...passed
  Test: nonsequential_test ...passed
  Test: basic_distance_test ...passed
  Test: single_input_test ...passed
  Test: empty_inputs_test ...passed
Suite: Clustering Union-Find
  Test: test_unionfind_create ...passed
  Test: test_unionfind_union ...passed
  Test: test_unionfind_ordered_by_cluster ...passed
Suite: homogenize
  Test: test_coll_point ...passed
  Test: test_coll_line ...passed
  Test: test_coll_poly ...passed
  Test: test_coll_coll ...passed
  Test: test_geom ...passed
  Test: test_coll_curve ...passed
Suite: encoded_polyline_input
  Test: in_encoded_polyline_test_geoms ...passed
  Test: in_encoded_polyline_test_precision ...passed
Suite: geojson_input
  Test: in_geojson_test_srid ...passed
  Test: in_geojson_test_bbox ...passed
  Test: in_geojson_test_geoms ...passed
Suite: twkb_input
  Test: test_twkb_in_point ...passed
  Test: test_twkb_in_linestring ...passed
  Test: test_twkb_in_polygon ...passed
  Test: test_twkb_in_multipoint ...passed
  Test: test_twkb_in_multilinestring ...passed
  Test: test_twkb_in_multipolygon ...passed
  Test: test_twkb_in_collection ...passed
  Test: test_twkb_in_precision ...passed
Suite: serialization/deserialization
  Test: test_typmod_macros ...passed
  Test: test_flags_macros ...passed
  Test: test_serialized_srid ...passed
  Test: test_gserialized_from_lwgeom_size ...passed
  Test: test_gbox_serialized_size ...passed
  Test: test_lwgeom_from_gserialized ...passed
  Test: test_lwgeom_count_vertices ...passed
  Test: test_on_gser_lwgeom_count_vertices ...passed
  Test: test_geometry_type_from_string ...passed
  Test: test_lwcollection_extract ...passed
  Test: test_lwgeom_free ...passed
  Test: test_lwgeom_flip_coordinates ...passed
  Test: test_f2d ...passed
  Test: test_lwgeom_clone ...passed
  Test: test_lwgeom_force_clockwise ...passed
  Test: test_lwgeom_calculate_gbox ...passed
  Test: test_lwgeom_is_empty ...passed
  Test: test_lwgeom_same ...passed
  Test: test_lwline_from_lwmpoint ...passed
  Test: test_lwgeom_as_curve ...passed
  Test: test_lwgeom_scale ...passed
  Test: test_gserialized_is_empty ...passed
  Test: test_gbox_same_2d ...passed
Suite: measures
  Test: test_mindistance2d_tolerance ...passed
  Test: test_rect_tree_contains_point ...passed
  Test: test_rect_tree_intersects_tree ...passed
  Test: test_lwgeom_segmentize2d ...passed
  Test: test_lwgeom_locate_along ...passed
  Test: test_lw_dist2d_pt_arc ...passed
  Test: test_lw_dist2d_seg_arc ...passed
  Test: test_lw_dist2d_arc_arc ...passed
  Test: test_lw_arc_length ...passed
  Test: test_lw_dist2d_pt_ptarrayarc ...passed
  Test: test_lw_dist2d_ptarray_ptarrayarc ...passed
  Test: test_lwgeom_tcpa ...passed
  Test: test_lwgeom_is_trajectory ...passed
Suite: effectivearea
  Test: do_test_lwgeom_effectivearea_lines ...passed
  Test: do_test_lwgeom_effectivearea_polys ...passed
Suite: miscellaneous
  Test: test_misc_force_2d ...passed
  Test: test_misc_simplify ...passed
  Test: test_misc_count_vertices ...passed
  Test: test_misc_area ...passed
  Test: test_misc_wkb ...passed
  Test: test_grid ...passed
Suite: noding
  Test: test_lwgeom_node ...passed
Suite: encoded_polyline_output
  Test: out_encoded_polyline_test_geoms ...passed
  Test: out_encoded_polyline_test_srid ...passed
  Test: out_encoded_polyline_test_precision ...passed
Suite: geojson_output
  Test: out_geojson_test_precision ...passed
  Test: out_geojson_test_dims ...passed
  Test: out_geojson_test_srid ...passed
  Test: out_geojson_test_bbox ...passed
  Test: out_geojson_test_geoms ...passed
Suite: gml_output
  Test: out_gml_test_precision ...passed
  Test: out_gml_test_srid ...passed
  Test: out_gml_test_dims ...passed
  Test: out_gml_test_geodetic ...passed
  Test: out_gml_test_geoms ...passed
  Test: out_gml_test_geoms_prefix ...passed
  Test: out_gml_test_geoms_nodims ...passed
  Test: out_gml2_extent ...passed
  Test: out_gml3_extent ...passed
Suite: kml_output
  Test: out_kml_test_precision ...passed
  Test: out_kml_test_dims ...passed
  Test: out_kml_test_geoms ...passed
  Test: out_kml_test_prefix ...passed
Suite: svg_output
  Test: out_svg_test_precision ...passed
  Test: out_svg_test_dims ...passed
  Test: out_svg_test_relative ...passed
  Test: out_svg_test_geoms ...passed
  Test: out_svg_test_srid ...passed
Suite: x3d_output
  Test: out_x3d3_test_precision ...passed
  Test: out_x3d3_test_geoms ...passed
  Test: out_x3d3_test_option ...passed
Suite: ptarray
  Test: test_ptarray_append_point ...passed
  Test: test_ptarray_append_ptarray ...passed
  Test: test_ptarray_locate_point ...passed
  Test: test_ptarray_isccw ...passed
  Test: test_ptarray_signed_area ...passed
  Test: test_ptarray_unstroke ...passed
  Test: test_ptarray_insert_point ...passed
  Test: test_ptarray_contains_point ...passed
  Test: test_ptarrayarc_contains_point ...passed
  Test: test_ptarray_scale ...passed
Suite: printing
  Test: test_lwprint_default_format ...passed
  Test: test_lwprint_format_orders ...passed
  Test: test_lwprint_optional_format ...passed
  Test: test_lwprint_oddball_formats ...passed
  Test: test_lwprint_bad_formats ...passed
Suite: SFCGAL
  Test: test_sfcgal_noop ...passed
Suite: split
  Test: test_lwline_split_by_point_to ...passed
  Test: test_lwgeom_split ...passed
Suite: stringbuffer
  Test: test_stringbuffer_append ...passed
  Test: test_stringbuffer_aprintf ...passed
Suite: surface
  Test: triangle_parse ...passed
  Test: tin_parse ...passed
  Test: polyhedralsurface_parse ...passed
  Test: surface_dimension ...passed
Suite: Internal Spatial Trees
  Test: test_tree_circ_create ...passed
  Test: test_tree_circ_pip ...passed
  Test: test_tree_circ_pip2 ...passed
  Test: test_tree_circ_distance ...passed
  Test: test_tree_circ_distance_threshold ...passed
Suite: triangulate
  Test: test_lwgeom_delaunay_triangulation ...passed
Suite: twkb_output
  Test: test_twkb_out_point ...passed
  Test: test_twkb_out_linestring ...passed
  Test: test_twkb_out_polygon ...passed
  Test: test_twkb_out_multipoint ...passed
  Test: test_twkb_out_multilinestring ...passed
  Test: test_twkb_out_multipolygon ...passed
  Test: test_twkb_out_collection ...passed
  Test: test_twkb_out_idlist ...passed
Suite: varint
  Test: test_zigzag ...passed
  Test: test_varint ...passed
  Test: test_varint_roundtrip ...passed
Suite: wkb_input
  Test: test_wkb_in_point ...passed
  Test: test_wkb_in_linestring ...passed
  Test: test_wkb_in_polygon ...passed
  Test: test_wkb_in_multipoint ...passed
  Test: test_wkb_in_multilinestring ...passed
  Test: test_wkb_in_multipolygon ...passed
  Test: test_wkb_in_collection ...passed
  Test: test_wkb_in_circularstring ...passed
  Test: test_wkb_in_compoundcurve ...passed
  Test: test_wkb_in_curvpolygon ...passed
  Test: test_wkb_in_multicurve ...passed
  Test: test_wkb_in_multisurface ...passed
  Test: test_wkb_in_malformed ...passed
Suite: wkb_output
  Test: test_wkb_out_point ...passed
  Test: test_wkb_out_linestring ...passed
  Test: test_wkb_out_polygon ...passed
  Test: test_wkb_out_multipoint ...passed
  Test: test_wkb_out_multilinestring ...passed
  Test: test_wkb_out_multipolygon ...passed
  Test: test_wkb_out_collection ...passed
  Test: test_wkb_out_circularstring ...passed
  Test: test_wkb_out_compoundcurve ...passed
  Test: test_wkb_out_curvpolygon ...passed
  Test: test_wkb_out_multicurve ...passed
  Test: test_wkb_out_multisurface ...passed
  Test: test_wkb_out_polyhedralsurface ...passed
Suite: wkt_input
  Test: test_wkt_in_point ...passed
  Test: test_wkt_in_linestring ...passed
  Test: test_wkt_in_polygon ...passed
  Test: test_wkt_in_multipoint ...passed
  Test: test_wkt_in_multilinestring ...passed
  Test: test_wkt_in_multipolygon ...passed
  Test: test_wkt_in_collection ...passed
  Test: test_wkt_in_circularstring ...passed
  Test: test_wkt_in_compoundcurve ...passed
  Test: test_wkt_in_curvpolygon ...passed
  Test: test_wkt_in_multicurve ...passed
  Test: test_wkt_in_multisurface ...passed
  Test: test_wkt_in_tin ...passed
  Test: test_wkt_in_polyhedralsurface ...passed
  Test: test_wkt_in_errlocation ...passed
Suite: wkt_output
  Test: test_wkt_out_point ...passed
  Test: test_wkt_out_linestring ...passed
  Test: test_wkt_out_polygon ...passed
  Test: test_wkt_out_multipoint ...passed
  Test: test_wkt_out_multilinestring ...passed
  Test: test_wkt_out_multipolygon ...passed
  Test: test_wkt_out_collection ...passed
  Test: test_wkt_out_circularstring ...passed
  Test: test_wkt_out_compoundcurve ...passed
  Test: test_wkt_out_curvpolygon ...passed
  Test: test_wkt_out_multicurve ...passed
  Test: test_wkt_out_multisurface ...passed

Run Summary:    Type  Total    Ran Passed Failed Inactive
              suites     38     38    n/a      0        0
               tests    251    251    251      0        0
             asserts   2468   2468   2468      0      n/a

Elapsed time =    0.298 seconds

Creating database 'postgis_reg'
Loading PostGIS into 'postgis_reg'
  /projects/postgis/branches/2.2/regress/00-regress-install/share/contrib/postgis/postgis.sql
  /projects/postgis/branches/2.2/regress/00-regress-install/share/contrib/postgis/postgis_comments.sql
Loading SFCGAL into 'postgis_reg'
  /projects/postgis/branches/2.2/regress/00-regress-install/share/contrib/postgis/sfcgal.sql
  /projects/postgis/branches/2.2/regress/00-regress-install/share/contrib/postgis/sfcgal_comments.sql
PostgreSQL 9.4.4, compiled by Visual C++ build 1800, 32-bit
  Postgis 2.2.0dev - r13980 - 2015-08-23 06:13:07
  scripts 2.2.0dev r13980
  GEOS: 3.5.0-CAPI-1.9.0 r4088
  PROJ: Rel. 4.9.1, 04 March 2015
  SFCGAL: 1.1.0

Running tests

 loader/Point .............. ok
 loader/PointM .............. ok
 loader/PointZ .............. ok
 loader/MultiPoint .............. ok
 loader/MultiPointM .............. ok
 loader/MultiPointZ .............. ok
 loader/Arc .............. ok
 loader/ArcM .............. ok
 loader/ArcZ .............. ok
 loader/Polygon .............. ok
 loader/PolygonM .............. ok
 loader/PolygonZ .............. ok
 loader/TSTPolygon ......... ok
 loader/TSIPolygon ......... ok
 loader/TSTIPolygon ......... ok
 loader/PointWithSchema ..... ok
 loader/NoTransPoint ......... ok
 loader/NotReallyMultiPoint ......... ok
 loader/MultiToSinglePoint ......... ok
 loader/ReprojectPts ........ ok
 loader/ReprojectPtsGeog ........ ok
 loader/Latin1 .... ok
 loader/Latin1-implicit .... ok
 loader/mfile .... ok
 dumper/literalsrid ....... ok
 dumper/realtable ....... ok
 affine .. ok
 bestsrid .. ok
 binary .. ok
 boundary .. ok
 cluster .. ok
 concave_hull .. ok
 ctors .. ok
 dump .. ok
 dumppoints .. ok
 empty .. ok
 forcecurve .. ok
 geography .. ok
 in_geohash .. ok
 in_gml .. ok
 in_kml .. ok
 in_encodedpolyline .. ok
 iscollection .. ok
 legacy .. ok
 long_xact .. ok
 lwgeom_regress .. ok
 measures .. ok
 operators .. ok
 out_geometry .. ok
 out_geography .. ok
 polygonize .. ok
 polyhedralsurface .. ok
 postgis_type_name .. ok
 regress .. ok
 regress_bdpoly .. ok
 regress_index .. ok
 regress_index_nulls .. ok
 regress_management .. ok
 regress_selectivity .. ok
 regress_lrs .. ok
 regress_ogc .. ok
 regress_ogc_cover .. ok
 regress_ogc_prep .. ok
 regress_proj .. ok
 relate .. ok
 remove_repeated_points .. ok
 removepoint .. ok
 setpoint .. ok
 simplify .. ok
 simplifyvw .. ok
 size .. ok
 snaptogrid .. ok
 split .. ok
 sql-mm-serialize .. ok
 sql-mm-circularstring .. ok
 sql-mm-compoundcurve .. ok
 sql-mm-curvepoly .. ok
 sql-mm-general .. ok
 sql-mm-multicurve .. ok
 sql-mm-multisurface .. ok
 swapordinates .. ok
 summary .. ok
 temporal .. ok
 tickets .. ok
 twkb .. ok
 typmod .. ok
 wkb .. ok
 wkt .. ok
 wmsservers .. ok
 knn .. ok
 hausdorff .. ok
 regress_buffer_params .. ok
 offsetcurve .. ok
 relatematch .. ok
 isvaliddetail .. ok
 sharedpaths .. ok
 snap .. ok
 node .. ok
 unaryunion .. ok
 clean .. ok
 relate_bnr .. ok
 delaunaytriangles .. ok
 clipbybox2d .. ok
 subdivide .. ok
 in_geojson .. ok
 regress_sfcgal .. ok
 sfcgal/empty .. ok
 sfcgal/geography .. ok
 sfcgal/legacy .. ok
 sfcgal/measures .. ok
 sfcgal/regress_ogc_prep .. ok
 sfcgal/regress_ogc .. ok
 sfcgal/regress .. ok
 sfcgal/tickets .. ok
 sfcgal/concave_hull .. ok
 sfcgal/wmsservers .. ok
 sfcgal/approximatemedialaxis .. ok
 uninstall .  /projects/postgis/branches/2.2/regress/00-regress-install/share/contrib/postgis/uninstall_sfcgal.sql
  /projects/postgis/branches/2.2/regress/00-regress-install/share/contrib/postgis/uninstall_postgis.sql
. ok (4336)

Run tests: 118
Failed: 0

-- if you built --with-gui, you should see this too

     CUnit - A unit testing framework for C - Version 2.1-2
     http://cunit.sourceforge.net/


Suite: Shapefile Loader File shp2pgsql Test
  Test: test_ShpLoaderCreate() ...passed
  Test: test_ShpLoaderDestroy() ...passed
Suite: Shapefile Loader File pgsql2shp Test
  Test: test_ShpDumperCreate() ...passed
  Test: test_ShpDumperDestroy() ...passed

Run Summary:    Type  Total    Ran Passed Failed Inactive
              suites      2      2    n/a      0        0
               tests      4      4      4      0        0
             asserts      4      4      4      0      n/a</programlisting>

	  <para>The <varname>postgis_tiger_geocoder</varname> and <varname>address_standardizer</varname> extensions, currenlty only support the standard PostgreSQL installcheck.  To test these use the below.  Note: the make install is not necessary if you already did make install at root of PostGIS code folder.</para>
	  <para>For address_standardizer:
	  <programlisting>cd extensions/address_standardizer
make install
make installcheck
	  </programlisting></para>

	  <para>Output should look like:
	  <screen>============== dropping database "contrib_regression" ==============
DROP DATABASE
============== creating database "contrib_regression" ==============
CREATE DATABASE
ALTER DATABASE
============== running regression test queries        ==============
test test-init-extensions     ... ok
test test-parseaddress        ... ok
test test-standardize_address_1 ... ok
test test-standardize_address_2 ... ok

=====================
 All 4 tests passed.
=====================</screen></para>

	  <para>For tiger geocoder, make sure you have postgis and fuzzystrmatch extensions available in your PostgreSQL instance. The address_standardizer tests will also kick in if you built postgis with address_standardizer support:
	  <programlisting>cd extensions/postgis_tiger_geocoder
make install
make installcheck
	  </programlisting></para>
	  <para>output should look like:
	  <screen>============== dropping database "contrib_regression" ==============
DROP DATABASE
============== creating database "contrib_regression" ==============
CREATE DATABASE
ALTER DATABASE
============== installing fuzzystrmatch               ==============
CREATE EXTENSION
============== installing postgis                     ==============
CREATE EXTENSION
============== installing postgis_tiger_geocoder      ==============
CREATE EXTENSION
============== installing address_standardizer        ==============
CREATE EXTENSION
============== running regression test queries        ==============
test test-normalize_address   ... ok
test test-pagc_normalize_address ... ok

=====================
All 2 tests passed.
=====================</screen></para>
	</sect2>

	<sect2>
	  <title>Installation</title>

	  <para>
		To install PostGIS, type
	  </para>

	  <para>
		<command>make install</command>
	  </para>

	  <para>
		This will copy the PostGIS installation files into their appropriate
		subdirectory specified by the <command>--prefix</command> configuration
		parameter. In particular:
	  </para>

	  <itemizedlist>
		<listitem>
		  <para>
			The loader and dumper binaries are installed in
			<filename>[prefix]/bin</filename>.
		  </para>
		</listitem>

		<listitem>
		  <para>
			The SQL files, such as <filename>postgis.sql</filename>, are
			installed in <filename>[prefix]/share/contrib</filename>.
		  </para>
		</listitem>

		<listitem>
		  <para>
			The PostGIS libraries are installed in
			<filename>[prefix]/lib</filename>.
		  </para>
		</listitem>
	  </itemizedlist>

	  <para>
		If you previously ran the <command>make comments</command> command to
		generate the <filename>postgis_comments.sql</filename>, <filename>raster_comments.sql</filename> file, install the
		sql file by running
	  </para>

	  <para>
		<command>make comments-install</command>
	  </para>

	  <note>
		<para>
		  <filename>postgis_comments.sql</filename>, <filename>raster_comments.sql</filename>, <filename>topology_comments.sql</filename> was separated from the
		  typical build and installation targets since with it comes the extra
		  dependency of <command>xsltproc</command>.
		</para>
	  </note>
	</sect2>
  </sect1>

  <sect1 id="create_new_db_extensions">
	<title>Creating a spatial database using EXTENSIONS</title>

	<para>
	 If you are using PostgreSQL 9.1+ and have compiled and installed the extensions/ postgis modules, you
	 can create a spatial database the new way.
	</para>

	<para>
	  <command>createdb [yourdatabase]</command>
	</para>

	<para>
	  The core postgis extension installs PostGIS geometry, geography, raster, spatial_ref_sys and all the functions and comments with a simple:
	  <programlisting>CREATE EXTENSION postgis;</programlisting> command.
	</para>

	<para>
	  <command>psql -d [yourdatabase] -c "CREATE EXTENSION postgis;"</command>
	</para>

	<para>
	  Topology is packaged as a separate extension and installable with command:
	</para>

	<para>
	  <command>psql -d [yourdatabase] -c "CREATE EXTENSION postgis_topology;"</command>
	</para>

	<para>If you plan to restore an old backup from prior versions in this new db, run:</para>
	<para><command>psql -d [yourdatabase] -f legacy.sql</command></para>
	<note><para>If you need legacy functions, you'll need to reinstall the legacy.sql script whenever you upgrade the minor version of PostGIS.
	E.g. if you upgraded from 2.4.3 to 2.5.0, then you need to reinstall the legacy.sql packaged with 2.5.0.  This is because some of the functions make reference to the library
	and the library is named with the minor in it.</para></note>
	<para>You can later run <filename>uninstall_legacy.sql</filename> to get rid of the deprecated functions after you are done with restoring and cleanup.</para>
  </sect1>

    <sect1 id="create_new_db">
	<title>Create a spatially-enabled database without using extensions</title>

	<note><para>This is generally only needed if you built-PostGIS without raster support. Since raster functions are part of the postgis extension, extension support is not enabled if PostGIS is built without raster.</para></note>
	<para> The first step in creating a PostGIS database is to create a simple
	  PostgreSQL database.
	</para>

	<para>
	  <command>createdb [yourdatabase]</command>
	</para>

	<para>
	  Many of the PostGIS functions are written in the PL/pgSQL procedural
	  language. As such, the next step to create a PostGIS database is to enable
	  the PL/pgSQL language in your new database. This is accomplish by the
	  command below command.  For PostgreSQL 8.4+, this is generally already installed
	</para>

	<para>
	  <command>createlang plpgsql [yourdatabase]</command>
	</para>

	<para>
	  Now load the PostGIS object and function definitions into your database by
	  loading the <filename>postgis.sql</filename> definitions file (located in
	  <filename>[prefix]/share/contrib</filename> as specified during the
	  configuration step).
	</para>

	<para>
	  <command>psql -d [yourdatabase] -f postgis.sql</command>
	</para>

	<para>
	  For a complete set of EPSG coordinate system definition identifiers, you
	  can also load the <filename>spatial_ref_sys.sql</filename> definitions
	  file and populate the <varname>spatial_ref_sys</varname> table. This will
	  permit you to perform ST_Transform() operations on geometries.
	</para>

	<para>
	  <command>psql -d [yourdatabase] -f spatial_ref_sys.sql</command>
	</para>

	<para>
	  If you wish to add comments to the PostGIS functions, the final step is to
	  load the <filename>postgis_comments.sql</filename> into your spatial
	  database. The comments can be viewed by simply typing <command>\dd
	  [function_name]</command> from a <command>psql</command> terminal window.
	</para>

	<para>
	  <command>psql -d [yourdatabase] -f postgis_comments.sql</command>
	</para>

	<para>
	  Install raster support
	</para>

	<para>
	  <command>psql -d [yourdatabase] -f rtpostgis.sql</command>
	</para>

	<para>
	  Install raster support comments.  This will provide quick help info for each raster function
	  using psql or PgAdmin or any other PostgreSQL tool that can show function comments
	</para>

	<para>
	  <command>psql -d [yourdatabase] -f raster_comments.sql</command>
	</para>
	<para>
	  Install topology support
	</para>

	<para>
	  <command>psql -d [yourdatabase] -f topology/topology.sql</command>
	</para>

	<para>
	  Install topology support comments.  This will provide quick help info for each topology function / type
	  using psql or PgAdmin or any other PostgreSQL tool that can show function comments
	</para>

	<para>
	  <command>psql -d [yourdatabase] -f topology/topology_comments.sql</command>
	</para>

	<para>If you plan to restore an old backup from prior versions in this new db, run:</para>
	<para><command>psql -d [yourdatabase] -f legacy.sql</command></para>
	<note><para>There is an alternative <filename>legacy_minimal.sql</filename> you can run instead which will install barebones needed to recover tables and work with apps like MapServer
	and GeoServer. If you have views that use things like distance / length etc, you'll need the full blown <filename>legacy.sql</filename></para></note>

	<para>You can later run <filename>uninstall_legacy.sql</filename> to get rid of the deprecated functions after you are done with restoring and cleanup.</para>
  </sect1>

  <sect1 id="installing_pagc_address_standardizer"><title>Installing and Using the address standardizer</title>
		<para>The <code>address_standardizer</code> extension used to be a separate package that required separate download. From PostGIS 2.2 on, it is now bundled in.
		For more information about the address_standardize, what it does, and how to configure it for your needs, refer to <xref linkend="Address_Standardizer" />.</para>
		<para>This standardizer can be used in conjunction with the PostGIS packaged tiger geocoder extension as a replacement for the <xref linkend="Normalize_Address" /> discussed.
		To use as replacement refer to  <xref linkend="tiger_pagc_address_standardizing" />.
		You can also use it as a building block for your own geocoder or use it to standardize your addresses for easier compare of addresses.</para>

		<para>The address standardizer relies on PCRE which is usually already installed on many Nix systems,
but you can download the latest at: <ulink url="http://www.pcre.org">http://www.pcre.org</ulink>. If during <xref linkend="installation_configuration" />, PCRE is found, then the address standardizer extension will automatically be built.  If you have a custom pcre install you want to use instead, pass to configure <code>--with-pcredir=/path/to/pcre</code> where <filename>/path/to/pcre</filename> is the root folder for your pcre include and lib directories.</para>

		<para>For Windows users, the PostGIS 2.1+ bundle is packaged with the address_standardizer already so no need to compile and can move straight to <code>CREATE EXTENSION</code> step.</para>


      <para>Once you have installed, you can connect to your database and run the SQL:</para>
			<programlisting>CREATE EXTENSION address_standardizer;</programlisting>

			<para>The following test requires no rules, gaz, or lex tables</para>
			<programlisting>SELECT num, street, city, state, zip
 FROM parse_address('1 Devonshire Place PH301, Boston, MA 02109');</programlisting>
			<para>Output should be</para>
			<screen> num |         street         |  city  | state |  zip
-----+------------------------+--------+-------+-------
 1   | Devonshire Place PH301 | Boston | MA    | 02109</screen>

        <sect2><title>Installing Regex::Assemble</title>
            <para>Perl Regex:Assemble is no longer needed for compiling address_standardizer extension since the files it generates are part of the source tree.  However if you need to edit the <filename>usps-st-city-orig.txt</filename> or <filename>usps-st-city-orig.txt usps-st-city-adds.tx</filename>, you need to rebuild <filename>parseaddress-stcities.h</filename> which does require Regex:Assemble.</para>
            <programlisting>cpan Regexp::Assemble</programlisting>
            <para>or if you are on Ubuntu / Debian you might need to do</para>
            <programlisting>sudo perl -MCPAN -e "install Regexp::Assemble"</programlisting>
        </sect2>
	</sect1>

  <sect1 id="loading_extras_tiger_geocoder">
	<title>Installing, Upgrading Tiger Geocoder and loading data</title>

	<para>Extras like Tiger geocoder may not be packaged in your PostGIS distribution. If you are missing the tiger geocoder extension or want a newer version than what your install comes with, then use
	the <filename>share/extension/postgis_tiger_geocoder.*</filename> files from the packages in <ulink url="http://postgis.net/windows_downloads/">Windows Unreleased Versions</ulink> section for your version of PostgreSQL.
	Although these packages are for windows, the postgis_tiger_geocoder extension files will work on any OS since the extension is an SQL/plpgsql only extension.</para>
	<sect2 id="install_tiger_geocoder_extension">
		<title>Tiger Geocoder Enabling your PostGIS database: Using Extension</title>
		<para>If you are using PostgreSQL 9.1+ and PostGIS 2.1+, you can take advantage of the new extension model for installing tiger geocoder. To do so:</para>
		<orderedlist>
			<listitem><para>First get binaries for PostGIS 2.1+ or compile and install as usual.  This should install the necessary extension files as well for tiger geocoder.</para></listitem>
			<listitem><para>Connect to your database via psql or pgAdmin or some other tool and run the following SQL commands.  Note that if you are installing in a database that already has postgis, you don't need to do the first step.  If you have <varname>fuzzystrmatch</varname> extension already installed, you don't need to do the second step either.</para>
			<para><programlisting>CREATE EXTENSION postgis;
CREATE EXTENSION fuzzystrmatch;
CREATE EXTENSION postgis_tiger_geocoder;
--this one is optional if you want to use the rules based standardizer (pagc_normalize_address)
CREATE EXTENSION address_standardizer;</programlisting></para>

<para>If you already have postgis_tiger_geocoder extension installed, and just want to update to the latest run:</para>
<programlisting>ALTER EXTENSION postgis UPDATE;
ALTER EXTENSION postgis_tiger_geocoder UPDATE;</programlisting>
<para>If you made custom entries or changes to <varname>tiger.loader_platform</varname> and <varname>tiger.loader_variables</varname> you may need to update these.</para>
</listitem>
			<listitem><para>To confirm your install is working correctly, run this sql in your database:</para>
				<programlisting>SELECT na.address, na.streetname,na.streettypeabbrev, na.zip
	FROM normalize_address('1 Devonshire Place, Boston, MA 02109') AS na;</programlisting>
				<para>Which should output</para>
				<para><screen> address | streetname | streettypeabbrev |  zip
---------+------------+------------------+-------
	   1 | Devonshire | Pl               | 02109</screen></para>
			</listitem>
			<listitem><para>Create a new record in <varname>tiger.loader_platform</varname> table with the paths of your executables and server. </para>
				<para>So for example to create a profile called debbie that follows <code>sh</code> convention. You would do:</para>
				<programlisting>INSERT INTO tiger.loader_platform(os, declare_sect, pgbin, wget, unzip_command, psql, path_sep,
		   loader, environ_set_command, county_process_command)
SELECT 'debbie', declare_sect, pgbin, wget, unzip_command, psql, path_sep,
	   loader, environ_set_command, county_process_command
  FROM tiger.loader_platform
  WHERE os = 'sh';</programlisting>
				<para>And then edit the paths in the <emphasis>declare_sect</emphasis> column to those that fit Debbie's pg, unzip,shp2pgsql, psql, etc path locations.</para>

				<para>If you don't edit this  <varname>loader_platform</varname> table, it will just contain common case locations of items and you'll have to edit the generated script after the script is generated.</para>
			</listitem>
			<listitem><para>As of PostGIS 2.4.1 the Zip code-5 digit tabulation area <varname>zcta5</varname> load step was revised to load current zcta5 data and is part of the  <xref linkend="Loader_Generate_Nation_Script" /> when enabled.
It is turned off by default because it takes quite a bit of time to load (20 to 60 minutes), takes up quite a bit of disk space, and is not used that often.</para>
<para>To enable it, do the following:</para>
<programlisting>UPDATE tiger.loader_lookuptables SET load = true WHERE table_name = 'zcta510';</programlisting>
<para>
If present the <xref linkend="Geocode" /> function can use it if a boundary filter is added to limit to just zips in that boundary.
The <xref linkend="Reverse_Geocode" /> function uses it if the returned address is missing a zip, which often happens with highway reverse geocoding.</para></listitem>
			<listitem><para>Create a folder called <filename>gisdata</filename> on root of server or your local pc if you have a fast network connection to the server. This folder is
where the tiger files will be downloaded to and processed.  If you are not happy with having the folder on the root of the server, or simply want to change to a different folder for staging, then edit the field <varname>staging_fold</varname> in the <varname>tiger.loader_variables</varname> table.</para></listitem>
            <listitem><para>Create a folder called temp in the <filename>gisdata</filename> folder or whereever you designated the <varname>staging_fold</varname> to be.  This will be
the folder where the loader extracts the downloaded tiger data.</para></listitem>
			<listitem><para>Then run the  <xref linkend="Loader_Generate_Nation_Script" />  SQL function make sure to use the name of your custom profile and copy the script to a .sh or .bat file.  So for example to build  the nation load:</para>
					<programlisting>psql -c "SELECT Loader_Generate_Nation_Script('debbie')" -d geocoder -tA > /gisdata/nation_script_load.sh</programlisting>
			</listitem>

			<listitem><para>Run the generated nation load commandline scripts.</para>
				<programlisting>cd /gisdata
sh nation_script_load.sh</programlisting>
      </listitem>

      <listitem><para>After you are done running the nation script, you should have three tables in your <code>tiger_data</code> schema and they should be filled with data. Confirm you do by doing the following queries from psql or pgAdmin</para>
				<programlisting>SELECT count(*) FROM tiger_data.county_all;</programlisting>
<screen> count
-------
  3233
(1 row)</screen>
				<programlisting>SELECT count(*) FROM tiger_data.state_all;</programlisting>
<screen>
 count
-------
    56
(1 row)
</screen>
      </listitem>

			<listitem><para>By default the tables corresponding to <varname>bg</varname>, <varname>tract</varname>, <varname>tabblock</varname> are not loaded. These tables are not used by the geocoder but are used by folks for population statistics.
			 If you wish to load them as part of your state loads, run the following statement to enable them.</para>
				<programlisting>UPDATE tiger.loader_lookuptables SET load = true WHERE load = false AND lookup_name IN('tract', 'bg', 'tabblock');</programlisting>
				<para>Alternatively you can load just these tables after loading state data using the <xref linkend="Loader_Generate_Census_Script" /></para></listitem>

			<listitem><para>For each state you want to load data for, generate a state script <xref linkend="Loader_Generate_Script" />.</para><warning><para>DO NOT Generate the state script until you have already loaded the nation data, because the state script utilizes county list loaded by nation script.</para></warning></listitem>

			<listitem><programlisting>psql -c "SELECT Loader_Generate_Script(ARRAY['MA'], 'debbie')" -d geocoder -tA > /gisdata/ma_load.sh</programlisting></listitem>

			<listitem><para>Run the generated commandline scripts.</para>
				<programlisting>cd /gisdata
sh ma_load.sh</programlisting>
			</listitem>
			<listitem><para>After you are done loading all data or at a stopping point, it's a good idea to analyze all the tiger tables to update the stats (include inherited stats)</para>
			    <programlisting>SELECT install_missing_indexes();
vacuum analyze verbose tiger.addr;
vacuum analyze verbose tiger.edges;
vacuum analyze verbose tiger.faces;
vacuum analyze verbose tiger.featnames;
vacuum analyze verbose tiger.place;
vacuum analyze verbose tiger.cousub;
vacuum analyze verbose tiger.county;
vacuum analyze verbose tiger.state;
vacuum analyze verbose tiger.zip_lookup_base;
vacuum analyze verbose tiger.zip_state;
vacuum analyze verbose tiger.zip_state_loc;</programlisting>
			</listitem>
		</orderedlist>
		<sect3 id="convert_tiger_geocoder_extension"><title>Converting a Tiger Geocoder Regular Install to Extension Model</title>
			<para>If you installed the tiger geocoder without using the extension model, you can convert to the extension model as follows:</para>
			<orderedlist>
				<listitem><para>Follow instructions in <xref linkend="upgrade_tiger_geocoder" /> for the non-extension model upgrade.</para></listitem>
				<listitem><para>Connect to your database with psql or pgAdmin and run the following command:</para>
					<programlisting>CREATE EXTENSION postgis_tiger_geocoder FROM unpackaged;</programlisting>
				</listitem>
			</orderedlist>
		</sect3>

	</sect2>
	<sect2 id="install_tiger_geocoder">
		<title>Tiger Geocoder Enabling your PostGIS database: Not Using Extensions</title>
		<para>
		  First install PostGIS using the prior instructions.
		</para>

		<para>
		  If you don't have an extras folder, download <ulink url="&postgis_download_url;">&postgis_download_url;</ulink>
		</para>

		<para>
		  <command>tar xvfz postgis-&last_release_version;.tar.gz</command>
		</para>

		<para>
		  <command>cd postgis-&last_release_version;/extras/tiger_geocoder</command>
		</para>

		<para>Edit the <filename>tiger_loader_2015.sql</filename> (or latest loader file you find, unless you want to load different year) to the paths of your executables server etc or alternatively you can update the <varname>loader_platform</varname> table once installed. If you don't edit this file or the <varname>loader_platform</varname> table, it will just contain common case locations of items and you'll have to edit the generated script after the fact when you run the  <xref linkend="Loader_Generate_Nation_Script" /> and <xref linkend="Loader_Generate_Script" />  SQL functions.
		 </para>
		<para>If you are installing Tiger geocoder for the first time edit either the <filename>create_geocode.bat</filename> script If you are on windows
			or the <filename>create_geocode.sh</filename> if you are on Linux/Unix/Mac OSX with your PostgreSQL specific settings and run the corresponding script from the commandline. </para>


		<para>Verify that you now have a <varname>tiger</varname> schema in your database and that it is part of your database search_path.  If it is not, add it with a command something along the line of: <programlisting>ALTER DATABASE geocoder SET search_path=public, tiger;</programlisting></para>
		<para>The normalizing address functionality works more or less without any data except for tricky addresses.  Run this test and verify things look like this:
			<programlisting>SELECT pprint_addy(normalize_address('202 East Fremont Street, Las Vegas, Nevada 89101')) As pretty_address;
pretty_address
---------------------------------------
202 E Fremont St, Las Vegas, NV 89101
			</programlisting>
		</para>
	</sect2>
	<sect2 id="tiger_pagc_address_standardizing"><title>Using Address Standardizer Extension with Tiger geocoder</title>
			<para>One of the many complaints of folks is the address normalizer function <xref linkend="Normalize_Address" /> function that normalizes an address for prepping before geocoding.  The normalizer is far from perfect and trying to patch its imperfectness takes a vast amount of resources.  As such we have integrated with another
			project that has a much better address standardizer engine.  To use this new address_standardizer, you compile the extension as described in <xref linkend="installing_pagc_address_standardizer" /> and install as an extension in your database.</para>

			<para>Once you install this extension in the same database as you have installed <code>postgis_tiger_geocoder</code>, then the <xref linkend="Pagc_Normalize_Address" /> can be used instead of <xref linkend="Normalize_Address" />. This extension is tiger agnostic, so can be used with other data sources such as international addresses. The tiger geocoder extension does come packaged with its own custom versions of <xref linkend="rulestab" /> ( <code>tiger.pagc_rules</code>) , <xref linkend="gaztab" /> (<code>tiger.pagc_gaz</code>), and <xref linkend="lextab" /> (<code>tiger.pagc_lex</code>).  These you can add and update to improve your standardizing experience for your own needs.</para>
	</sect2>
	<sect2 id="tiger_geocoder_loading_data">
		<title>Loading Tiger Data</title>
		<para>The instructions for loading data are available in a more detailed form  in the <filename>extras/tiger_geocoder/tiger_2011/README</filename>.  This just includes the general steps.</para>
		<para>The load process downloads data from the census website for the respective nation files, states requested, extracts the files, and then loads each state into its own separate
		set of state tables.  Each state table inherits from the tables defined in <varname>tiger</varname> schema so that its sufficient to just query those tables to access all the data and drop a set of state tables at any time using the <xref linkend="Drop_State_Tables_Generate_Script" /> if you need to reload a state or just don't need a state anymore.</para>
		<para>In order to be able to load data you'll need the following tools:</para>
		<itemizedlist>
			<listitem><para>A tool to unzip the zip files from census website.</para>
			  <para>For Unix like systems: <varname>unzip</varname> executable which is usually already installed on most Unix like platforms.</para>
			  <para>For Windows, 7-zip which is a free compress/uncompress tool you can download from <ulink url="http://www.7-zip.org/">http://www.7-zip.org/</ulink> </para>
			</listitem>
			<listitem><para><filename>shp2pgsql</filename> commandline which is installed by default when you install PostGIS.</para></listitem>
			<listitem><para><filename>wget</filename> which is a web grabber tool usually installed on most Unix/Linux systems.</para>
				<para>If you are on windows, you can get pre-compiled binaries from <ulink url="http://gnuwin32.sourceforge.net/packages/wget.htm">http://gnuwin32.sourceforge.net/packages/wget.htm</ulink> </para>
			</listitem>
		</itemizedlist>
		<para>If you are upgrading from tiger_2010, you'll need to first generate and run <xref linkend="Drop_Nation_Tables_Generate_Script" />. Before you load any state data, you need to load the nation wide data which you do with  <xref linkend="Loader_Generate_Nation_Script" />. Which will
		generate a loader script for you.   <xref linkend="Loader_Generate_Nation_Script" /> is a one-time step that should be done for upgrading (from 2010) and for new installs.</para>
		<para>To load state data refer to <xref linkend="Loader_Generate_Script" /> to generate a data load script for your platform for the states you desire.
			Note that you can install these piecemeal. You don't have to load all the states you want all at once.  You can load them as you need them.</para>

		<para>After the states you desire have been loaded, make sure to run the:
		<programlisting>SELECT install_missing_indexes();</programlisting> as described in  <xref linkend="Install_Missing_Indexes" />.</para>
		<para>To test that things are working as they should, try to run a geocode on an address in your state using <xref linkend="Geocode" /> </para>
	</sect2>
	<sect2 id="upgrade_tiger_geocoder">
		<title>Upgrading your Tiger Geocoder Install</title>
		<para>
		  If you have Tiger Geocoder packaged with 2.0+ already installed, you can upgrade the functions at any time even from an interim tar ball if there are fixes you badly need.  This will only work for Tiger geocoder not installed with extensions.
		</para>

		<para>
		  If you don't have an extras folder, download <ulink url="&postgis_download_url;">&postgis_download_url;</ulink>
		</para>

		<para>
		  <command>tar xvfz postgis-&last_release_version;.tar.gz</command>
		</para>

		<para>
		  <command>cd postgis-&last_release_version;/extras/tiger_geocoder/tiger_2011</command>
		</para>

		<para>Locate the  <filename>upgrade_geocoder.bat</filename> script If you are on windows
			or the <filename>upgrade_geocoder.sh</filename> if you are on Linux/Unix/Mac OSX.  Edit the file to have your postgis database credentials.</para>

		<para>If you are upgrading from 2010 or 2011, make sure to unremark out the loader script line so you get the latest script for loading 2012 data.</para>
		<para>
			Then run th corresponding script from the commandline.
		</para>

		<para>Next drop all nation tables and load up the new ones. Generate a drop script with this SQL statement as detailed in <xref linkend="Drop_Nation_Tables_Generate_Script" /></para>
			<programlisting>SELECT drop_nation_tables_generate_script();</programlisting>
		<para>Run the generated drop SQL statements.</para>
		<para>Generate a nation load script with this SELECT statement as detailed in <xref linkend="Loader_Generate_Nation_Script" /></para>
		<para><emphasis role="bold">For windows</emphasis></para>
		<programlisting>SELECT loader_generate_nation_script('windows'); </programlisting>
		<para><emphasis role="bold">For unix/linux</emphasis></para>
		<programlisting>SELECT loader_generate_nation_script('sh');</programlisting>
		<para>Refer to <xref linkend="tiger_geocoder_loading_data" /> for instructions on how to run the generate script. This only needs to be done once.</para>
		<note><para>You can have a mix of 2010/2011 state tables and can upgrade each state separately.  Before you upgrade a state to 2011, you first need to drop the 2010 tables for that state using <xref linkend="Drop_State_Tables_Generate_Script" />.</para></note>
	</sect2>

  </sect1>

  <sect1 id="templatepostgis">
	<title>Create a spatially-enabled database from a template</title>

	<para>
	  Some packaged distributions of PostGIS (in particular the Win32 installers
	  for PostGIS &gt;= 1.1.5) load the PostGIS functions into a template
	  database called <varname>template_postgis</varname>. If the
	  <varname>template_postgis</varname> database exists in your PostgreSQL
	  installation then it is possible for users and/or applications to create
	  spatially-enabled databases using a single command. Note that in both
	  cases, the database user must have been granted the privilege to create
	  new databases.
	</para>

	<para>
	  From the shell:
	</para>

	<programlisting># createdb -T template_postgis my_spatial_db</programlisting>

	<para>
	  From SQL:
	</para>

	<programlisting>postgres=# CREATE DATABASE my_spatial_db TEMPLATE=template_postgis</programlisting>
  </sect1>

  <sect1 id="upgrading">
	<title>Upgrading</title>

	<para>
	  Upgrading existing spatial databases can be tricky as it requires
	  replacement or introduction of new PostGIS object definitions.
	</para>

	<para>
	  Unfortunately not all definitions can be easily replaced in a live
	  database, so sometimes your best bet is a dump/reload process.
	</para>

	<para>
	  PostGIS provides a SOFT UPGRADE procedure for minor or bugfix releases,
	  and a HARD UPGRADE procedure for major releases.
	</para>

	<para>
	  Before attempting to upgrade PostGIS, it is always worth to backup your
	  data. If you use the -Fc flag to pg_dump you will always be able to
	  restore the dump with a HARD UPGRADE.
	</para>

	<sect2 id="soft_upgrade">
	  <title>Soft upgrade</title>

	  <para>If you installed your database using extensions, you'll need to upgrade using the extension model as well.  If you installed using the old sql script way,
	  then you should upgrade using the sql script way. Please refer to the appropriate.</para>

	  <sect3 id="soft_upgrade_sql_script"><title>Soft Upgrade Pre 9.1+ or without extensions</title>
	  <para>This section applies only to those who installed PostGIS not using extensions.  If you have extensions and try to upgrade with this approach you'll get messages like:</para>
	  <programlisting>can't drop ... because postgis extension depends on it</programlisting>
	  <para>
		After compiling and installing (make install) you should find a  <filename>postgis_upgrade.sql</filename> and <filename>rtpostgis_upgrade.sql</filename> in the installation folders. For example <filename>/usr/share/postgresql/9.3/contrib/postgis_upgrade.sql</filename>.  Install the <filename>postgis_upgrade.sql</filename>. If you have raster functionality installed, you will also need to install the <filename>/usr/share/postgresql/9.3/contrib/postgis_upgrade.sql</filename>. If you are moving from PostGIS 1.* to PostGIS 2.* or from PostGIS 2.* prior to r7409, you need to do a HARD UPGRADE.
	  </para>

	  <programlisting>psql -f postgis_upgrade.sql -d your_spatial_database</programlisting>

	  <para>
		The same procedure applies to raster and
		topology extensions, with upgrade files named
		<filename>rtpostgis_upgrade*.sql</filename> and
		<filename>topology_upgrade*.sql</filename> respectively.
		If you need them:
	  </para>

	  <programlisting>psql -f rtpostgis_upgrade.sql -d your_spatial_database</programlisting>
	  <programlisting>psql -f topology_upgrade.sql -d your_spatial_database</programlisting>

	  <note>
		<para>
		  If you can't find the <filename>postgis_upgrade*.sql</filename> specific for upgrading your version you are using a version too early for
		  a soft upgrade and need to do a HARD UPGRADE.
		</para>
	  </note>

	  <para>
		The <xref linkend="PostGIS_Full_Version" /> function
		should inform you about the need to run this kind of
		upgrade using a "procs need upgrade" message.
	  </para>
	  </sect3>

	<sect3 id="soft_upgrade_extensions"><title>Soft Upgrade 9.1+ using extensions</title>
		<para>If you originally installed PostGIS with extensions, then you need to upgrade using extensions as well.  Doing a minor upgrade with extensions, is fairly painless.</para>
		<programlisting>ALTER EXTENSION postgis UPDATE TO "&last_release_version;";
ALTER EXTENSION postgis_topology UPDATE TO "&last_release_version;";</programlisting>
		<para>If you get an error notice something like:</para>
			<programlisting>No migration path defined for ... to &last_release_version;</programlisting>
		<para>Then you'll need to backup your database, create a fresh one as described in <xref linkend="create_new_db_extensions" /> and then restore your backup ontop of this new database.</para>
    <para>If you get a notice message like:</para>
    <programlisting>Version "&last_release_version;" of extension "postgis" is already installed</programlisting>
    <para>
Then everything is already up to date and you can safely ignore it. <emphasis role="bold">UNLESS</emphasis>
you're attempting to upgrade from an SVN version to the next (which
doesn't get a new version number); in that case you can append "next" to the version
string, and next time you'll need to drop the "next" suffix again:
    </para>
		<programlisting>ALTER EXTENSION postgis UPDATE TO "&last_release_version;next";
ALTER EXTENSION postgis_topology UPDATE TO "&last_release_version;next";</programlisting>
		<note><para>If you installed PostGIS originally without a version specified, you can often skip the reinstallation of postgis extension before restoring since the backup just has <code>CREATE EXTENSION postgis</code> and thus
		picks up the newest latest version during restore.</para></note>
	</sect3>

	</sect2>

	<sect2 id="hard_upgrade">
	  <title>Hard upgrade</title>

	  <para>
		By HARD UPGRADE we mean full dump/reload of postgis-enabled databases.
		You need a HARD UPGRADE when PostGIS objects' internal storage changes
		or when SOFT UPGRADE is not possible. The
		<link linkend="release_notes">Release Notes</link>
		appendix reports for each version whether you need a dump/reload (HARD
		UPGRADE) to upgrade.
	  </para>

	  <para>
		The dump/reload process is assisted by the postgis_restore.pl
		script which takes care of skipping from the dump all
		definitions which belong to PostGIS (including old ones),
		allowing you to restore your schemas and data into a
		database with PostGIS installed without getting duplicate
		symbol errors or bringing forward deprecated objects.
	  </para>

	 <para>Supplementary instructions for windows users are available at  <ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiWinUpgrade">Windows Hard upgrade</ulink>.</para>


	  <para>
		The Procedure is as follows:
	  </para>

	<orderedlist>

	<listitem>

	  <para>
		Create a "custom-format" dump of the database you want
		to upgrade (let's call it <varname>olddb</varname>)
		include binary blobs (-b) and verbose (-v) output.
		The user can be the owner of the db, need not be postgres
		super account.
	  </para>

	  <programlisting>pg_dump -h localhost -p 5432 -U postgres -Fc -b -v -f "/somepath/olddb.backup" olddb</programlisting>

	</listitem>

	<listitem>

	  <para>
		Do a fresh install of PostGIS in a new database -- we'll
		refer to this database as <varname>newdb</varname>.
		Please refer to <xref linkend="create_new_db" /> and <xref linkend="create_new_db_extensions" /> for
		instructions on how to do this.
	  </para>

	  <para>
		The spatial_ref_sys entries found in your dump will be
		restored, but they will not override existing ones in
		spatial_ref_sys.  This is to ensure that fixes in the
		official set will be properly propagated to restored
		databases. If for any reason you really want your own
		overrides of standard entries just don't load the
		spatial_ref_sys.sql file when creating the new db.
	  </para>

	  <para>
		If your database is really old or you know you've
		been using long deprecated functions in your
		views and functions, you might need to load
		<filename>legacy.sql</filename> for all your functions
		and views etc. to properly come back.
		Only do this if _really_ needed. Consider upgrading your
		views and functions before dumping instead, if possible.
		The deprecated functions can be later removed by loading
		<filename>uninstall_legacy.sql</filename>.
	  </para>

	</listitem>

	<listitem>

	  <para>
		Restore your backup into your fresh
		<varname>newdb</varname> database using
		postgis_restore.pl.
		Unexpected errors, if any, will be printed to the standard
		error stream by psql. Keep a log of those.
	  </para>

	  <programlisting>perl utils/postgis_restore.pl "/somepath/olddb.backup" | psql -h localhost -p 5432 -U postgres newdb 2> errors.txt</programlisting>

	</listitem>

	</orderedlist>

	<para>
		Errors may arise in the following cases:
	</para>

	<orderedlist>
	<listitem>
	<para>
		Some of your views or functions make use of deprecated PostGIS objects.
		In order to fix this you may try loading <filename>legacy.sql</filename>
		script prior to restore or you'll have to restore to a
		version of PostGIS which still contains those objects
		and try a migration again after porting your code.
		If the <filename>legacy.sql</filename> way works for you, don't forget
		to fix your code to stop using deprecated functions and drop them
		loading <filename>uninstall_legacy.sql</filename>.
	</para>
	</listitem>
	<listitem>
	<para>
		Some custom records of spatial_ref_sys in dump file have
		an invalid SRID value. Valid SRID values are bigger than 0
		and smaller than 999000. Values in the 999000.999999 range
    are reserved for internal use while values > 999999 can't
    be used at all.
    All your custom records with invalid SRIDs will be retained,
    with those > 999999 moved into the reserved range, but the
    spatial_ref_sys table would lose a check constraint guarding
    for that invariant to hold and possibly also its primary key
    ( when multiple invalid SRIDS get converted to the same reserved
    SRID value ).
  </para>

  <para>
		In order to fix this you should copy your custom SRS to
		a SRID with a valid value (maybe in the 910000..910999
		range), convert all your tables to the new srid (see
		<xref linkend="UpdateGeometrySRID"/>), delete the invalid
		entry from spatial_ref_sys and re-construct the check(s) with:

		<programlisting>ALTER TABLE spatial_ref_sys ADD CONSTRAINT spatial_ref_sys_srid_check check (srid &gt; 0 AND srid &lt; 999000 );</programlisting>

		<programlisting>ALTER TABLE spatial_ref_sys ADD PRIMARY KEY(srid));</programlisting>

	</para>
	</listitem>
	</orderedlist>


	</sect2>
  </sect1>

  <sect1>
	<title>Common Problems during installation</title>
	<para>
	  There are several things to check when your installation or upgrade
	  doesn't go as you expected.
	</para>

	<orderedlist>
	  <listitem>
		<para>
		  Check that you have installed PostgreSQL &min_postgres_version;
		  or newer, and that you are compiling against the same version of the
		  PostgreSQL source as the version of PostgreSQL that is running.
		  Mix-ups can occur when your (Linux) distribution has already
		  installed PostgreSQL, or you have otherwise installed PostgreSQL
		  before and forgotten about it. PostGIS will only work with PostgreSQL
		  &min_postgres_version; or newer, and strange, unexpected
		  error messages will result if you use an older version. To check the
		  version of PostgreSQL which is running, connect to the database using
		  psql and run this query:
		</para>

		<programlisting>SELECT version();</programlisting>

		<para>
		  If you are running an RPM based distribution, you can check for the
		  existence of pre-installed packages using the <command>rpm</command>
		  command as follows: <command>rpm -qa | grep postgresql</command>
		</para>
	  </listitem>

	  <listitem>
		<para>If your upgrade fails, make sure you are restoring into a database that already has PostGIS installed.</para>
		<programlisting>SELECT postgis_full_version();</programlisting>
	  </listitem>
	</orderedlist>

	<para>
	  Also check that configure has correctly detected the location and version
	  of PostgreSQL, the Proj4 library and the GEOS library.
	</para>

	<orderedlist>
	  <listitem>
		<para>
		  The output from configure is used to generate the
		  <filename>postgis_config.h</filename> file. Check that the
		  <varname>POSTGIS_PGSQL_VERSION</varname>,
		  <varname>POSTGIS_PROJ_VERSION</varname> and
		  <varname>POSTGIS_GEOS_VERSION</varname> variables have been set
		  correctly.
		</para>
	  </listitem>
	</orderedlist>
  </sect1>

  <sect1>
	<title>Loader/Dumper</title>

	<para>
	  The data loader and dumper are built and installed automatically as part
	  of the PostGIS build. To build and install them manually:
	</para>

	<programlisting># cd postgis-&last_release_version;/loader
# make
# make install</programlisting>

	<para>
	  The loader is called <filename>shp2pgsql</filename> and converts ESRI
	  Shape files into SQL suitable for loading in PostGIS/PostgreSQL. The
	  dumper is called <filename>pgsql2shp</filename> and converts PostGIS
	  tables (or queries) into ESRI Shape files. For more verbose documentation,
	  see the online help, and the manual pages.
	</para>
  </sect1>
</chapter>