X-Git-Url: https://git.openstreetmap.org./nominatim.git/blobdiff_plain/764dcd7f6459c08aafd5cf2fcb7902cc2868cb30..3f73a363f42cb3cb6627ddcea371e3a22810daa6:/docs/admin/Migration.md diff --git a/docs/admin/Migration.md b/docs/admin/Migration.md index 66b4c28b..0ca6ebf2 100644 --- a/docs/admin/Migration.md +++ b/docs/admin/Migration.md @@ -1,12 +1,80 @@ # 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.5.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.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 + +External data files for Wikipedia importance, postcodes etc. are no longer +expected to reside in the source tree by default. Instead they will be searched +in the project directory. If you have an automated setup script you must +either adapt the download location or explicitly set the location of the +files to the old place in your `.env`. + +### Introducing `nominatim` command line tool + +The various php utilities have been replaced with a single `nominatim` +command line tool. Make sure to adapt any scripts. There is no direct 1:1 +matching between the old utilities and the commands of nominatim CLI. The +following list gives you a list of nominatim sub-commands that contain +functionality of each script: + +* ./utils/setup.php: `import`, `freeze`, `refresh` +* ./utils/update.php: `replication`, `add-data`, `index`, `refresh` +* ./utils/specialphrases.php: `special-phrases` +* ./utils/check_import_finished.php: `admin` +* ./utils/warm.php: `admin` +* ./utils/export.php: `export` + +Try `nominatim --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. + +### 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 + +The table need a different index for nearest place lookup. Recreate the +indexes using the following shell script: + +```bash +for table in `psql -d nominatim -c "SELECT tablename FROM pg_tables WHERE tablename LIKE 'search_name_%'" -tA | grep -v search_name_blank`; +do + psql -d nominatim -c "DROP INDEX idx_${table}_centroid_place; CREATE INDEX idx_${table}_centroid_place ON ${table} USING gist (centroid) WHERE ((address_rank >= 2) AND (address_rank <= 25)); DROP INDEX idx_${table}_centroid_street; CREATE INDEX idx_${table}_centroid_street ON ${table} USING gist (centroid) WHERE ((address_rank >= 26) AND (address_rank <= 27))"; +done +``` ### Removal of html output @@ -27,13 +95,15 @@ which needs a different database index. Create it with the following SQL command ```sql CREATE INDEX idx_placex_pendingsector_rank_address - ON placex USING BTREE (rank_address, geometry_sector) where indexed_status > 0; + ON placex + USING BTREE (rank_address, geometry_sector) + WHERE indexed_status > 0; ``` You can then drop the old index with: ```sql -DROP INDEX idx_placex_pendingsector +DROP INDEX idx_placex_pendingsector; ``` ### Unused index @@ -41,7 +111,7 @@ DROP INDEX idx_placex_pendingsector This index has been unused ever since the query using it was changed two years ago. Saves about 12GB on a planet installation. ```sql -DROP INDEX idx_placex_geometry_reverse_lookupPoint +DROP INDEX idx_placex_geometry_reverse_lookupPoint; ``` ### Switching to dotenv @@ -66,10 +136,14 @@ follows: * reimport the tables: `./utils/setup.php --import-wikipedia-articles` * update the functions: `./utils/setup.php --create-functions --enable-diff-updates` * create a new lookup index: -``` -CREATE INDEX idx_placex_wikidata on placex -USING BTREE ((extratags -> 'wikidata')) -WHERE extratags ? 'wikidata' and class = 'place' and osm_type = 'N' and rank_search < 26 +```sql +CREATE INDEX idx_placex_wikidata + ON placex + USING BTREE ((extratags -> 'wikidata')) + WHERE extratags ? 'wikidata' + AND class = 'place' + AND osm_type = 'N' + AND rank_search < 26; ``` * compute importance: `./utils/update.php --recompute-importance` @@ -126,7 +200,7 @@ The new format is ### Natural Earth country boundaries no longer needed as fallback -``` +```sql DROP TABLE country_naturalearthdata; ``` @@ -152,27 +226,37 @@ following command: The reverse algorithm has changed and requires new indexes. Run the following SQL statements to create the indexes: -``` +```sql CREATE INDEX idx_placex_geometry_reverse_lookupPoint - ON placex USING gist (geometry) - WHERE (name is not null or housenumber is not null or rank_address between 26 and 27) - AND class not in ('railway','tunnel','bridge','man_made') - AND rank_address >= 26 AND indexed_status = 0 AND linked_place_id is null; + ON placex + USING gist (geometry) + WHERE (name IS NOT null or housenumber IS NOT null or rank_address BETWEEN 26 AND 27) + AND class NOT IN ('railway','tunnel','bridge','man_made') + AND rank_address >= 26 + AND indexed_status = 0 + AND linked_place_id IS null; CREATE INDEX idx_placex_geometry_reverse_lookupPolygon ON placex USING gist (geometry) WHERE St_GeometryType(geometry) in ('ST_Polygon', 'ST_MultiPolygon') - AND rank_address between 4 and 25 AND type != 'postcode' - AND name is not null AND indexed_status = 0 AND linked_place_id is null; + AND rank_address between 4 and 25 + AND type != 'postcode' + AND name is not null + AND indexed_status = 0 + AND linked_place_id is null; CREATE INDEX idx_placex_geometry_reverse_placeNode ON placex USING gist (geometry) - WHERE osm_type = 'N' AND rank_search between 5 and 25 - AND class = 'place' AND type != 'postcode' - AND name is not null AND indexed_status = 0 AND linked_place_id is null; + WHERE osm_type = 'N' + AND rank_search between 5 and 25 + AND class = 'place' + AND type != 'postcode' + AND name is not null + AND indexed_status = 0 + AND linked_place_id is null; ``` You also need to grant the website user access to the `country_osm_grid` table: -``` +```sql GRANT SELECT ON table country_osm_grid to "www-user"; ``` @@ -180,7 +264,7 @@ Replace the `www-user` with the user name of your website server if necessary. You can now drop the unused indexes: -``` +```sql DROP INDEX idx_placex_reverse_geometry; ``` @@ -209,8 +293,8 @@ CREATE INDEX idx_postcode_geometry ON location_postcode USING GIST (geometry); CREATE UNIQUE INDEX idx_postcode_id ON location_postcode USING BTREE (place_id); CREATE INDEX idx_postcode_postcode ON location_postcode USING BTREE (postcode); GRANT SELECT ON location_postcode TO "www-data"; -drop type if exists nearfeaturecentr cascade; -create type nearfeaturecentr as ( +DROP TYPE IF EXISTS nearfeaturecentr CASCADE; +CREATE TYPE nearfeaturecentr AS ( place_id BIGINT, keywords int[], rank_address smallint,