docs/admin/Migration.md

   1 # Database Migrations
   2
   3 This page describes database migrations necessary to update existing databases
   4 to newer versions of Nominatim.
   5
   6 SQL statements should be executed from the PostgreSQL commandline. Execute
   7 `psql nominatim` to enter command line mode.
   8
   9 ## 3.5.0 -> master
  10
  11 ### Change of layout of search_name_* tables
  12
  13 The table need a different index for nearest place lookup. Recreate the
  14 indexs suing the following shell script:
  15
  16 ```bash
  17 for table in `psql -d nominatim -c "SELECT tablename FROM pg_tables WHERE tablename LIKE 'search_name_%'" -tA | grep -v search_name_blank`;
  18 do
  19     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))";
  20 done
  21 ```
  22
  23 ### Removal of html output
  24
  25 The debugging UI is no longer directly provided with Nominatim. Instead we
  26 now provide a simple Javascript application. Please refer to
  27 [Setting up the Nominatim UI](../Setup-Nominatim-UI) for details on how to
  28 set up the UI.
  29
  30 The icons served together with the API responses have been moved to the
  31 nominatim-ui project as well. If you want to keep the `icon` field in the
  32 response, you need to set `CONST_MapIcon_URL` to the URL of the `/mapicon`
  33 directory of nominatim-ui.
  34
  35 ### Change order during indexing
  36
  37 When reindexing places during updates, there is now a different order used
  38 which needs a different database index. Create it with the following SQL command:
  39
  40 ```sql
  41 CREATE INDEX idx_placex_pendingsector_rank_address
  42   ON placex USING BTREE (rank_address, geometry_sector) where indexed_status > 0;
  43 ```
  44
  45 You can then drop the old index with:
  46
  47 ```sql
  48 DROP INDEX idx_placex_pendingsector
  49 ```
  50
  51 ### Unused index
  52
  53 This index has been unused ever since the query using it was changed two years ago. Saves about 12GB on a planet installation.
  54
  55 ```sql
  56 DROP INDEX idx_placex_geometry_reverse_lookupPoint
  57 ```
  58
  59 ### Switching to dotenv
  60
  61 As part of the work changing the configuration format, the configuration for
  62 the website is now using a separate configuration file. To create the
  63 configuration file, run the following command after updating:
  64
  65 ```sh
  66 ./utils/setup.php --setup-website
  67 ```
  68
  69 ## 3.4.0 -> 3.5.0
  70
  71 ### New Wikipedia/Wikidata importance tables
  72
  73 The `wikipedia_*` tables have a new format that also includes references to
  74 Wikidata. You need to update the computation functions and the tables as
  75 follows:
  76
  77   * download the new Wikipedia tables as described in the import section
  78   * reimport the tables: `./utils/setup.php --import-wikipedia-articles`
  79   * update the functions: `./utils/setup.php --create-functions --enable-diff-updates`
  80   * create a new lookup index:
  81 ```
  82 CREATE INDEX idx_placex_wikidata on placex
  83 USING BTREE ((extratags -> 'wikidata'))
  84 WHERE extratags ? 'wikidata' and class = 'place' and osm_type = 'N' and rank_search < 26
  85 ```
  86   * compute importance: `./utils/update.php --recompute-importance`
  87
  88 The last step takes about 10 hours on the full planet.
  89
  90 Remove one function (it will be recreated in the next step):
  91
  92 ```sql
  93 DROP FUNCTION create_country(hstore,character varying);
  94 ```
  95
  96 Finally, update all SQL functions:
  97
  98 ```sh
  99 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 100 ```
 101
 102 ## 3.3.0 -> 3.4.0
 103
 104 ### Reorganisation of location_area_country table
 105
 106 The table `location_area_country` has been optimized. You need to switch to the
 107 new format when you run updates. While updates are disabled, run the following
 108 SQL commands:
 109
 110 ```sql
 111 CREATE TABLE location_area_country_new AS
 112   SELECT place_id, country_code, geometry FROM location_area_country;
 113 DROP TABLE location_area_country;
 114 ALTER TABLE location_area_country_new RENAME TO location_area_country;
 115 CREATE INDEX idx_location_area_country_geometry ON location_area_country USING GIST (geometry);
 116 CREATE INDEX idx_location_area_country_place_id ON location_area_country USING BTREE (place_id);
 117 ```
 118
 119 Finally, update all SQL functions:
 120
 121 ```sh
 122 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 123 ```
 124
 125 ## 3.2.0 -> 3.3.0
 126
 127 ### New database connection string (DSN) format
 128
 129 Previously database connection setting (`CONST_Database_DSN` in `settings/*.php`) had the format
 130
 131    * (simple) `pgsql://@/nominatim`
 132    * (complex) `pgsql://johndoe:secret@machine1.domain.com:1234/db1`
 133
 134 The new format is
 135
 136    * (simple) `pgsql:dbname=nominatim`
 137    * (complex) `pgsql:dbname=db1;host=machine1.domain.com;port=1234;user=johndoe;password=secret`
 138
 139 ### Natural Earth country boundaries no longer needed as fallback
 140
 141 ```
 142 DROP TABLE country_naturalearthdata;
 143 ```
 144
 145 Finally, update all SQL functions:
 146
 147 ```sh
 148 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 149 ```
 150
 151 ### Configurable Address Levels
 152
 153 The new configurable address levels require a new table. Create it with the
 154 following command:
 155
 156 ```sh
 157 ./utils/update.php --update-address-levels
 158 ```
 159
 160 ## 3.1.0 -> 3.2.0
 161
 162 ### New reverse algorithm
 163
 164 The reverse algorithm has changed and requires new indexes. Run the following
 165 SQL statements to create the indexes:
 166
 167 ```
 168 CREATE INDEX idx_placex_geometry_reverse_lookupPoint
 169   ON placex USING gist (geometry)
 170   WHERE (name is not null or housenumber is not null or rank_address between 26 and 27)
 171     AND class not in ('railway','tunnel','bridge','man_made')
 172     AND rank_address >= 26 AND indexed_status = 0 AND linked_place_id is null;
 173 CREATE INDEX idx_placex_geometry_reverse_lookupPolygon
 174   ON placex USING gist (geometry)
 175   WHERE St_GeometryType(geometry) in ('ST_Polygon', 'ST_MultiPolygon')
 176     AND rank_address between 4 and 25 AND type != 'postcode'
 177     AND name is not null AND indexed_status = 0 AND linked_place_id is null;
 178 CREATE INDEX idx_placex_geometry_reverse_placeNode
 179   ON placex USING gist (geometry)
 180   WHERE osm_type = 'N' AND rank_search between 5 and 25
 181     AND class = 'place' AND type != 'postcode'
 182     AND name is not null AND indexed_status = 0 AND linked_place_id is null;
 183 ```
 184
 185 You also need to grant the website user access to the `country_osm_grid` table:
 186
 187 ```
 188 GRANT SELECT ON table country_osm_grid to "www-user";
 189 ```
 190
 191 Replace the `www-user` with the user name of your website server if necessary.
 192
 193 You can now drop the unused indexes:
 194
 195 ```
 196 DROP INDEX idx_placex_reverse_geometry;
 197 ```
 198
 199 Finally, update all SQL functions:
 200
 201 ```sh
 202 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 203 ```
 204
 205 ## 3.0.0 -> 3.1.0
 206
 207 ### Postcode Table
 208
 209 A new separate table for artificially computed postcode centroids was introduced.
 210 Migration to the new format is possible but **not recommended**.
 211
 212 Create postcode table and indexes, running the following SQL statements:
 213
 214 ```sql
 215 CREATE TABLE location_postcode
 216   (place_id BIGINT, parent_place_id BIGINT, rank_search SMALLINT,
 217    rank_address SMALLINT, indexed_status SMALLINT, indexed_date TIMESTAMP,
 218    country_code varchar(2), postcode TEXT,
 219    geometry GEOMETRY(Geometry, 4326));
 220 CREATE INDEX idx_postcode_geometry ON location_postcode USING GIST (geometry);
 221 CREATE UNIQUE INDEX idx_postcode_id ON location_postcode USING BTREE (place_id);
 222 CREATE INDEX idx_postcode_postcode ON location_postcode USING BTREE (postcode);
 223 GRANT SELECT ON location_postcode TO "www-data";
 224 drop type if exists nearfeaturecentr cascade;
 225 create type nearfeaturecentr as (
 226   place_id BIGINT,
 227   keywords int[],
 228   rank_address smallint,
 229   rank_search smallint,
 230   distance float,
 231   isguess boolean,
 232   postcode TEXT,
 233   centroid GEOMETRY
 234 );
 235 ```
 236
 237 Add postcode column to `location_area` tables with SQL statement:
 238
 239 ```sql
 240 ALTER TABLE location_area ADD COLUMN postcode TEXT;
 241 ```
 242
 243 Then reimport the functions:
 244
 245 ```sh
 246 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 247 ```
 248
 249 Create appropriate triggers with SQL:
 250
 251 ```sql
 252 CREATE TRIGGER location_postcode_before_update BEFORE UPDATE ON location_postcode
 253     FOR EACH ROW EXECUTE PROCEDURE postcode_update();
 254 ```
 255
 256 Finally populate the postcode table (will take a while):
 257
 258 ```sh
 259 ./utils/setup.php --calculate-postcodes --index --index-noanalyse
 260 ```
 261
 262 This will create a working database. You may also delete the old artificial
 263 postcodes now. Note that this may be expensive and is not absolutely necessary.
 264 The following SQL statement will remove them:
 265
 266 ```sql
 267 DELETE FROM place_addressline a USING placex p
 268  WHERE a.address_place_id = p.place_id and p.osm_type = 'P';
 269 ALTER TABLE placex DISABLE TRIGGER USER;
 270 DELETE FROM placex WHERE osm_type = 'P';
 271 ALTER TABLE placex ENABLE TRIGGER USER;
 272 ```