[SCM] PostGIS branch master updated. 3.6.0rc2-15-g7dea89193
git at osgeo.org
git at osgeo.org
Thu Aug 28 07:15:21 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 7dea8919301b12b80e2565cdd153500951461786 (commit)
from 7609db888c9615e3d8a8d4ab93a6a3276dedc05a (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 7dea8919301b12b80e2565cdd153500951461786
Author: Sandro Santilli <strk at kbt.io>
Date: Thu Aug 28 16:15:01 2025 +0200
[style] drop trailing blanks
NOTE: editorconfig should have done this...
diff --git a/doc/developer.md b/doc/developer.md
index c83302e9e..3c51f4cab 100644
--- a/doc/developer.md
+++ b/doc/developer.md
@@ -42,8 +42,8 @@ The libraries of these were always separate, however the name rtpostgis- that pa
name so was renamed, but for all purposes rtpostgis of the past is equivalent to postgis_raster of the present.
All these changes were made to ease upgrade pains with pg_upgrade.
-As a developer you still have the option of having your lib files minor versioned
-for easier testing in the same cluster.
+As a developer you still have the option of having your lib files minor versioned
+for easier testing in the same cluster.
To take advantage of this feature, when configuring postgis compile, use the switch *--with-library-minor-version*
@@ -58,7 +58,7 @@ To take advantage of this feature, when configuring postgis compile, use the swi
* Only major versions can remove SQL api functions
or C api functions without stubbing (which we will cover shortly).
-* Only PostGIS first release of a major can introduce functionality that requires a pg_dump / pg_restore.
+* Only PostGIS first release of a major can introduce functionality that requires a pg_dump / pg_restore.
* Don't require newer versions of library in a micro, but you can require new versions in first release of a minor.
For example we often drop support for older versions of GEOS and PostgreSQL in a new minor release.
@@ -72,55 +72,55 @@ There are several types of removals that impact user upgrades and should be care
* C Api functions
* Types, Views, Tables are also exposed via SQL Api
-Functions internal to postgis that are never exposed and only used within postgis libraries
+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
+## UPGRADING C Api functions
You should avoid ever removing C Api function in Minor and patch 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
+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
+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.
We could even blank out all the legacy files.
-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 do not
+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 do not
run ALTER EXTENSION or SELECT postgis_extensions_upgrade() in a micro, so taking these out will break production code.
- * For the postgis extension, these should go in postgis/postgis_legacy.c the stub will look something like this.
+ * 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 version 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_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.
+ * 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
+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
+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
+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
+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
+## 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.
@@ -134,7 +134,7 @@ The SQL Api definitions are found in following places:
| `postgis_sfcgal` | `sfcgal/sfcgal_sql.in` |
| `postgis_topology` | `topology/sql/*.sql.in` |
-We use perl scripts to stitch together these various SQL and
+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.
@@ -142,13 +142,13 @@ The various notes you put in .sql.in files take the following form and precede t
* -- 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.
+ 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
+ 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:
@@ -160,13 +160,13 @@ The various notes you put in .sql.in files take the following form and precede t
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
+ 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.
+ 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
+ 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.
@@ -179,12 +179,12 @@ If you need something dropped or need to make some system changes that would pre
The relevant files for each extension are as follows:
* postgis - postgis/postgis_before_upgrade.sql , postgis/postgis_after_upgrade.sql
-* postgis_raster - raster/rtpostgis_drop.sql.in, rtpostgis_upgrade_cleanup.sql.in
+* postgis_raster - raster/rtpostgis_drop.sql.in, rtpostgis_upgrade_cleanup.sql.in
(the rtpostgis_upgrade_cleanup.sql.in is equivalent to the after_upgrade script of other extensions)
* postgis_sfcgal - sfcgal/sfcgal_before_upgrade.sql.in, sfcgal/sfcgal_after_upgrade.sql.in
* postgis_topology - topology/topology_before_upgrade.sql.in, topology/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
+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 - generally you want to use this one as it only cares about input types of functions
@@ -210,7 +210,7 @@ We have guards in place in the code to handle these for dependency libraries
* PostgreSQL
- sql.in and c files
-
+
```c
#if POSTGIS_PGSQL_VERSION >= 150
/* code that requires PostgreSQL 15+ */
@@ -219,15 +219,15 @@ We have guards in place in the code to handle these for dependency libraries
- regress/../tests.mk.in
-* GEOS
- - c:
+* GEOS
+ - c:
```c
#if POSTGIS_GEOS_VERSION < 31000
/* GEOS < 3.1 code goes here */
#endif
```
- test files:
- * **`regress/**/tests.mk.in`**
+ * **`regress/**/tests.mk.in`**
* raster/rt_pg/tests/tests.mi.in
```makefile
@@ -244,7 +244,7 @@ We have guards in place in the code to handle these for dependency libraries
/* SFCGAL 2.1+ required */
#endif
```
- - tests:
+ - tests:
* sfcgal/regress/tests.mk.in
```makefile
@@ -262,12 +262,12 @@ We have guards in place in the code to handle these for dependency libraries
```
* GDAL
- - c files
+ - c files
```c
#if POSTGIS_GDAL_VERSION < 30700
/* Logic for GDAL < 3.7 **/
#endif
- ```
+ ```
Even if a user can't use a certain function, that function still needs to be exposed,
but instead of doing something functional, will output an error that the extension needs to be compiled
-----------------------------------------------------------------------
Summary of changes:
doc/developer.md | 74 ++++++++++++++++++++++++++++----------------------------
1 file changed, 37 insertions(+), 37 deletions(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list