X-Git-Url: https://git.openstreetmap.org./nominatim.git/blobdiff_plain/f0a7850edf01ffb9419ddeb39dff181e6727f6e9..f143ecaf1c7fc39f67c4d0baf7deea38ce2914f7:/docs/admin/Migration.md diff --git a/docs/admin/Migration.md b/docs/admin/Migration.md index fc309af1..becf2f7b 100644 --- a/docs/admin/Migration.md +++ b/docs/admin/Migration.md @@ -1,19 +1,142 @@ # Database Migrations -Since version 3.7.0 Nominatim offers automatic migrations. Please follow +Nominatim offers automatic migrations for versions 4.3+. Please follow the following steps: -* 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 +* Stop any updates that are potentially running +* Update the backend: `pip install -U nominatim-db` +* Go to your project directory and run `nominatim admin --migrate` +* Update the frontend: `pip install -U nominatim-api` +* (optionally) Restart updates 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. + If you are migrating from a version <4.3, you need to install 4.3 + and migrate to 4.3 first. Then you can migrate to the current + version. It is strongly recommended to do a reimport instead. + +## 4.5.0 -> 5.0.0 + +### PHP frontend removed + +The PHP frontend has been completely removed. Please switch to the Python +frontend. + +Without the PHP code, the `nominatim refresh --website` command is no longer +needed. It currently omits a warning and does otherwise nothing. It will be +removed in later versions of Nominatim. So make sure you remove it from your +scripts. + +### CMake building removed + +Nominatim can now only be installed via pip. Please follow the installation +instructions for the current version to change to pip. + +### osm2pgsql no longer vendored in + +Nominatim no longer ships its own version of osm2pgsql. Please install a +stock version of osm2pgsql from your distribution. See the +[installation instruction for osm2pgsql](https://osm2pgsql.org/doc/install.html) +for details. A minimum version of 1.8 is required. The current stable versions +of Ubuntu and Debian already ship with an appropriate versions. For older +installation, you may have to compile a newer osm2pgsql yourself. + +### Legacy tokenizer removed + +The `legacy` tokenizer is no longer enabled. This tokenizer has been superseded +by the `ICU` tokenizer a long time ago. In the unlikely case that your database +still uses the `legacy` tokenizer, you must reimport your database. + +### osm2pgsql style overhauled + +There are some fundamental changes to how customized osm2pgsql styles should +be written. The changes are mostly backwards compatible, i.e. custom styles +should still work with the new implementation. The only exception is a +customization of the `process_tags()` function. This function is no longer +considered public and neither are the helper functions used in it. +They currently still work but will be removed at some point. If you have +been making changes to `process_tags`, please review your style and try +to switch to the new convenience functions. + +For more information on the changes, see the +[pull request](https://github.com/osm-search/Nominatim/pull/3615) +and read the new +[customization documentation](https://nominatim.org/release-docs/latest/customize/Import-Styles/). + +## 4.4.0 -> 4.5.0 + +### New structure for Python packages + +The nominatim Python package has been split into `nominatim-db` and `nominatim-api`. +Any imports need to be adapted accordingly. + +If you are running the Python frontend, change the server module from +`nominatim.server.falcon.server` to `nominatim_api.server.falcon.server`. + +If you are using the Nominatim library, all imports need to be changed +from `nominatim.api.` to `nominatim_api.`. + +If you have written custom tokenizers or sanitizers, the appropriate modules +are now found in `nominatim_db`. + +## 4.2.0 -> 4.3.0 + +### New indexes for reverse lookup + +The reverse lookup algorithm has changed slightly to improve performance. +This change needs a different index in the database. The required index +will be automatically build during migration. Until the new index is available +performance of the /reverse endpoint is significantly reduced. You should +therefore either remove traffic from the machine before attempting a +version update or create the index manually **before** starting the update +using the following SQL: + +```sql +CREATE INDEX IF NOT EXISTS idx_placex_geometry_reverse_lookupPlaceNode + ON placex USING gist (ST_Buffer(geometry, reverse_place_diameter(rank_search))) + WHERE rank_address between 4 and 25 AND type != 'postcode' + AND name is not null AND linked_place_id is null AND osm_type = 'N'; +``` + +## 4.0.0 -> 4.1.0 + +### ICU tokenizer is the new default + +Nominatim now installs the [ICU tokenizer](../customize/Tokenizers.md#icu-tokenizer) +by default. This only has an effect on newly installed databases. When +updating older databases, it keeps its installed tokenizer. If you still +run with the legacy tokenizer, make sure to compile Nominatim with the +PostgreSQL module, see [Installation](Installation.md#building-nominatim). + +### 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 @@ -80,7 +203,7 @@ done 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