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