<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>
<para>Please refer to <xreflinkend="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>
GEOS geometry library, version 3.3 or greater, but GEOS 3.4+ is recommended to take full advantage of all the new functions and features. Without GEOS 3.4,
you will be missing some major enhancements such as ST_Triangles and long-running function interruption, and improvements to geometry validation and
making geometries valid such as ST_ValidDetail and ST_MakeValid. GEOS 3.3.2+ is also required for topology support. GEOS is available for download from
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+.
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.
SFCGAL, version 1.0 (or higher) could be used to provide additional 2D and 3D advanced analysis functions to PostGIS cf <xreflinkend="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.0 require at least CGAL 4.1 and Boost 1.46 (cf: <ulinkurl="http://oslandia.github.io/SFCGAL/installation.html">http://oslandia.github.io/SFCGAL/installation.html</ulink>)
In order to build the <xreflinkend="Address_Standardizer"/> you will also need PCRE <ulinkurl="http://www.pcre.org">http://www.pcre.org</ulink> (which generally is already installed on nix systems) and <code>Regex::Assemble</code> perl CPAN package. The <code>Regex::Assemble</code> is only needed for compilation, not for running in PostgreSQL.
CUnit (<filename>CUnit</filename>). This is needed for regression testing. <ulinkurl="http://cunit.sourceforge.net/">http://cunit.sourceforge.net/</ulink>
or another OS, you may find additional more detailed help at <ulinkurl="http://trac.osgeo.org/postgis/wiki/UsersWikiInstall">PostGIS User contributed compile guides</ulink> and <ulinkurl="http://trac.osgeo.org/postgis/wiki/DevWikiMain">PostGIS Dev Wiki</ulink>.</para>
<para>Pre-Built Packages for various OS are listed in <ulinkurl="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 <ulinkurl="http://www.postgis.org/download/windows/">PostGIS Windows download site</ulink>
We also have <ulinkurl="http://www.postgis.org/download/windows/experimental.php">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>
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 <ulinkurl="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
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>,
<para>You can download some pre-built ones available in html and pdf from <ulinkurl="http://www.postgis.us/study_guides">PostGIS / PostgreSQL Study Guides</ulink></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>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
<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>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>
<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>
<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>
<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>
<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>
<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 <xreflinkend="Address_Standardizer"/>.</para>
<para>This standardizer can be use in conjunction with the PostGIS packaged tiger geocoder extension as a replacement for the <xreflinkend="Normalize_Address"/> discussed.
To use as replacement refer to <xreflinkend="tiger_pagc_address_standardizing"/>.
You can also use it as a building block for your own geocoder.</para>
<para>The address standardizer relies on PCRE which is usually already installed on most Nix systems,
but you can download the latest at: <ulinkurl="http://www.pcre.org">http://www.pcre.org</ulink>. It also requires Perl with the <code>Regexp::Assemble</code> installed </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>Extras like Tiger geocoder may not be packaged in your PostGIS distribution, but will always be available in the postgis-&last_release_version;.tar.gz file. The instructions provided here are also available in the <filename>extras/tiger_geocoder/tiger_2011/README</filename></para>
<para>If you are on Windows and you don't have tar installed, you can use <ulinkurl="http://www.7-zip.org/">http://www.7-zip.org/</ulink> to unzip the PostGIS tarball.</para>
<title>Tiger Geocoder Enabling your PostGIS database: Using Extension</title>
<para>If you are using PostgreSQL 9.1+ and PostGIS 2.1.0, 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.0 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>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><para>Then run the <xreflinkend="Loader_Generate_Nation_Script"/> and <xreflinkend="Loader_Generate_Script"/> SQL functions make sure to use the name of your custom profile. So for example to do the nation load using our new profile we would:</para>
<para>Edit the <filename>tiger_loader_2012.sql</filename> 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 <xreflinkend="Loader_Generate_Nation_Script"/> and <xreflinkend="Loader_Generate_Script"/> SQL functions.
<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;
<sect2id="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 <xreflinkend="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 <xreflinkend="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 <xreflinkend="Pagc_Normalize_Address"/> can be used instead of <xreflinkend="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 <xreflinkend="rulestab"/> ( <code>tiger.pagc_rules</code>) , <xreflinkend="gaztab"/> (<code>tiger.pagc_gaz</code>), and <xreflinkend="lextab"/> (<code>tiger.pagc_lex</code>). These you can add and update to improve your standardizing experience for your own needs.</para>
<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 <xreflinkend="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 <ulinkurl="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 <ulinkurl="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 <xreflinkend="Drop_Nation_Tables_Generate_Script"/>. Before you load any state data, you need to load the nation wide data which you do with <xreflinkend="Loader_Generate_Nation_Script"/>. Which will
generate a loader script for you. <xreflinkend="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 <xreflinkend="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 <xreflinkend="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 <xreflinkend="Geocode"/></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.
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>Next drop all nation tables and load up the new ones. Generate a drop script with this SQL statement as detailed in <xreflinkend="Drop_Nation_Tables_Generate_Script"/></para>
<para>Refer to <xreflinkend="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 <xreflinkend="Drop_State_Tables_Generate_Script"/>.</para></note>
<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>
<sect3id="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>
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.
<sect3id="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 <xreflinkend="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. <emphasisrole="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
<para>Supplementary instructions for windows users are available at <ulinkurl="http://trac.osgeo.org/postgis/wiki/UsersWikiWinUpgrade">Windows Hard upgrade</ulink>.</para>