1 # Updating the Database
3 There are many different ways to update your Nominatim database.
4 The following section describes how to keep it up-to-date using
5 an [online replication service for OpenStreetMap data](https://wiki.openstreetmap.org/wiki/Planet.osm/diffs)
6 For a list of other methods to add or update data see the output of
7 `nominatim add-data --help`.
10 If you have configured a flatnode file for the import, then you
11 need to keep this flatnode file around for updates.
13 ### Installing the newest version of Pyosmium
15 The replication process uses
16 [Pyosmium](https://docs.osmcode.org/pyosmium/latest/updating_osm_data.html)
17 to download update data from the server.
18 It is recommended to install Pyosmium via pip.
19 Run (as the same user who will later run the updates):
22 pip3 install --user osmium
25 ### Setting up the update process
27 Next the update process needs to be initialised. By default Nominatim is configured
28 to update using the global minutely diffs.
30 If you want a different update source you will need to add some settings
31 to `.env`. For example, to use the daily country extracts
32 diffs for Ireland from Geofabrik add the following:
34 # base URL of the replication service
35 NOMINATIM_REPLICATION_URL="https://download.geofabrik.de/europe/ireland-and-northern-ireland-updates"
36 # How often upstream publishes diffs (in seconds)
37 NOMINATIM_REPLICATION_UPDATE_INTERVAL=86400
38 # How long to sleep if no update found yet (in seconds)
39 NOMINATIM_REPLICATION_RECHECK_INTERVAL=900
41 To set up the update process now run the following command:
43 nominatim replication --init
45 It outputs the date where updates will start. Recheck that this date is
48 The `replication --init` command needs to be rerun whenever the replication
51 ### Updating Nominatim
53 Nominatim supports different modes how to retrieve the update data from the
54 server. Which one you want to use depends on your exact setup and how often you
55 want to retrieve updates.
57 These instructions are for using a single source of updates. If you have
58 imported multiple country extracts and want to keep them
59 up-to-date, [Advanced installations section](Advanced-Installations.md)
60 contains instructions to set up and update multiple country extracts.
64 When the `--once` parameter is given, then Nominatim will download exactly one
65 batch of updates and then exit. This one-time mode still respects the
66 `NOMINATIM_REPLICATION_UPDATE_INTERVAL` that you have set. If according to
67 the update interval no new data has been published yet, it will go to sleep
68 until the next expected update and only then attempt to download the next batch.
70 The one-time mode is particularly useful if you want to run updates continuously
71 but need to schedule other work in between updates. For example, the main
72 service at osm.org uses it, to regularly recompute postcodes -- a process that
73 must not be run while updates are in progress. Its update script
79 # Switch to your project directory.
83 nominatim replication --once
84 if [ -f "/srv/nominatim/schedule-maintenance" ]; then
85 rm /srv/nominatim/schedule-maintenance
86 nominatim refresh --postcodes
91 A cron job then creates the file `/srv/nominatim/schedule-maintenance` once per night.
93 ##### One-time mode with systemd
95 You can run the one-time mode with a systemd timer & service.
97 Create a timer description like `/etc/systemd/system/nominatim-updates.timer`:
101 Description=Timer to start updates of Nominatim
106 Unit=nominatim-updates.service
109 WantedBy=multi-user.target
112 And then a similar service definition: `/etc/systemd/system/nominatim-updates.service`:
116 Description=Single updates of Nominatim
119 WorkingDirectory=/srv/nominatim
120 ExecStart=nominatim replication --once
121 StandardOutput=append:/var/log/nominatim-updates.log
122 StandardError=append:/var/log/nominatim-updates.error.log
128 WantedBy=multi-user.target
131 Replace the `WorkingDirectory` with your project directory. Also adapt user and
132 group names as required. `OnUnitActiveSec` defines how often the individual
133 update command is run.
135 Now activate the service and start the updates:
138 sudo systemctl daemon-reload
139 sudo systemctl enable nominatim-updates.timer
140 sudo systemctl start nominatim-updates.timer
143 You can stop future data updates, while allowing any current, in-progress
144 update steps to finish, by running `sudo systemctl stop
145 nominatim-updates.timer` and waiting until `nominatim-updates.service` isn't
146 running (`sudo systemctl is-active nominatim-updates.service`). Current output
147 from the update can be seen like above (`systemctl status
148 nominatim-updates.service`).
153 With the `--catch-up` parameter, Nominatim will immediately try to download
154 all changes from the server until the database is up-to-date. The catch-up mode
155 still respects the parameter `NOMINATIM_REPLICATION_MAX_DIFF`. It downloads and
156 applies the changes in appropriate batches until all is done.
158 The catch-up mode is foremost useful to bring the database up to speed after the
159 initial import. Give that the service usually is not in production at this
160 point, you can temporarily be a bit more generous with the batch size and
161 number of threads you use for the updates by running catch-up like this:
165 NOMINATIM_REPLICATION_MAX_DIFF=5000 nominatim replication --catch-up --threads 15
168 The catch-up mode is also useful when you want to apply updates at a lower
169 frequency than what the source publishes. You can set up a cron job to run
170 replication catch-up at whatever interval you desire.
173 When running scheduled updates with catch-up, it is a good idea to choose
174 a replication source with an update frequency that is an order of magnitude
175 lower. For example, if you want to update once a day, use an hourly updated
176 source. This makes sure that you don't miss an entire day of updates when
177 the source is unexpectedly late to publish its update.
179 If you want to use the source with the same update frequency (e.g. a daily
180 updated source with daily updates), use the
181 continuous update mode. It ensures to re-request the newest update until it
185 #### Continuous updates
188 This mode is no longer recommended to use and will removed in future
189 releases. systemd is much better
190 suited for running regular updates. Please refer to the setup
191 instructions for running one-time mode with systemd above.
193 This is the easiest mode. Simply run the replication command without any
196 nominatim replication
198 The update application keeps running forever and retrieves and applies
199 new updates from the server as they are published.
201 You can run this command as a simple systemd service. Create a service
202 description like that in `/etc/systemd/system/nominatim-updates.service`:
206 Description=Continuous updates of Nominatim
209 WorkingDirectory=/srv/nominatim
210 ExecStart=nominatim replication
211 StandardOutput=append:/var/log/nominatim-updates.log
212 StandardError=append:/var/log/nominatim-updates.error.log
218 WantedBy=multi-user.target
221 Replace the `WorkingDirectory` with your project directory. Also adapt user
222 and group names as required.
224 Now activate the service and start the updates:
227 sudo systemctl daemon-reload
228 sudo systemctl enable nominatim-updates
229 sudo systemctl start nominatim-updates