docs: different default for format on osm.org

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

diff --git a/docs/admin/Migration.md b/docs/admin/Migration.md
index 5aae344869dbeae4ec45da21429ae35668247bc3..bc6499183c4b84e63efc2fc7d5778a9353777ee2 100644 (file)
--- a/docs/admin/Migration.md
+++ b/docs/admin/Migration.md
@@ -1,12 +1,53 @@
 # Database Migrations
 
 # Database Migrations
 

-This page describes database migrations necessary to update existing databases
-to newer versions of Nominatim.
+Since version 3.7.0 Nominatim offers automatic migrations. Please follow
+the following steps:

 
 

-SQL statements should be executed from the PostgreSQL commandline. Execute
-`psql nominatim` to enter command line mode.
+* stop any updates that are potentially running
+* update Nominatim to the newer version
+* go to your project directory and run `nominatim admin --migrate`
+* (optionally) restart updates

 
 

-## 3.6.0 -> master
+Below you find additional migrations and hints about other structural and
+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.
+
+## 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
 


@@ -27,8 +68,8 @@ functionality of each script:
 * ./utils/setup.php: `import`, `freeze`, `refresh`
 * ./utils/update.php: `replication`, `add-data`, `index`, `refresh`
 * ./utils/specialphrases.php: `special-phrases`
 * ./utils/setup.php: `import`, `freeze`, `refresh`
 * ./utils/update.php: `replication`, `add-data`, `index`, `refresh`
 * ./utils/specialphrases.php: `special-phrases`

-* ./utils/check_import_finished.php: `check-database`
-* ./utils/warm.php: `warm`
+* ./utils/check_import_finished.php: `admin`
+* ./utils/warm.php: `admin`

 * ./utils/export.php: `export`
 
 Try `nominatim <command> --help` for more information about each subcommand.
 * ./utils/export.php: `export`
 
 Try `nominatim <command> --help` for more information about each subcommand.


@@ -36,6 +77,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


@@ -54,7 +101,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


@@ -98,6 +145,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