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