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