Merge pull request #2681 from lonvia/improve-geocodejson

[nominatim.git] / docs / admin / Migration.md

diff --git a/docs/admin/Migration.md b/docs/admin/Migration.md
index 52970a33d65c078189aabf4a0537e1e15abe3385..11ee7f0558c37406599d681334b602524492f363 100644 (file)
--- a/docs/admin/Migration.md
+++ b/docs/admin/Migration.md
@@ -4,18 +4,59 @@ Since version 3.7.0 Nominatim offers automatic migrations. Please follow
 the following steps:
 
 * stop any updates that are potentially running
 the following steps:
 
 * stop any updates that are potentially running

-* update Nominatim to the nwer version
-* goto your project directory and run `nominatim admin --migrate`
+* update Nominatim to the newer version
+* go to your project directory and run `nominatim admin --migrate`

 * (optionally) restart updates
 
 Below you find additional migrations and hints about other structural and
 * (optionally) restart updates
 
 Below you find additional migrations and hints about other structural and

-breaking changes.
+breaking changes. **Please read them before running the migration.**

 
 !!! note
     If you are migrating from a version <3.6, then you still have to follow
     the manual migration steps up to 3.6.
 
 
 !!! note
     If you are migrating from a version <3.6, then you still have to follow
     the manual migration steps up to 3.6.
 

-## 3.6.0 -> master
+## 4.0.0 -> master
+
+### geocodejson output changed
+
+The `type` field of the geocodejson output has changed. It now contains
+the address class of the object instead of the value of the OSM tag. If
+your client has used the `type` field, switch them to read `osm_value`
+instead.
+
+## 3.7.0 -> 4.0.0
+
+### NOMINATIM_PHRASE_CONFIG removed
+
+Custom blacklist configurations for special phrases now need to be handed
+with the `--config` parameter to `nominatim special-phrases`. Alternatively
+you can put your custom configuration in the project directory in a file
+named `phrase-settings.json`.
+
+Version 3.8 also removes the automatic converter for the php format of
+the configuration in older versions. If you are updating from Nominatim < 3.7
+and still work with a custom `phrase-settings.php`, you need to manually
+convert it into a json format.
+
+### PHP utils removed
+
+The old PHP utils have now been removed completely. You need to switch to
+the appropriate functions of the nominatim  command line tool. See
+[Introducing `nominatim` command line tool](#introducing-nominatim-command-line-tool)
+below.
+
+## 3.6.0 -> 3.7.0
+
+### New format and name of configuration file
+
+The configuration for an import is now saved in a `.env` file in the project
+directory. This file follows the dotenv format. For more information, see
+the [installation chapter](Import.md#configuration-setup-in-env).
+
+To migrate to the new system, create a new project directory, add the `.env`
+file and port your custom configuration from `settings/local.php`. Most
+settings are named similar and only have received a `NOMINATIM_` prefix.
+Use the default settings in `settings/env.defaults` as a reference.

 
 ### New location for data files
 
 
 ### New location for data files
 


@@ -45,6 +86,12 @@ Try `nominatim <command> --help` for more information about each subcommand.
 `./utils/query.php` no longer exists in its old form. `nominatim search`
 provides a replacement but returns different output.
 
 `./utils/query.php` no longer exists in its old form. `nominatim search`
 provides a replacement but returns different output.
 

+### Switch to normalized house numbers
+
+The housenumber column in the placex table uses now normalized version.
+The automatic migration step will convert the column but this may take a
+very long time. It is advisable to take the machine offline while doing that.
+

 ## 3.5.0 -> 3.6.0
 
 ### Change of layout of search_name_* tables
 ## 3.5.0 -> 3.6.0
 
 ### Change of layout of search_name_* tables


@@ -63,7 +110,7 @@ done
 
 The debugging UI is no longer directly provided with Nominatim. Instead we
 now provide a simple Javascript application. Please refer to
 
 The debugging UI is no longer directly provided with Nominatim. Instead we
 now provide a simple Javascript application. Please refer to

-[Setting up the Nominatim UI](../Setup-Nominatim-UI) for details on how to
+[Setting up the Nominatim UI](Setup-Nominatim-UI.md) for details on how to

 set up the UI.
 
 The icons served together with the API responses have been moved to the
 set up the UI.
 
 The icons served together with the API responses have been moved to the


@@ -107,6 +154,14 @@ configuration file, run the following command after updating:
 ./utils/setup.php --setup-website
 ```
 
 ./utils/setup.php --setup-website
 ```
 

+### Update SQL code
+
+To update the SQL code to the leatest version run:
+
+```
+./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
+```
+

 ## 3.4.0 -> 3.5.0
 
 ### New Wikipedia/Wikidata importance tables
 ## 3.4.0 -> 3.5.0
 
 ### New Wikipedia/Wikidata importance tables