docs/admin/Migration.md

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