docs/admin/Migration.md

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