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