osm2pgsql-replication.1

.TH "OSM2PGSQL-REPLICATION" "1" "2.2.0" "" ""
.SH NAME
osm2pgsql\-replication \- osm2pgsql database updater
.SH SYNOPSIS
.B osm2pgsql\-replication
[-h] {init,update,status} ...
.SH DESCRIPTION
Update an osm2pgsql database with changes from an OSM replication server.

This tool initialises the updating process by looking at the import file
or the newest object in the database. The state is then saved in a table
in the database. Subsequent runs download newly available data and apply
it to the database.

See the help of the \(cqinit\(cq and \(cqupdate\(cq command for more information on
how to use osm2pgsql-replication.

.SH
AVAILABLE COMMANDS
.TP
\fBosm2pgsql\-replication\fR \fI\,init\/\fR
Initialise the replication process.
.TP
\fBosm2pgsql\-replication\fR \fI\,update\/\fR
Download newly available data and apply it to the database.
.TP
\fBosm2pgsql\-replication\fR \fI\,status\/\fR
Print information about the current replication status, optionally as JSON.

.SH COMMAND \fI\,'osm2pgsql\-replication init'\/\fR
usage: osm2pgsql\-replication init [\-h] [\-q] [\-v] [\-d DB] [\-U NAME] [\-H HOST]
                                  [\-P PORT] [\-p PREFIX]
                                  [\-\-middle\-schema SCHEMA] [\-\-schema SCHEMA]
                                  [\-\-osm\-file FILE | \-\-server URL]
                                  [\-\-start\-at TIME]

Initialise the replication process.

This function sets the replication service to use and determines from
which date to apply updates. You must call this function at least once
to set up the replication process. It can safely be called again later
to change the replication servers or to roll back the update process and
reapply updates.

There are different methods available for initialisation. When no
additional parameters are given, the data is initialised from the data
in the database. If the data was imported from a file with replication
information and the properties table is available (for osm2pgsql >= 1.9)
then the replication from the file is used. Otherwise the minutely
update service from openstreetmap.org is used as the default replication
service. The start date is either taken from the database timestamp
(for osm2pgsql >= 1.9) or determined from the newest way in the database
by querying the OSM API about its creation date.

The replication service can be changed with the \(cq\-\-server\(cq parameter.
To use a different start date, add \(cq\-\-start\-at\(cq with an absolute
ISO timestamp (e.g. 2007\-08\-20T12:21:53Z). When the program determines the
start date from the database timestamp or way creation date, then it
subtracts another 3 hours by default to ensure that all new changes are
available. To change this rollback period, use \(cq\-\-start\-at\(cq with the
number of minutes to rollback. This rollback mode can also be used to
force initialisation to use the database date and ignore the date
from the replication information in the file.

The initialisation process can also use replication information from
an OSM file directly and ignore all other date information.
Use the command \(cqosm2pgsql-replication \-\-osm\-file <filename>\(cq for this.

.SH DEFAULT ARGUMENTS \fI\,'osm2pgsql\-replication init'\/\fR
.TP
\fB\-q\fR, \fB\-\-quiet\fR
Print only error messages

.TP
\fB\-v\fR, \fB\-\-verbose\fR
Increase verboseness of output

.SH DATABASE ARGUMENTS \fI\,'osm2pgsql\-replication init'\/\fR
The following arguments can be used to set the connection parameters to the
osm2pgsql database. You may also use libpq environment variables to set
connection parameters, see https://www.postgresql.org/docs/current/libpq\-envars.html.
If your database connection requires a password, use a pgpass file,
see https://www.postgresql.org/docs/current/libpq\-pgpass.html.

.TP
\fB\-d\fR \fI\,DB\/\fR, \fB\-\-database\fR \fI\,DB\/\fR
Name of PostgreSQL database to connect to or conninfo string

.TP
\fB\-U\fR \fI\,NAME\/\fR, \fB\-\-username\fR \fI\,NAME\/\fR, \fB\-\-user\fR \fI\,NAME\/\fR
PostgreSQL user name

.TP
\fB\-H\fR \fI\,HOST\/\fR, \fB\-\-host\fR \fI\,HOST\/\fR
Database server host name or socket location

.TP
\fB\-P\fR \fI\,PORT\/\fR, \fB\-\-port\fR \fI\,PORT\/\fR
Database server port

.TP
\fB\-p\fR \fI\,PREFIX\/\fR, \fB\-\-prefix\fR \fI\,PREFIX\/\fR
Prefix for table names (default 'planet_osm')

.TP
\fB\-\-middle\-schema\fR \fI\,SCHEMA\/\fR
Name of the schema to store the table for the replication state in

.TP
\fB\-\-schema\fR \fI\,SCHEMA\/\fR
Name of the schema for the database

.SH REPLICATION SOURCE ARGUMENTS \fI\,'osm2pgsql\-replication init'\/\fR
.TP
\fB\-\-osm\-file\fR \fI\,FILE\/\fR
Get replication information from the given file.

.TP
\fB\-\-server\fR \fI\,URL\/\fR
Use replication server at the given URL

.TP
\fB\-\-start\-at\fR \fI\,TIME\/\fR
Time when to start replication. When an absolute timestamp (in ISO format) is given, it will be used. If a number is given, then replication starts the number of minutes before the known date of the database.

.SH COMMAND \fI\,'osm2pgsql\-replication update'\/\fR
usage: osm2pgsql\-replication update update [options] [\-\- param [param ...]]

Download newly available data and apply it to the database.

The data is downloaded in chunks of \(cq\-\-max\-diff\-size\(cq MB. Each chunk is
saved in a temporary file and imported with osm2pgsql from there. The
temporary file is normally deleted afterwards unless you state an explicit
location with \(cq\-\-diff\-file\(cq. Once the database is up to date with the
replication source, the update process exits with 0.

Any additional arguments to osm2pgsql need to be given after \(cq\-\-\(cq. Database
and the prefix parameter are handed through to osm2pgsql. They do not need
to be repeated. \(cq\-\-append\(cq and \(cq\-\-slim\(cq will always be added as well.

Use the \(cq\-\-post\-processing\(cq parameter to execute a script after osm2pgsql has
run successfully. If the updates consists of multiple runs because the
maximum size of downloaded data was reached, then the script is executed
each time that osm2pgsql has run. When the post\-processing fails, then
the entire update run is considered a failure and the replication information
is not updated. That means that when 'update' is run the next time it will
recommence with downloading the diffs again and reapplying them to the
database. This is usually safe. The script receives two parameters:
the sequence ID and timestamp of the last successful run. The timestamp
may be missing in the rare case that the replication service stops responding
after the updates have been downloaded.

.TP
\fBparam\fR
Extra parameters to hand in to osm2pgsql.

.SH OPTIONS \fI\,'osm2pgsql\-replication update'\/\fR
.TP
\fB\-\-diff\-file\fR \fI\,FILE\/\fR
File to save changes before they are applied to osm2pgsql.

.TP
\fB\-\-max\-diff\-size\fR \fI\,MAX_DIFF_SIZE\/\fR
Maximum data to load in MB (default: 500MB)

.TP
\fB\-\-osm2pgsql\-cmd\fR \fI\,OSM2PGSQL_CMD\/\fR
Path to osm2pgsql command

.TP
\fB\-\-once\fR
Run updates only once, even when more data is available.

.TP
\fB\-\-post\-processing\fR \fI\,SCRIPT\/\fR
Post\-processing script to run after each execution of osm2pgsql.

.SH DEFAULT ARGUMENTS \fI\,'osm2pgsql\-replication update'\/\fR
.TP
\fB\-q\fR, \fB\-\-quiet\fR
Print only error messages

.TP
\fB\-v\fR, \fB\-\-verbose\fR
Increase verboseness of output

.SH DATABASE ARGUMENTS \fI\,'osm2pgsql\-replication update'\/\fR
The following arguments can be used to set the connection parameters to the
osm2pgsql database. You may also use libpq environment variables to set
connection parameters, see https://www.postgresql.org/docs/current/libpq\-envars.html.
If your database connection requires a password, use a pgpass file,
see https://www.postgresql.org/docs/current/libpq\-pgpass.html.

.TP
\fB\-d\fR \fI\,DB\/\fR, \fB\-\-database\fR \fI\,DB\/\fR
Name of PostgreSQL database to connect to or conninfo string

.TP
\fB\-U\fR \fI\,NAME\/\fR, \fB\-\-username\fR \fI\,NAME\/\fR, \fB\-\-user\fR \fI\,NAME\/\fR
PostgreSQL user name

.TP
\fB\-H\fR \fI\,HOST\/\fR, \fB\-\-host\fR \fI\,HOST\/\fR
Database server host name or socket location

.TP
\fB\-P\fR \fI\,PORT\/\fR, \fB\-\-port\fR \fI\,PORT\/\fR
Database server port

.TP
\fB\-p\fR \fI\,PREFIX\/\fR, \fB\-\-prefix\fR \fI\,PREFIX\/\fR
Prefix for table names (default 'planet_osm')

.TP
\fB\-\-middle\-schema\fR \fI\,SCHEMA\/\fR
Name of the schema to store the table for the replication state in

.TP
\fB\-\-schema\fR \fI\,SCHEMA\/\fR
Name of the schema for the database

.SH COMMAND \fI\,'osm2pgsql\-replication status'\/\fR
usage: osm2pgsql\-replication status [\-h] [\-q] [\-v] [\-d DB] [\-U NAME] [\-H HOST]
                                    [\-P PORT] [\-p PREFIX]
                                    [\-\-middle\-schema SCHEMA] [\-\-schema SCHEMA]
                                    [\-\-json]

Print information about the current replication status, optionally as JSON.

Sample output:

    2021\-08\-17 15:20:28 [INFO]: Using replication service 'https://planet.openstreetmap.org/replication/minute', which is at sequence 4675115 ( 2021\-08\-17T13:19:43Z )
    2021\-08\-17 15:20:28 [INFO]: Replication server's most recent data is <1 minute old
    2021\-08\-17 15:20:28 [INFO]: Local database is 8288 sequences behind the server, i.e. 5 day(s) 20 hour(s) 58 minute(s)
    2021\-08\-17 15:20:28 [INFO]: Local database's most recent data is 5 day(s) 20 hour(s) 59 minute(s) old


With the \(cq\-\-json\(cq option, the status is printed as a json object.

    {
      "server": {
        "base_url": "https://planet.openstreetmap.org/replication/minute",
        "sequence": 4675116,
        "timestamp": "2021\-08\-17T13:20:43Z",
        "age_sec": 27
      },
      "local": {
        "sequence": 4666827,
        "timestamp": "2021\-08\-11T16:21:09Z",
        "age_sec": 507601
      },
      "status": 0
    }


\(cqstatus\(cq is 0 if there were no problems getting the status. 1 & 2 for
improperly set up replication. 3 for network issues. If status is greater 0,
then the \(cqerror\(cq key is an error message (as string). \(cqstatus\(cq is used as
the exit code.

\(cqserver\(cq is the replication server's current status. \(cqsequence\(cq is its
sequence number, \(cqtimestamp\(cq the time of that, and 'age_sec' the age of the
data in seconds.

\(cqlocal\(cq is the status of your server.

.SH OPTIONS \fI\,'osm2pgsql\-replication status'\/\fR
.TP
\fB\-\-json\fR
Output status as json.

.SH DEFAULT ARGUMENTS \fI\,'osm2pgsql\-replication status'\/\fR
.TP
\fB\-q\fR, \fB\-\-quiet\fR
Print only error messages

.TP
\fB\-v\fR, \fB\-\-verbose\fR
Increase verboseness of output

.SH DATABASE ARGUMENTS \fI\,'osm2pgsql\-replication status'\/\fR
The following arguments can be used to set the connection parameters to the
osm2pgsql database. You may also use libpq environment variables to set
connection parameters, see https://www.postgresql.org/docs/current/libpq\-envars.html.
If your database connection requires a password, use a pgpass file,
see https://www.postgresql.org/docs/current/libpq\-pgpass.html.

.TP
\fB\-d\fR \fI\,DB\/\fR, \fB\-\-database\fR \fI\,DB\/\fR
Name of PostgreSQL database to connect to or conninfo string

.TP
\fB\-U\fR \fI\,NAME\/\fR, \fB\-\-username\fR \fI\,NAME\/\fR, \fB\-\-user\fR \fI\,NAME\/\fR
PostgreSQL user name

.TP
\fB\-H\fR \fI\,HOST\/\fR, \fB\-\-host\fR \fI\,HOST\/\fR
Database server host name or socket location

.TP
\fB\-P\fR \fI\,PORT\/\fR, \fB\-\-port\fR \fI\,PORT\/\fR
Database server port

.TP
\fB\-p\fR \fI\,PREFIX\/\fR, \fB\-\-prefix\fR \fI\,PREFIX\/\fR
Prefix for table names (default 'planet_osm')

.TP
\fB\-\-middle\-schema\fR \fI\,SCHEMA\/\fR
Name of the schema to store the table for the replication state in

.TP
\fB\-\-schema\fR \fI\,SCHEMA\/\fR
Name of the schema for the database
.SH SEE ALSO
* osm2pgsql website (https://osm2pgsql.org)
* osm2pgsql manual (https://osm2pgsql.org/doc/manual.html)