</sect2>
</sect1>
- <sect1>
+ <sect1 id="create_new_db">
<title>Create a spatially-enabled database</title>
<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
+ command below command. For PostgreSQL 8.4+, this is generally already installed
</para>
<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>
</sect1>
<sect1 id="templatepostgis">
<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 an HARD UPGRADE.
+ restore the dump with a HARD UPGRADE.
</para>
<sect2 id="soft_upgrade">
<para>
After compiling you should find several <filename>postgis_upgrade*.sql</filename> files. Install the one
for your version of PostGIS. For example <filename>postgis_upgrade_13_to_15.sql</filename> should be used if you are upgrading
- from PostGIS 1.3 to 1.5.
+ from PostGIS 1.3 to 1.5. 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_13_to_15.sql -d your_spatial_database</programlisting>
-
- <para>
- If a soft upgrade is not possible the script will abort and you will be
- warned about HARD UPGRADE being required, so do not hesitate to try a
- soft upgrade first.
- </para>
+ <programlisting>psql -f postgis_upgrade_20_minor.sql -d your_spatial_database</programlisting>
<note>
<para>
- If you can't find the <filename>postgis_upgrade*.sql</filename> files
- you are probably using a version prior to 1.1 and must generate that
- file by yourself. This is done with the following command:
+ 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>
-
- <programlisting>$ utils/postgis_proc_upgrade.pl postgis.sql > postgis_upgrade.sql</programlisting>
</note>
</sect2>
<title>Hard upgrade</title>
<para>
- By HARD UPGRADE we intend full dump/reload of postgis-enabled databases.
- You need an HARD UPGRADE when PostGIS objects' internal storage changes
+ 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
<para>
Create a "custom-format" dump of the database you want to upgrade (let's
- call it "olddb")
- </para>
-
- <programlisting>$ pg_dump -Fc olddb > olddb.dump</programlisting>
-
- <para>
- Restore the dump contextually upgrading PostGIS into a new database. The
- new database doesn't have to exist. postgis_restore accepts createdb
- parameters after the dump file name, and that can for instance be used
- if you are using a non-default character encoding for your database.
- Let's call it "newdb", with UNICODE as the character encoding:
+ call it "olddb") 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>$ sh utils/postgis_restore.pl postgis.sql newdb olddb.dump -E=UNICODE > restore.log</programlisting>
+ <programlisting>pg_dump -h localhost -p 5432 -U postgres -Fc -b -v -f "/somepath/olddb.backup" olddb</programlisting>
+
+ <para>If you made custom entries to your spatial_ref_sys.sql, you may want to backup this table separately or copy out the custom records.
+ The spatial_ref_sys you will end up with will be the new one packaged with the PostGIS install.</para>
- <para>
- Check that all restored dump objects really had to be restored from dump
- and do not conflict with the ones defined in postgis.sql
- </para>
+ <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" /> for instructions on how to do this.</para>
+
+ <para>Restore your backup into your fresh <varname>newdb</varname> database using pg_restore.</para>
- <programlisting>$ grep ^KEEPING restore.log | less</programlisting>
+ <programlisting>pg_restore -h localhost -p 5432 -U postgres -d newdb "/somepath/olddb.backup"</programlisting>
- <para>
- If upgrading from PostgreSQL < 8.0 to >= 8.0 you might want to
- drop the attrelid, varattnum and stats columns in the geometry_columns
- table, which are no-more needed. Keeping them won't hurt. DROPPING THEM
- WHEN REALLY NEEDED WILL DO HURT !
- </para>
-
- <programlisting>$ psql newdb -c "ALTER TABLE geometry_columns DROP attrelid"
-$ psql newdb -c "ALTER TABLE geometry_columns DROP varattnum"
-$ psql newdb -c "ALTER TABLE geometry_columns DROP stats"</programlisting>
-
- <para>
- spatial_ref_sys table is restore from the dump, to ensure your custom
- additions are kept, but the distributed one might contain modification
- so you should backup your entries, drop the table and source the new
- one. If you did make additions we assume you know how to backup them
- before upgrading the table. Replace of it with the new one is done like
- this:
- </para>
+ <para>Finally run the <varname>uninstall_legacy.sql</varname> script in this new database. NOTE: This step is
+ important even if you plan to reinstall legacy functions. This is because many functions have been revised to use default parameters, and
+ your old install would therefore restore these which would result in ambiguous name conflicts when called.</para>
+ <programlisting>psql -h localhost -p 5432 -U postgres -d newdb -f uninstall_legacy.sql</programlisting>
- <programlisting>$ psql newdb
-newdb=> truncate spatial_ref_sys;
-DROP
-newdb=> \i spatial_ref_sys.sql</programlisting>
+ <para>If your applications or GIS tools rely on old deprecated functions, you can restore these back with</para>
+ <programlisting>psql -h localhost -p 5432 -U postgres -d newdb -f legacy.sql</programlisting>
</sect2>
</sect1>
projects / postgis / commitdiff