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