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