[SCM] PostGIS branch master updated. 3.6.0beta1-25-g1689f7cdc
git at osgeo.org
git at osgeo.org
Tue Aug 12 21:32:06 PDT 2025
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "PostGIS".
The branch, master has been updated
via 1689f7cdca0de3fb9748738b160f35bbdb91a707 (commit)
from a6b12ed5008cb6fce07d43d6bfa64d975c65f657 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 1689f7cdca0de3fb9748738b160f35bbdb91a707
Author: Regina Obe <lr at pcorp.us>
Date: Wed Aug 13 00:29:14 2025 -0400
Developer documentation for our upgrade machinery.
Closes #5961 for PostGIS 3.6.0
diff --git a/doc/developer.txt b/doc/developer.txt
new file mode 100644
index 000000000..f26a973f8
--- /dev/null
+++ b/doc/developer.txt
@@ -0,0 +1,143 @@
+-------------------------------------------------------------------------
+
+TITLE: PostGIS Developer How-To
+
+AUTHOR: Name: Regina Obe
+
+DATE: 2025-08-12
+
+CATEGORY: Development Docs
+
+-------------------------------------------------------------------------
+
+When removing objects impacts upgrade
+==========================================================
+
+There are two types of function removals that impact user upgrades and should be carefully thought thru.
+
+* SQL Api functions - these are functions that are exposed to the user in the database.
+ They are either SQl, plpgsql, or C backed functions.
+
+* C Api functions -- these are postgis lib functions that back SQL Api functions
+
+* Types, Views are also exposed via SQL Api
+
+Functions internal to postgis that are never exposed and only used within postgis libraries
+can be shuffled around to your hearts content.
+
+UPGRADING C Api functions
+==========================
+
+You should avoid ever removing C Api function in Minor and Micro releases of PostGIS.
+If there is a C Api function that you badly want to remove you need to stub it so the signature still
+exists but throws an error.
+
+These functions should be removed from whatever file
+they were in and stubbed in a deprecation file. Ideally you should never do this in a micro. Only minor.
+For Major such as when PostGIS 4 comes out we could in theory skip the legacy file and just chuck the function entirely.
+
+So a function can be stubbed in 3.0.0, but not 3.0.1, though there are cases where you might as long as
+you carefully fix up the SQL signature exposing it. The reason to avoid not doing this in a micro is people often run
+ALTER EXTENSION or SELECt postgis_extensions_upgrade() in a micro.
+
+ * For the postgis extension, these should go in postgis/postgis_legacy.c the stub will look something like this.
+
+ POSTGIS_DEPRECATE("2.0.0", postgis_uses_stats)
+
+ Note the specification of the function it was removed and the name of the function
+
+ * For postgis_sfcgal, deprecated C api functions should go in sfcgal/postgis_sfcgal_legacy.c
+ * For postgis_raster, raster/rt_pg/rtpg_legacy.c
+ * postgis_topology extension has never had any deprecated functions so there is currently no legacy file for it.
+ If there comes a need to deprecate C functions, then a file topology/postgis_topology_legacy.c will be created to store these.
+ * postgis_tiger_geocoder is all sql and plpgsql so it has no C backing functions.
+
+Why do we even bother replacing a good function with a function that throws an error? Because of pg_upgrade tool used
+to upgrade PostgreSQL clusters. When pg_upgrade runs, it does not use the regular CREATE EXTENSION routine that loads function definitions from
+a file. Instead it uses a naked CREATE EXTENSION and then tries to load all functions /types /etc/ from the old databases as they existed
+meaning they point at the same .so, .dll, .dylib whatever. When it tries to load these in, it validates the library to make sure said
+functions exist in the library. If these functions don't it will bail and pg_upgrade will fail. It however will do fine
+not complain if the function exists even if all the function knows how to do is throw an error.
+
+WHY oh WHY does it use old signatures in an old database instead of a fresh CREATE EXTENSION install?
+Primarily because objects are referenced by object identifiers AKA oids in views, tables, you name it, and if you create new function
+from scratch, even if it has the same exact definition as the old, it does not have the same OID.
+As such all db internal references would be broken
+if you try to overlay the old def structures onto the new extension install.
+
+So this whole care of legacy functions is to appease pg_upgrade.
+
+
+UPGRADING SQL Api functions
+============================
+
+For most SQL Api functions, nothing special needs to be done beyond
+noting a CHANGED in version or AVAILABILITY in the respective .sql.in files.
+
+The SQL Api definitions are found in following places:
+
+* postgis extension, postgis/postgis_sql.in, geography.sql.in, postgis.bin.sql.in, or postgis_spgist.sql.in
+* postgis_raster extension raster/rt_pg/rtpostgis.sql.in
+* postgis_sfcgal extension sfcgal/sfcgal.sql.in
+* postgis_topology - topology/sql/*.sql.in
+
+We use perl scripts to stitch together these various SQL and
+read meta comments to determine what to do during an upgrade.
+The utils/create_upgrade.pl is the script that is tasked with creating upgrade scripts.
+
+The various notes you put in .sql.in files take the following form and precede the function/type/etc definition:
+
+* -- Availability: Is only informational 2.0.0 where 2.0.0 represents the version it was introduced in.
+* -- Changed: Is only informational. You'll often see an Availability comment followed by a changed comment.
+ e.g.
+ -- Availability: 0.1.0
+ -- Changed: 2.0.0 use gserialized selectivity estimators
+* -- Replaces: is both informational and also instructs the perl upgrade script to protect the user from some upgrade pains.
+ You use Replaces instead of just a simple Changed, if you are changing inputs to the function or changing
+ outputs of the function. So any change to the api
+
+ Such a comment would look something like:
+ -- Availability: 2.1.0
+ -- Changed: 3.1.0 - add zvalue=0.0 parameter
+ -- Replaces ST_Force3D(geometry) deprecated in 3.1.0
+
+ When utils/create_upgrade.pl script comes across a Replaces clause, the perl script will change the statement to do the following
+ 1) Finds the old definition
+ 2) renames the old definition to ST_Force3D_deprecated_by_postgis_310
+ 3) Installs the new version of the function.
+ 4) At the end of the upgrade script, it will try to drop the function. If the old function is bound
+ to user objects, it will leave the old function alone and warn the user as part of the upgrade, that they have objects bound to an old signature.
+
+ Why do we do this? Because all objects are bound by oids and not names. So if a user has a view or materialized view, it will be bound to
+ ST_Force3D_deprecated_by_postgis_310 and not the new ST_Force3D. We can't drop things bound to user objects without executing a
+ DROP ... CASCADE, which will destroy user objects.
+
+
+
+For some objects such as types and casts, comments are not sufficient to get create_upgrade.pl to do the right thing.
+In these cases you need to do this work yourself as needed.
+Case in point, if you are removing a signature and have no replacement for it. You just want to drop it.
+In these cases you'll put code in the before_upgrade.sql or after_upgrade.sql corresponding to the extension you are changing.
+
+
+* postgis extension - postgis/postgis_before_upgrade.sql , postgis/postgis_after_upgrade.sql
+* postgis_sfcgal - sfcgal/sfcgal_before_upgrade.sql.in, sfcgal/sfcgal_after_upgrade.sql.in
+* postgis_topology - sfcgal/topology_before_upgrade.sql.in, sfcgal/topology_after_upgrade.sql.in
+
+Helper function calls you'll find in these scripts are the following and are defined in postgis/common_before_upgrade.sql and dropped in
+postgis/common_after_upgrade.sql
+
+* _postgis_drop_function_by_signature
+* _postgis_drop_function_by_identity
+
+# these ones are new in 3.6.0 to handle the very delicate major upgrade of topology
+
+* _postgis_drop_cast_by_types
+* _postgis_add_column_to_table
+
+
+
+
+
+
+
-----------------------------------------------------------------------
Summary of changes:
doc/developer.txt | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 143 insertions(+)
create mode 100644 doc/developer.txt
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list