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