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