From: Sandro Santilli Date: Fri, 16 Dec 2005 01:35:03 +0000 (+0000) Subject: Added notes `bout postgis_scripts_released(), postgis_scripts_installed() X-Git-Tag: pgis_1_1_0~30 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=c9ed4a8a4ad99d4bda5d042c8b6b9720953fbc14;p=postgis Added notes `bout postgis_scripts_released(), postgis_scripts_installed() and postgis_version(). Copied soft upgrade description from README file - removed most references about DBPROC/RELPROC and the like. git-svn-id: http://svn.osgeo.org/postgis/trunk@2210 b70326c6-7e19-0410-871a-916f4a2858ee --- diff --git a/doc/postgis.xml b/doc/postgis.xml index aeaebffff..0a90134a0 100644 --- a/doc/postgis.xml +++ b/doc/postgis.xml @@ -363,25 +363,21 @@ Upgrading - -Upgrading PostGIS can be tricky, because it is composed by both a shared -library and a set of definitions that are stored in the host database. - + +Upgrading existing spatial databases can be tricky as it requires +replacement or introduction of new PostGIS object definitions. + - -When the set of definitions changes (new objects, or procedural language -functions modifications) it is not always easy to have them replace the -old ones. Having a mismatch between definitions and implementations can -bring to an unstable or unsable system. - + +Unfortunately not all definitions can be easily replaced in +a live database, so sometimes your best bet is a dump/reload +process. + - -Since postgis version 0.9.0 You can check your installation state -using postgis_full_version(). -The function will warn you with a "need proc upgrade" message if a mismatch -is found. Also, it will see you if your database is still using an older -postgis library (NOTE: this is not true for postgis_version()). - + +PostGIS provides a SOFT UPGRADE procedure for minor or bugfix +releases, and an HARD UPGRADE procedure for major releases. + Before attempting to upgrade postgis, it is always worth to backup @@ -392,44 +388,29 @@ to restore the dump with an HARD UPGRADE. Soft upgrade - -By SOFT UPGRADE we intend a live replacement of objects definitions. -This is only possible in certain circumstances as not all objects -are replaceable in a live system. - - - -To know wheter a SOFT UPGRADE should work for you refer to your new -version section in the Release Notes -appendix of this manual. - - - -The postgis_full_version() -function will also show you current state -and by that you should be able to find out wheter or not SOFT UPGRADE -will be possible. You should look at the DBPROC and RELPROC values. -DBPROC are the procedures stored in the database, RELPROC are the -procedures expected by the shared library (RELeased PROCedures). -Their values represent SCRIPTS versions. If they don't match the -function will warn you with a message: "needs proc upgrade". - + +Soft upgrade consists of sourcing the lwpostgis_upgrade.sql +script in your spatial database: + - -Soft (proc) upgrade will only be possible when the DBPROC and RELPROC -versions share MAJOR and MINOR numbers. If this is the case you can -try to use the utils/postgis_proc_upgrade.pl script. Note that the -script will check for this itself so you should be safe attempting -w/out checking it manually. Here is how you do: - +psql -f lwpostgis_upgrade.sql -d your_spatial_database - + +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. + - $ make install # DON'T DO IT IF WITHOUT BACKING UP YOUR DATA ! + + +If you can't find the lwpostgis_upgrade.sql file +you are probably using a version prior to 1.1 and must generate that +file by yourself. This is done with the following command: + - $ utils/postgis_proc_upgrade.pl lwpostgis.sql | psql <db> +utils/postgis_proc_upgrade.pl lwpostgis.sql > lwpostgis_upgrade.sql + - @@ -3955,13 +3936,17 @@ dimension postgis_version() - Returns the version number of the PostGIS functions - installed in this database (deprecated, use postgis_full_version() - instead). + Returns PostGIS version number and compile-time options + + + Prior to version 1.1.0 this was a procedural function, thus possibly + returning inaccurate information (in case of incomplete database upgrades). + + - + postgis_lib_version() Returns the version number of the PostGIS library. @@ -3995,23 +3980,42 @@ dimension postgis_scripts_installed() - Returns the version number of the lwpostgis.sql script - installed in this database. + + Returns version of the postgis scripts + installed in this database. + + + + If the output of this function doesn't match the output of + postgis_scripts_released() + you probably missed to properly upgrade an existing database. + See the Upgrading section for more info. + + Availability: 0.9.0 - + postgis_scripts_released() Returns the version number of the lwpostgis.sql script released with the installed postgis lib. + + + Starting with version 1.1.0 this function returns the same + value of postgis_lib_version(). + Kept for backward compatibility. + + - Availability: 0.9.0 + Availability: 0.9.0 + +