Local OSM integration
Integration applies approved changes to the local osm2pgsql reference using an OSC batch. It is not an upload to the OSM API and does not replace replication ingestion.
Supported operating sequence
- Select roots: use approved typed object versions. A persisted cursor lets bounded runs progress through candidates rather than repeatedly selecting only the first blocked roots.
- Prepare: resolve dependencies and affected parents, reconcile versions and build a consistent OSC. Retain independent roots when others are blocked.
- Check: verify the target, style, baseline and planned publication. The runner can invoke execution checks without performing an append.
- Execute: recheck the prepared batch, run osm2pgsql append, verify the result and finalise the business records.
- Derive: request optional segmentation; its outcome is recorded separately.
The production orchestration entry point is python/lbt-run-update.py. lbt-prepare-update.py, lbt-stage-update.py, lbt-execute-update.py and lbt-finalize-update.py provide lower-level operations. Do not mix ad hoc invocations with an active scheduled run.
Dependency policy
A node movement can change a way and a relation without changing those parents' own versions. The planner must therefore consider children required by a root and parents affected by those children.
- A dependency awaiting a required review blocks the relevant roots.
- A refused dependency is not automatically forced through.
- A dependency with no monitored change may be included after version, content and structural checks.
- A deletion must not leave a retained parent referencing the deleted primitive.
- A stored context must agree with the required version/content; using the latest live OSM response would not necessarily reproduce what was examined.
A regional PBF may omit distant members of large relations. Missing or inconsistent contexts remain explicit blockers. Do not disable the check to integrate an incomplete structure.
Relations and publication
Not every relation has a rendered geometry. Route-like relations can legitimately repeat a way in their ordered member list; repeated members must not be removed generically. Surface relations need their own structural and geometry checks. Nested relations and incomplete extracts must be evaluated against the executor's supported checks, not assumed correct solely because osm2pgsql accepts the file.
The supported installation uses the configured osm2pgsql version and output/style described in Installation. Changing output mode, version, projection or style is a data-pipeline change: do not substitute a different append command without checking compatibility with the created database and the verification code.
Read a run report
| Field | Interpretation |
|---|---|
mode | check or execute |
roots_selected, roots_retained, roots_blocked | Approved candidates and planner outcome |
objects | Primitives in the retained OSC, including dependencies |
partial | Some selected roots were not retained |
append_requested | Whether the runner requested a data-writing execution |
execution_invoked | Whether the child executor was invoked, including checks |
commit_confirmed | Whether integration finalisation was confirmed |
outcome, next_action | Overall result and next operational step |
Code 2 is accepted by the supplied systemd unit for business blockers, including partial success. Code 1 indicates a failed run requiring log inspection. A prepared batch is not sufficient evidence of successful preflight: inspect the child result as well.
Interruption and recovery
Keep the batch identifier, run directory, standard error and verification report. For an uncertain execution, use inspection before any recovery. Finalisation after a confirmed append must not execute a second append. The tooling refuses automatic replay of an already integrated batch.
Never repair an uncertain outcome by deleting the journal, rebuilding a new OSC against changed inputs or manually marking roots integrated. Follow the installed tools' --help and the recorded diagnostic. The troubleshooting guide lists the evidence to collect.