1OSM2PGSQL-REPLICATION(1) OSM2PGSQL-REPLICATION(1)
2
6 osm2pgsql-replication - osm2pgsql database updater
7
9 osm2pgsql-replication [-h] {init,update,status} ...
10
12 Update an osm2pgsql database with changes from a OSM replication
13 server.
14 This tool initialises the updating process by looking at the import
16 file
17 or the newest object in the database. The state is then saved in a ta‐
18 ble
19 in the database. Subsequent runs download newly available data and ap‐
20 ply
21 it to the database.
22 See the help of the ’init’ and ’update’ command for more information on
24 how to use osm2pgsql-replication.
25
27 Sub-commands
28 osm2pgsql-replication init
29 Initialise the replication process.
30 osm2pgsql-replication update
32 Download newly available data and apply it to the database.
33 osm2pgsql-replication status
35 Print information about the current replication status, op‐
36 tionally as JSON.
37
39 usage: osm2pgsql-replication init [-h] [-q] [-v] [-d DB] [-U NAME] [-H
40 HOST]
41 [-P PORT] [-p PREFIX]
42 [--middle-schema SCHEMA] [--schema
43 SCHEMA]
44 [--osm-file FILE | --server URL]
45 [--start-at TIME]
46 Initialise the replication process.
48 This function sets the replication service to use and determines from
50 which date to apply updates. You must call this function at least once
51 to set up the replication process. It can safely be called again later
52 to change the replication servers or to roll back the update process
53 and
54 reapply updates.
55 There are different methods available for initialisation. When no
57 additional parameters are given, the data is initialised from the data
58 in the database. If the data was imported from a file with replication
59 information and the properties table is available (for osm2pgsql >=
60 1.9)
61 then the replication from the file is used. Otherwise the minutely
62 update service from openstreetmap.org is used as the default replica‐
63 tion
64 service. The start date is either taken from the database timestamp
65 (for osm2pgsql >= 1.9) or determined from the newest way in the data‐
66 base
67 by querying the OSM API about its creation date.
68 The replication service can be changed with the ’--server’ parameter.
70 To use a different start date, add ’--start-at’ with an absolute
71 ISO timestamp (e.g. 2007-08-20T12:21:53Z). When the program determines
72 the
73 start date from the database timestamp or way creation date, then it
74 subtracts another 3 hours by default to ensure that all new changes are
75 available. To change this rollback period, use ’--start-at’ with the
76 number of minutes to rollback. This rollback mode can also be used to
77 force initialisation to use the database date and ignore the date
78 from the replication information in the file.
79 The initialisation process can also use replication information from
81 an OSM file directly and ignore all other date information.
82 Use the command ’osm2pgsql-replication --osm-file <filename>’ for this.
83 -q, --quiet
88 Print only error messages
89 -v, --verbose
92 Increase verboseness of output
93 -d DB, --database DB
96 Name of PostgreSQL database to connect to or conninfo string
97 -U NAME, --username NAME
100 PostgreSQL user name
101 -H HOST, --host HOST
104 Database server host name or socket location
105 -P PORT, --port PORT
108 Database server port
109 -p PREFIX, --prefix PREFIX
112 Prefix for table names (default 'planet_osm')
113 --middle-schema SCHEMA
116 Name of the schema to store the table for the replication state
117 in
118 --schema SCHEMA
121 Name of the schema for the database
122 --osm-file FILE
125 Get replication information from the given file.
126 --server URL
129 Use replication server at the given URL
130 --start-at TIME
133 Time when to start replication. When an absolute timestamp (in
134 ISO format) is given, it will be used. If a number is given,
135 then replication starts the number of minutes before the known
136 date of the database.
137
140 usage: osm2pgsql-replication update update [options] [-- param [param
141 ...]]
142 Download newly available data and apply it to the database.
144 The data is downloaded in chunks of ’--max-diff-size’ MB. Each chunk is
146 saved in a temporary file and imported with osm2pgsql from there. The
147 temporary file is normally deleted afterwards unless you state an ex‐
148 plicit
149 location with ’--diff-file’. Once the database is up to date with the
150 replication source, the update process exits with 0.
151 Any additional arguments to osm2pgsql need to be given after ’--’.
153 Database
154 and the prefix parameter are handed through to osm2pgsql. They do not
155 need
156 to be repeated. ’--append’ and ’--slim’ will always be added as well.
157 Use the ’--post-processing’ parameter to execute a script after
159 osm2pgsql has
160 run successfully. If the updates consists of multiple runs because the
161 maximum size of downloaded data was reached, then the script is exe‐
162 cuted
163 each time that osm2pgsql has run. When the post-processing fails, then
164 the entire update run is considered a failure and the replication in‐
165 formation
166 is not updated. That means that when 'update' is run the next time it
167 will
168 recommence with downloading the diffs again and reapplying them to the
169 database. This is usually safe. The script receives two parameters:
170 the sequence ID and timestamp of the last successful run. The timestamp
171 may be missing in the rare case that the replication service stops re‐
172 sponding
173 after the updates have been downloaded.
174 param Extra parameters to hand in to osm2pgsql.
177 --diff-file FILE
180 File to save changes before they are applied to osm2pgsql.
181 --max-diff-size MAX_DIFF_SIZE
184 Maximum data to load in MB (default: 500MB)
185 --osm2pgsql-cmd OSM2PGSQL_CMD
188 Path to osm2pgsql command
189 --once Run updates only once, even when more data is available.
192 --post-processing SCRIPT
195 Post-processing script to run after each execution of osm2pgsql.
196 -q, --quiet
199 Print only error messages
200 -v, --verbose
203 Increase verboseness of output
204 -d DB, --database DB
207 Name of PostgreSQL database to connect to or conninfo string
208 -U NAME, --username NAME
211 PostgreSQL user name
212 -H HOST, --host HOST
215 Database server host name or socket location
216 -P PORT, --port PORT
219 Database server port
220 -p PREFIX, --prefix PREFIX
223 Prefix for table names (default 'planet_osm')
224 --middle-schema SCHEMA
227 Name of the schema to store the table for the replication state
228 in
229 --schema SCHEMA
232 Name of the schema for the database
233
237 usage: osm2pgsql-replication status [-h] [-q] [-v] [-d DB] [-U NAME]
238 [-H HOST]
239 [-P PORT] [-p PREFIX]
240 [--middle-schema SCHEMA] [--schema
241 SCHEMA]
242 [--json]
243 Print information about the current replication status, optionally as
245 JSON.
246 Sample output:
248 2021-08-17 15:20:28 [INFO]: Using replication service
250 'https://planet.openstreetmap.org/replication/minute', which is at se‐
251 quence 4675115 ( 2021-08-17T13:19:43Z )
252 2021-08-17 15:20:28 [INFO]: Replication server's most recent data
253 is <1 minute old
254 2021-08-17 15:20:28 [INFO]: Local database is 8288 sequences behind
255 the server, i.e. 5 day(s) 20 hour(s) 58 minute(s)
256 2021-08-17 15:20:28 [INFO]: Local database's most recent data is 5
257 day(s) 20 hour(s) 59 minute(s) old
258 With the ’--json’ option, the status is printed as a json object.
261 {
263 "server": {
264 "base_url": "https://planet.openstreetmap.org/replica‐
265 tion/minute",
266 "sequence": 4675116,
267 "timestamp": "2021-08-17T13:20:43Z",
268 "age_sec": 27
269 },
270 "local": {
271 "sequence": 4666827,
272 "timestamp": "2021-08-11T16:21:09Z",
273 "age_sec": 507601
274 },
275 "status": 0
276 }
277 ’status’ is 0 if there were no problems getting the status. 1 & 2 for
280 improperly set up replication. 3 for network issues. If status ≠ 0,
281 then
282 the ’error’ key is an error message (as string). ’status’ is used as
283 the
284 exit code.
285 ’server’ is the replication server's current status. ’sequence’ is it's
287 sequence number, ’timestamp’ the time of that, and 'age_sec' the age of
288 the
289 data in seconds.
290 ’local’ is the status of your server.
292 --json Output status as json.
296 -q, --quiet
299 Print only error messages
300 -v, --verbose
303 Increase verboseness of output
304 -d DB, --database DB
307 Name of PostgreSQL database to connect to or conninfo string
308 -U NAME, --username NAME
311 PostgreSQL user name
312 -H HOST, --host HOST
315 Database server host name or socket location
316 -P PORT, --port PORT
319 Database server port
320 -p PREFIX, --prefix PREFIX
323 Prefix for table names (default 'planet_osm')
324 --middle-schema SCHEMA
327 Name of the schema to store the table for the replication state
328 in
329 --schema SCHEMA
332 Name of the schema for the database
333
336 * osm2pgsql website (https://osm2pgsql.org)
337 * osm2pgsql manual (https://osm2pgsql.org/doc/manual.html)
338 1.9.2 OSM2PGSQL-REPLICATION(1)