add documentation for public interface of SearchDescription

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

diff --git a/docs/admin/Migration.md b/docs/admin/Migration.md
index 0400ed43aaf2e720a5ebefb4ab60dbf56e267706..fc309af1c3d9d69a089d40b280bea11dc240a747 100644 (file)
--- a/docs/admin/Migration.md
+++ b/docs/admin/Migration.md
@@ -1,12 +1,118 @@
 # 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.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 <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.
+
+### 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
+
+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
+set up the UI.
+
+The icons served together with the API responses have been moved to the
+nominatim-ui project as well. If you want to keep the `icon` field in the
+response, you need to set `CONST_MapIcon_URL` to the URL of the `/mapicon`
+directory of nominatim-ui.
+
+### Change order during indexing
+
+When reindexing places during updates, there is now a different order used
+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;
+```
+
+You can then drop the old index with:
+
+```sql
+DROP INDEX idx_placex_pendingsector;
+```
+
+### Unused index
+
+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;
+```

 
 ### Switching to dotenv
 
 
 ### Switching to dotenv
 


@@ -18,6 +124,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


@@ -29,6 +143,16 @@ follows:
   * download the new Wikipedia tables as described in the import section
   * reimport the tables: `./utils/setup.php --import-wikipedia-articles`
   * update the functions: `./utils/setup.php --create-functions --enable-diff-updates`
   * download the new Wikipedia tables as described in the import section
   * 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:
+```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`
 
 The last step takes about 10 hours on the full planet.
   * compute importance: `./utils/update.php --recompute-importance`
 
 The last step takes about 10 hours on the full planet.


@@ -84,7 +208,7 @@ The new format is
 
 ### Natural Earth country boundaries no longer needed as fallback
 
 
 ### Natural Earth country boundaries no longer needed as fallback
 

-```
+```sql

 DROP TABLE country_naturalearthdata;
 ```
 
 DROP TABLE country_naturalearthdata;
 ```
 


@@ -110,27 +234,37 @@ following command:
 The reverse algorithm has changed and requires new indexes. Run the following
 SQL statements to create the indexes:
 
 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
 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')
 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)
 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:
 
 ```
 
 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";
 ```
 
 GRANT SELECT ON table country_osm_grid to "www-user";
 ```
 


@@ -138,7 +272,7 @@ Replace the `www-user` with the user name of your website server if necessary.
 
 You can now drop the unused indexes:
 
 
 You can now drop the unused indexes:
 

-```
+```sql

 DROP INDEX idx_placex_reverse_geometry;
 ```
 
 DROP INDEX idx_placex_reverse_geometry;
 ```
 


@@ -167,8 +301,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";
 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,
   place_id BIGINT,
   keywords int[],
   rank_address smallint,