docs/admin/Migration.md

   1 # Database Migrations
   2
   3 Since version 3.7.0 Nominatim offers automatic migrations. Please follow
   4 the following steps:
   5
   6 * stop any updates that are potentially running
   7 * update Nominatim to the newer version
   8 * go to your project directory and run `nominatim admin --migrate`
   9 * (optionally) restart updates
  10
  11 Below you find additional migrations and hints about other structural and
  12 breaking changes. **Please read them before running the migration.**
  13
  14 !!! note
  15     If you are migrating from a version <3.6, then you still have to follow
  16     the manual migration steps up to 3.6.
  17
  18 ## 4.1.0 -> master
  19
  20 ### New indexes for reverse lookup
  21
  22 The reverse lookup algorithm has changed slightly to improve performance.
  23 This change needs a different index in the database. The required index
  24 will be automatically build during migration. Until the new index is available
  25 performance of the /reverse endpoint is significantly reduced. You should
  26 therefore either remove traffic from the machine before attempting a
  27 version update or create the index manually **before** starting the update
  28 using the following SQL:
  29
  30 ```
  31 CREATE INDEX IF NOT EXISTS idx_placex_geometry_reverse_lookupPlaceNode
  32   ON placex USING gist (ST_Buffer(geometry, reverse_place_diameter(rank_search)))
  33   WHERE rank_address between 4 and 25 AND type != 'postcode'
  34     AND name is not null AND linked_place_id is null AND osm_type = 'N';
  35 ```
  36
  37 ## 4.0.0 -> 4.1.0
  38
  39 ### ICU tokenizer is the new default
  40
  41 Nominatim now installs the [ICU tokenizer](../customize/Tokenizers.md#icu-tokenizer)
  42 by default. This only has an effect on newly installed databases. When
  43 updating older databases, it keeps its installed tokenizer. If you still
  44 run with the legacy tokenizer, make sure to compile Nominatim with the
  45 PostgreSQL module, see [Installation](Installation.md#building-nominatim).
  46
  47 ### geocodejson output changed
  48
  49 The `type` field of the geocodejson output has changed. It now contains
  50 the address class of the object instead of the value of the OSM tag. If
  51 your client has used the `type` field, switch them to read `osm_value`
  52 instead.
  53
  54 ## 3.7.0 -> 4.0.0
  55
  56 ### NOMINATIM_PHRASE_CONFIG removed
  57
  58 Custom blacklist configurations for special phrases now need to be handed
  59 with the `--config` parameter to `nominatim special-phrases`. Alternatively
  60 you can put your custom configuration in the project directory in a file
  61 named `phrase-settings.json`.
  62
  63 Version 3.8 also removes the automatic converter for the php format of
  64 the configuration in older versions. If you are updating from Nominatim < 3.7
  65 and still work with a custom `phrase-settings.php`, you need to manually
  66 convert it into a json format.
  67
  68 ### PHP utils removed
  69
  70 The old PHP utils have now been removed completely. You need to switch to
  71 the appropriate functions of the nominatim  command line tool. See
  72 [Introducing `nominatim` command line tool](#introducing-nominatim-command-line-tool)
  73 below.
  74
  75 ## 3.6.0 -> 3.7.0
  76
  77 ### New format and name of configuration file
  78
  79 The configuration for an import is now saved in a `.env` file in the project
  80 directory. This file follows the dotenv format. For more information, see
  81 the [installation chapter](Import.md#configuration-setup-in-env).
  82
  83 To migrate to the new system, create a new project directory, add the `.env`
  84 file and port your custom configuration from `settings/local.php`. Most
  85 settings are named similar and only have received a `NOMINATIM_` prefix.
  86 Use the default settings in `settings/env.defaults` as a reference.
  87
  88 ### New location for data files
  89
  90 External data files for Wikipedia importance, postcodes etc. are no longer
  91 expected to reside in the source tree by default. Instead they will be searched
  92 in the project directory. If you have an automated setup script you must
  93 either adapt the download location or explicitly set the location of the
  94 files to the old place in your `.env`.
  95
  96 ### Introducing `nominatim` command line tool
  97
  98 The various php utilities have been replaced with a single `nominatim`
  99 command line tool. Make sure to adapt any scripts. There is no direct 1:1
 100 matching between the old utilities and the commands of nominatim CLI. The
 101 following list gives you a list of nominatim sub-commands that contain
 102 functionality of each script:
 103
 104 * ./utils/setup.php: `import`, `freeze`, `refresh`
 105 * ./utils/update.php: `replication`, `add-data`, `index`, `refresh`
 106 * ./utils/specialphrases.php: `special-phrases`
 107 * ./utils/check_import_finished.php: `admin`
 108 * ./utils/warm.php: `admin`
 109 * ./utils/export.php: `export`
 110
 111 Try `nominatim <command> --help` for more information about each subcommand.
 112
 113 `./utils/query.php` no longer exists in its old form. `nominatim search`
 114 provides a replacement but returns different output.
 115
 116 ### Switch to normalized house numbers
 117
 118 The housenumber column in the placex table uses now normalized version.
 119 The automatic migration step will convert the column but this may take a
 120 very long time. It is advisable to take the machine offline while doing that.
 121
 122 ## 3.5.0 -> 3.6.0
 123
 124 ### Change of layout of search_name_* tables
 125
 126 The table need a different index for nearest place lookup. Recreate the
 127 indexes using the following shell script:
 128
 129 ```bash
 130 for table in `psql -d nominatim -c "SELECT tablename FROM pg_tables WHERE tablename LIKE 'search_name_%'" -tA | grep -v search_name_blank`;
 131 do
 132     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))";
 133 done
 134 ```
 135
 136 ### Removal of html output
 137
 138 The debugging UI is no longer directly provided with Nominatim. Instead we
 139 now provide a simple Javascript application. Please refer to
 140 [Setting up the Nominatim UI](Setup-Nominatim-UI.md) for details on how to
 141 set up the UI.
 142
 143 The icons served together with the API responses have been moved to the
 144 nominatim-ui project as well. If you want to keep the `icon` field in the
 145 response, you need to set `CONST_MapIcon_URL` to the URL of the `/mapicon`
 146 directory of nominatim-ui.
 147
 148 ### Change order during indexing
 149
 150 When reindexing places during updates, there is now a different order used
 151 which needs a different database index. Create it with the following SQL command:
 152
 153 ```sql
 154 CREATE INDEX idx_placex_pendingsector_rank_address
 155   ON placex
 156   USING BTREE (rank_address, geometry_sector)
 157   WHERE indexed_status > 0;
 158 ```
 159
 160 You can then drop the old index with:
 161
 162 ```sql
 163 DROP INDEX idx_placex_pendingsector;
 164 ```
 165
 166 ### Unused index
 167
 168 This index has been unused ever since the query using it was changed two years ago. Saves about 12GB on a planet installation.
 169
 170 ```sql
 171 DROP INDEX idx_placex_geometry_reverse_lookupPoint;
 172 ```
 173
 174 ### Switching to dotenv
 175
 176 As part of the work changing the configuration format, the configuration for
 177 the website is now using a separate configuration file. To create the
 178 configuration file, run the following command after updating:
 179
 180 ```sh
 181 ./utils/setup.php --setup-website
 182 ```
 183
 184 ### Update SQL code
 185
 186 To update the SQL code to the leatest version run:
 187
 188 ```
 189 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 190 ```
 191
 192 ## 3.4.0 -> 3.5.0
 193
 194 ### New Wikipedia/Wikidata importance tables
 195
 196 The `wikipedia_*` tables have a new format that also includes references to
 197 Wikidata. You need to update the computation functions and the tables as
 198 follows:
 199
 200   * download the new Wikipedia tables as described in the import section
 201   * reimport the tables: `./utils/setup.php --import-wikipedia-articles`
 202   * update the functions: `./utils/setup.php --create-functions --enable-diff-updates`
 203   * create a new lookup index:
 204 ```sql
 205 CREATE INDEX idx_placex_wikidata
 206   ON placex
 207   USING BTREE ((extratags -> 'wikidata'))
 208   WHERE extratags ? 'wikidata'
 209     AND class = 'place'
 210     AND osm_type = 'N'
 211     AND rank_search < 26;
 212 ```
 213   * compute importance: `./utils/update.php --recompute-importance`
 214
 215 The last step takes about 10 hours on the full planet.
 216
 217 Remove one function (it will be recreated in the next step):
 218
 219 ```sql
 220 DROP FUNCTION create_country(hstore,character varying);
 221 ```
 222
 223 Finally, update all SQL functions:
 224
 225 ```sh
 226 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 227 ```
 228
 229 ## 3.3.0 -> 3.4.0
 230
 231 ### Reorganisation of location_area_country table
 232
 233 The table `location_area_country` has been optimized. You need to switch to the
 234 new format when you run updates. While updates are disabled, run the following
 235 SQL commands:
 236
 237 ```sql
 238 CREATE TABLE location_area_country_new AS
 239   SELECT place_id, country_code, geometry FROM location_area_country;
 240 DROP TABLE location_area_country;
 241 ALTER TABLE location_area_country_new RENAME TO location_area_country;
 242 CREATE INDEX idx_location_area_country_geometry ON location_area_country USING GIST (geometry);
 243 CREATE INDEX idx_location_area_country_place_id ON location_area_country USING BTREE (place_id);
 244 ```
 245
 246 Finally, update all SQL functions:
 247
 248 ```sh
 249 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 250 ```
 251
 252 ## 3.2.0 -> 3.3.0
 253
 254 ### New database connection string (DSN) format
 255
 256 Previously database connection setting (`CONST_Database_DSN` in `settings/*.php`) had the format
 257
 258    * (simple) `pgsql://@/nominatim`
 259    * (complex) `pgsql://johndoe:secret@machine1.domain.com:1234/db1`
 260
 261 The new format is
 262
 263    * (simple) `pgsql:dbname=nominatim`
 264    * (complex) `pgsql:dbname=db1;host=machine1.domain.com;port=1234;user=johndoe;password=secret`
 265
 266 ### Natural Earth country boundaries no longer needed as fallback
 267
 268 ```sql
 269 DROP TABLE country_naturalearthdata;
 270 ```
 271
 272 Finally, update all SQL functions:
 273
 274 ```sh
 275 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 276 ```
 277
 278 ### Configurable Address Levels
 279
 280 The new configurable address levels require a new table. Create it with the
 281 following command:
 282
 283 ```sh
 284 ./utils/update.php --update-address-levels
 285 ```
 286
 287 ## 3.1.0 -> 3.2.0
 288
 289 ### New reverse algorithm
 290
 291 The reverse algorithm has changed and requires new indexes. Run the following
 292 SQL statements to create the indexes:
 293
 294 ```sql
 295 CREATE INDEX idx_placex_geometry_reverse_lookupPoint
 296   ON placex
 297   USING gist (geometry)
 298   WHERE (name IS NOT null or housenumber IS NOT null or rank_address BETWEEN 26 AND 27)
 299     AND class NOT IN ('railway','tunnel','bridge','man_made')
 300     AND rank_address >= 26
 301     AND indexed_status = 0
 302     AND linked_place_id IS null;
 303 CREATE INDEX idx_placex_geometry_reverse_lookupPolygon
 304   ON placex USING gist (geometry)
 305   WHERE St_GeometryType(geometry) in ('ST_Polygon', 'ST_MultiPolygon')
 306     AND rank_address between 4 and 25
 307     AND type != 'postcode'
 308     AND name is not null
 309     AND indexed_status = 0
 310     AND linked_place_id is null;
 311 CREATE INDEX idx_placex_geometry_reverse_placeNode
 312   ON placex USING gist (geometry)
 313   WHERE osm_type = 'N'
 314     AND rank_search between 5 and 25
 315     AND class = 'place'
 316     AND type != 'postcode'
 317     AND name is not null
 318     AND indexed_status = 0
 319     AND linked_place_id is null;
 320 ```
 321
 322 You also need to grant the website user access to the `country_osm_grid` table:
 323
 324 ```sql
 325 GRANT SELECT ON table country_osm_grid to "www-user";
 326 ```
 327
 328 Replace the `www-user` with the user name of your website server if necessary.
 329
 330 You can now drop the unused indexes:
 331
 332 ```sql
 333 DROP INDEX idx_placex_reverse_geometry;
 334 ```
 335
 336 Finally, update all SQL functions:
 337
 338 ```sh
 339 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 340 ```
 341
 342 ## 3.0.0 -> 3.1.0
 343
 344 ### Postcode Table
 345
 346 A new separate table for artificially computed postcode centroids was introduced.
 347 Migration to the new format is possible but **not recommended**.
 348
 349 Create postcode table and indexes, running the following SQL statements:
 350
 351 ```sql
 352 CREATE TABLE location_postcode
 353   (place_id BIGINT, parent_place_id BIGINT, rank_search SMALLINT,
 354    rank_address SMALLINT, indexed_status SMALLINT, indexed_date TIMESTAMP,
 355    country_code varchar(2), postcode TEXT,
 356    geometry GEOMETRY(Geometry, 4326));
 357 CREATE INDEX idx_postcode_geometry ON location_postcode USING GIST (geometry);
 358 CREATE UNIQUE INDEX idx_postcode_id ON location_postcode USING BTREE (place_id);
 359 CREATE INDEX idx_postcode_postcode ON location_postcode USING BTREE (postcode);
 360 GRANT SELECT ON location_postcode TO "www-data";
 361 DROP TYPE IF EXISTS nearfeaturecentr CASCADE;
 362 CREATE TYPE nearfeaturecentr AS (
 363   place_id BIGINT,
 364   keywords int[],
 365   rank_address smallint,
 366   rank_search smallint,
 367   distance float,
 368   isguess boolean,
 369   postcode TEXT,
 370   centroid GEOMETRY
 371 );
 372 ```
 373
 374 Add postcode column to `location_area` tables with SQL statement:
 375
 376 ```sql
 377 ALTER TABLE location_area ADD COLUMN postcode TEXT;
 378 ```
 379
 380 Then reimport the functions:
 381
 382 ```sh
 383 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 384 ```
 385
 386 Create appropriate triggers with SQL:
 387
 388 ```sql
 389 CREATE TRIGGER location_postcode_before_update BEFORE UPDATE ON location_postcode
 390     FOR EACH ROW EXECUTE PROCEDURE postcode_update();
 391 ```
 392
 393 Finally populate the postcode table (will take a while):
 394
 395 ```sh
 396 ./utils/setup.php --calculate-postcodes --index --index-noanalyse
 397 ```
 398
 399 This will create a working database. You may also delete the old artificial
 400 postcodes now. Note that this may be expensive and is not absolutely necessary.
 401 The following SQL statement will remove them:
 402
 403 ```sql
 404 DELETE FROM place_addressline a USING placex p
 405  WHERE a.address_place_id = p.place_id and p.osm_type = 'P';
 406 ALTER TABLE placex DISABLE TRIGGER USER;
 407 DELETE FROM placex WHERE osm_type = 'P';
 408 ALTER TABLE placex ENABLE TRIGGER USER;
 409 ```