Skip to main content

Version 2.3.0

Released: 2026-06-10

Github release page

Expire

Quick and efficient expire and re-rendering of tiles with changed data is important for OSM. Historically osm2pgsql didn’t do a great job figuring out which tiles are affected by some change. Quite some work went into this release to improve that situation. Most importantly polygons are now not expired by bounding box any more but the shape of the polygon is taken into account. For large polygons with weird shapes, this can make quite a difference.

A larger refactoring was needed to be able to support “diff expire”: When an object changes, we used to always expire all tiles intersecting the old or the new geometry of an object. We can now expire tiles based on the symmetric difference between old and new geometry. A small change in, say, a large lake will then only affect the tile(s) covering that small change, not the whole area. This feature has to be enabled using the diff_expire = true setting in the table definition.

The number of tiles to be expired can be quite large if the input geometries are large or if there are many geometries. Numbers of tiles in the billions can crash osm2pgsql because it runs out of memory. Such large numbers can also overwhelm any kind of re-rendering mechanism run after osm2pgsql to bring tiles up to date. In day-to-day processing this should not happen, but it can happen due to vandalism or misconfiguration.

To protect against this problem, this version introduces limits on the number of tiles that can be affected by a single geometry and the overall number of tiles that an expire output will generate for each run of osm2pgsql. Defaults for these limits are quite high to not negatively affect existing setups. It is recommended to review and adapt the limits for each expire output based on your configuration and expire processing.

Overall the code related to expire processing is much cleaner and some bugs in corner-cases were removed.

Style Tester

The newly added tool osm2pgsql-test-style allows you to test your Lua style file using a BDD-style testing language. osm2pgsql has tested its own styles and functionality with such BDD tests for a long time. We’ve cleaned up the code of the framework behind these tests and moved it into its own stand-alone file, so it can now be used externally.

New Id Cache Function

It is sometimes useful to process tagged nodes together with the ways they are on. Examples are barrier tags on highways (such as a lift gate) or a ford in a river. On some maps, the size and orientation of the “lift gate” or the “ford” symbol depends on the type and geometry of the way it is on.

Doing the processing for this is possible in PostGIS, but not easy and not cheap. So we added some functionality to osm2pgsql to help with this: When processing nodes, you instruct osm2pgsql in the Lua config file to store the Ids of some nodes (for instance with the “ford=yes” tag) in the “Id cache”. Later, when processing the ways this information can be retrieved and used to store the node together with the way geometry or do other processing.

Thanks to @dch0ph for bringing up this issue and testing the implementation.

Geometry Processing

We are adding more and more functionality around geometries to osm2pgsql accessible from the Lua config file. It is more convenient and often much faster to do this processing while the data is being imported instead of inside the database later on.

The Rest…

There are lots of smaller fixes, cleanups, improvements and other changes:

Man pages

Downloads

— Recent releases —

2.3.0 2.2.0 2.1.1 2.1.0 2.0.1 2.0.0 1.11.0 1.10.0 1.9.2 1.9.1 1.9.0 1.8.1 1.8.0 1.7.2 1.7.1 1.7.0 1.6.0 1.5.2 1.5.1 1.5.0 1.4.2 1.4.1 1.4.0 1.3.0 1.2.2 1.2.1 1.2.0 1.0.0