Release 2.2.0

We are excited to publish version 2.2.0 of osm2pgsql. This release adds two powerful building blocks that can be used to implement all sorts of new features. The new “Locators” and the “deleted callbacks” features seem simple by themselves, but they can be used as basis for many features that have been requested for years.

New Locator feature

This release introduces a new feature: Locators. They help with a common problem, namely how to quickly find out in which region an OSM object is. The region can be a country or any other area. A locator is initialized with one or more regions, each region has a name and a polygon or bounding box. A geometry of an OSM object can then be checked against this region list to figure out in which region(s) it is located. This check is much faster than it would be to do this inside the database after import.

Locators can be used for all sorts of interesting features, for instance:

• Read larger OSM file but import only data inside some area.
• Annotate each OSM object with the country (or other region) it is in. This can then, for instance, be used to show special highway shields for each country.
• Use the information which region the data is in for further processing, for instance setting of default values for the speed limit or using special language transliterations rules based on country.

For details see the manual and look at the example config files provided in the flex-config/locator directory.

Callbacks for deleted objects

The Lua callback functions process_node(), process_way(), and process_relation() (and their untagged companions) only get called for new or changed OSM objects. Deleted objects are usually handled behind the scenes and for most use cases this is enough.

But sometimes it is useful to also know when an object was deleted. That’s why we have new process_deleted_node/way/relation() callbacks now. These open up a lot of new processing options for working with changes. Some users do advanced processing of OSM data inside the database after the data is imported with osm2pgsql. This is much easier now because you don’t need database triggers anymore to detect and process deleted objects.

New osm2pgsql-expire command

We have added a osm2pgsql-expire command. It is currently marked as experimental so it might change without notice. You can use it to turn entries in expire files (that look like ZOOM/X/Y) into a GeoJSON file visualizing the tiles. When given an OSM data file it can generate the tile output (in expire file format or as GeoJSON). This tool is intended as a debugging aid.

Other features and fixes

• Fix: Ways and relations that didn’t change themselves but were processed due to some of their members changing were always send to the normal process_node/way/relation() callback even if they had no tags. This is now fixed, the process_untagged_*() callbacks are called instead.
• Fix problem when detecting PostGIS version at the start of osm2pgsql. If the PostGIS version can not be detected, we report that properly.
• Allow both --username and --user command line options in all commands, there was an inconsistency between osm2pgsql and osm2pgsql-replication before.
• When using the RAM middle, untagged nodes that were members of a relation were not found when building the geometry for that relation. This is now fixed and MultiPoint and GeometryCollection geometries are built correctly.
• Fixed bounding box calculation for relations with node members.
• Reworked README.md, CONTRIBUTING.md and Contribution Guide on the website.
• Refactored a lot of the boilerplate code handling the Lua integration. This code is now shorter and easier to understand and maintain.
• Fixed bugs in wildcard matching of old C transforms.
• Fixed and improved tests around index creation.
• Finally fixed the last warnings reported by clang-tidy, see https://osm2pgsql.org/news/2025/08/21/zero-warnings.html, from now on new code is only allowed in if it checks cleanly with clang-tidy.
• Various cleanups in flex example config files.
• Lots of code cleanups, mainly to bring naming and formatting to a consistent state.
• As always, some code was refactored and there were many small fixes to the code and docs.