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