Nominatim/docs/admin/Advanced-Installations.md

# Advanced installations

This page contains instructions for setting up multiple countries in 
your Nominatim database. It is assumed that you have already successfully
installed the Nominatim software itself, if not return to the 
[installation page](Installation.md).

## Importing with a database user without superuser rights

Nominatim usually creates its own PostgreSQL database at the beginning of the
import process. This makes usage easier for the user but means that the
database user doing the import needs the appropriate rights.

If you prefer to run the import with a database user with limited rights,
you can do so by changing the import process as follows:

1. Run the command for database preparation with a database user with
   superuser rights. For example, to use a db user 'dbadmin' for a
   database 'nominatim', execute:

   ```
   NOMINATIM_DATABASE_DSN="pgsql:dbname=nominatim;user=dbadmin" nominatim import --prepare-database
   ```

2. Grant the import user the right to create tables. For example, foe user 'import-user':

   ```
   psql -d nominatim -c 'GRANT CREATE ON SCHEMA public TO "import-user"'
   ```

3. Now run the reminder of the import with the import user:

   ```
   NOMINATIM_DATABASE_DSN="pgsql:dbname=nominatim;user=import-user" nominatim import --continue import-from-file --osm-file file.pbf
   ```

## Importing multiple regions (without updates)

To import multiple regions in your database you can simply give multiple
OSM files to the import command:

```
nominatim import --osm-file file1.pbf --osm-file file2.pbf
```

If you already have imported a file and want to add another one, you can
use the add-data function to import the additional data as follows:

```
nominatim add-data --file <FILE>
nominatim refresh --postcodes
nominatim index -j <NUMBER OF THREADS>
```

Please note that adding additional data is always significantly slower than
the original import.

## Importing multiple regions (with updates)

If you want to import multiple regions _and_ be able to keep them up-to-date
with updates, then you can use the scripts provided in the `utils` directory.

These scripts will set up an `update` directory in your project directory,
which has the following structure:

```bash
update
 ├── europe
 │    ├── andorra
 │    │    └── sequence.state
 │    └── monaco
 │         └── sequence.state
 └── tmp
      └── europe
           ├── andorra-latest.osm.pbf
           └── monaco-latest.osm.pbf

```

The `sequence.state` files contain the sequence ID for each region. They will
be used by pyosmium to get updates. The `tmp` folder is used for import dump and
can be deleted once the import is complete.


### Setting up multiple regions

Create a project directory as described for the
[simple import](Import.md#creating-the-project-directory). If necessary,
you can also add an `.env` configuration with customized options. In particular,
you need to make sure that `NOMINATIM_REPLICATION_UPDATE_INTERVAL` and
`NOMINATIM_REPLICATION_RECHECK_INTERVAL` are set according to the update
interval of the extract server you use.

Copy the scripts `utils/import_multiple_regions.sh` and `utils/update_database.sh`
into the project directory.

Now customize both files as per your requirements

1. List of countries. e.g.

        COUNTRIES="europe/monaco europe/andorra"

2. URL to the service providing the extracts and updates. eg:

        BASEURL="https://download.geofabrik.de"
        DOWNCOUNTRYPOSTFIX="-latest.osm.pbf"

5. Followup in the update script can be set according to your installation.
   E.g. for Photon,

        FOLLOWUP="curl http://localhost:2322/nominatim-update"

    will handle the indexing.


To start the initial import, change into the project directory and run

```
    bash import_multiple_regions.sh
```

### Updating the database

Change into the project directory and run the following command:

    bash update_database.sh

This will get diffs from the replication server, import diffs and index
the database. The default replication server in the
script ([Geofabrik](https://download.geofabrik.de)) provides daily updates.

## Using an external PostgreSQL database

You can install Nominatim using a database that runs on a different server.
Simply point the configuration variable `NOMINATIM_DATABASE_DSN` to the
server and follow the standard import documentation.

The import will be faster, if the import is run directly from the database
machine. You can easily switch to a different machine for the query frontend
after the import.

## Moving the database to another machine

For some configurations it may be useful to run the import on one machine, then
move the database to another machine and run the Nominatim service from there.
For example, you might want to use a large machine to be able to run the import
quickly but only want a smaller machine for production because there is not so
much load. Or you might want to do the import once and then replicate the
database to many machines.

The important thing to keep in mind when transferring the Nominatim installation
is that you need to transfer the database _and the project directory_. Both
parts are essential for your installation.

The Nominatim database can be transferred using the `pg_dump`/`pg_restore` tool.
Make sure to use the same version of PostgreSQL and PostGIS on source and
target machine.

!!! note
    Before creating a dump of your Nominatim database, consider running
    `nominatim freeze` first. Your database looses the ability to receive further
    data updates but the resulting database is only about a third of the size
    of a full database.

Next install nominatim-api on the target machine by following the standard
installation instructions. Again, make sure to use the same version as the
source machine.

Create a project directory on your destination machine and set up the `.env`
file to match the configuration on the source machine. That's all.