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.5.0 -> master
  10
  11 ### Change order during indexing
  12
  13 When reindexing places during updates, there is now a different order used
  14 which needs a different database index. Create it with the following SQL command:
  15
  16 ```sql
  17 CREATE INDEX idx_placex_pendingsector_rank_address
  18   ON placex USING BTREE (rank_address, geometry_sector) where indexed_status > 0;
  19 ```
  20
  21 You can then drop the old index with:
  22
  23 ```sql
  24 DROP INDEX idx_placex_pendingsector
  25 ```
  26
  27 ### Unused index
  28
  29 This index has been unused ever since the query using it was changed two years ago. Saves about 12GB on a planet installation.
  30
  31 ```sql
  32 DROP INDEX idx_placex_geometry_reverse_lookupPoint
  33 ```
  34
  35 ### Switching to dotenv
  36
  37 As part of the work changing the configuration format, the configuration for
  38 the website is now using a separate configuration file. To create the
  39 configuration file, run the following command after updating:
  40
  41 ```sh
  42 ./utils/setup.php --setup-website
  43 ```
  44
  45 ## 3.4.0 -> 3.5.0
  46
  47 ### New Wikipedia/Wikidata importance tables
  48
  49 The `wikipedia_*` tables have a new format that also includes references to
  50 Wikidata. You need to update the computation functions and the tables as
  51 follows:
  52
  53   * download the new Wikipedia tables as described in the import section
  54   * reimport the tables: `./utils/setup.php --import-wikipedia-articles`
  55   * update the functions: `./utils/setup.php --create-functions --enable-diff-updates`
  56   * compute importance: `./utils/update.php --recompute-importance`
  57
  58 The last step takes about 10 hours on the full planet.
  59
  60 Remove one function (it will be recreated in the next step):
  61
  62 ```sql
  63 DROP FUNCTION create_country(hstore,character varying);
  64 ```
  65
  66 Finally, update all SQL functions:
  67
  68 ```sh
  69 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
  70 ```
  71
  72 ## 3.3.0 -> 3.4.0
  73
  74 ### Reorganisation of location_area_country table
  75
  76 The table `location_area_country` has been optimized. You need to switch to the
  77 new format when you run updates. While updates are disabled, run the following
  78 SQL commands:
  79
  80 ```sql
  81 CREATE TABLE location_area_country_new AS
  82   SELECT place_id, country_code, geometry FROM location_area_country;
  83 DROP TABLE location_area_country;
  84 ALTER TABLE location_area_country_new RENAME TO location_area_country;
  85 CREATE INDEX idx_location_area_country_geometry ON location_area_country USING GIST (geometry);
  86 CREATE INDEX idx_location_area_country_place_id ON location_area_country USING BTREE (place_id);
  87 ```
  88
  89 Finally, update all SQL functions:
  90
  91 ```sh
  92 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
  93 ```
  94
  95 ## 3.2.0 -> 3.3.0
  96
  97 ### New database connection string (DSN) format
  98
  99 Previously database connection setting (`CONST_Database_DSN` in `settings/*.php`) had the format
 100
 101    * (simple) `pgsql://@/nominatim`
 102    * (complex) `pgsql://johndoe:secret@machine1.domain.com:1234/db1`
 103
 104 The new format is
 105
 106    * (simple) `pgsql:dbname=nominatim`
 107    * (complex) `pgsql:dbname=db1;host=machine1.domain.com;port=1234;user=johndoe;password=secret`
 108
 109 ### Natural Earth country boundaries no longer needed as fallback
 110
 111 ```
 112 DROP TABLE country_naturalearthdata;
 113 ```
 114
 115 Finally, update all SQL functions:
 116
 117 ```sh
 118 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 119 ```
 120
 121 ### Configurable Address Levels
 122
 123 The new configurable address levels require a new table. Create it with the
 124 following command:
 125
 126 ```sh
 127 ./utils/update.php --update-address-levels
 128 ```
 129
 130 ## 3.1.0 -> 3.2.0
 131
 132 ### New reverse algorithm
 133
 134 The reverse algorithm has changed and requires new indexes. Run the following
 135 SQL statements to create the indexes:
 136
 137 ```
 138 CREATE INDEX idx_placex_geometry_reverse_lookupPoint
 139   ON placex USING gist (geometry)
 140   WHERE (name is not null or housenumber is not null or rank_address between 26 and 27)
 141     AND class not in ('railway','tunnel','bridge','man_made')
 142     AND rank_address >= 26 AND indexed_status = 0 AND linked_place_id is null;
 143 CREATE INDEX idx_placex_geometry_reverse_lookupPolygon
 144   ON placex USING gist (geometry)
 145   WHERE St_GeometryType(geometry) in ('ST_Polygon', 'ST_MultiPolygon')
 146     AND rank_address between 4 and 25 AND type != 'postcode'
 147     AND name is not null AND indexed_status = 0 AND linked_place_id is null;
 148 CREATE INDEX idx_placex_geometry_reverse_placeNode
 149   ON placex USING gist (geometry)
 150   WHERE osm_type = 'N' AND rank_search between 5 and 25
 151     AND class = 'place' AND type != 'postcode'
 152     AND name is not null AND indexed_status = 0 AND linked_place_id is null;
 153 ```
 154
 155 You also need to grant the website user access to the `country_osm_grid` table:
 156
 157 ```
 158 GRANT SELECT ON table country_osm_grid to "www-user";
 159 ```
 160
 161 Replace the `www-user` with the user name of your website server if necessary.
 162
 163 You can now drop the unused indexes:
 164
 165 ```
 166 DROP INDEX idx_placex_reverse_geometry;
 167 ```
 168
 169 Finally, update all SQL functions:
 170
 171 ```sh
 172 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 173 ```
 174
 175 ## 3.0.0 -> 3.1.0
 176
 177 ### Postcode Table
 178
 179 A new separate table for artificially computed postcode centroids was introduced.
 180 Migration to the new format is possible but **not recommended**.
 181
 182 Create postcode table and indexes, running the following SQL statements:
 183
 184 ```sql
 185 CREATE TABLE location_postcode
 186   (place_id BIGINT, parent_place_id BIGINT, rank_search SMALLINT,
 187    rank_address SMALLINT, indexed_status SMALLINT, indexed_date TIMESTAMP,
 188    country_code varchar(2), postcode TEXT,
 189    geometry GEOMETRY(Geometry, 4326));
 190 CREATE INDEX idx_postcode_geometry ON location_postcode USING GIST (geometry);
 191 CREATE UNIQUE INDEX idx_postcode_id ON location_postcode USING BTREE (place_id);
 192 CREATE INDEX idx_postcode_postcode ON location_postcode USING BTREE (postcode);
 193 GRANT SELECT ON location_postcode TO "www-data";
 194 drop type if exists nearfeaturecentr cascade;
 195 create type nearfeaturecentr as (
 196   place_id BIGINT,
 197   keywords int[],
 198   rank_address smallint,
 199   rank_search smallint,
 200   distance float,
 201   isguess boolean,
 202   postcode TEXT,
 203   centroid GEOMETRY
 204 );
 205 ```
 206
 207 Add postcode column to `location_area` tables with SQL statement:
 208
 209 ```sql
 210 ALTER TABLE location_area ADD COLUMN postcode TEXT;
 211 ```
 212
 213 Then reimport the functions:
 214
 215 ```sh
 216 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 217 ```
 218
 219 Create appropriate triggers with SQL:
 220
 221 ```sql
 222 CREATE TRIGGER location_postcode_before_update BEFORE UPDATE ON location_postcode
 223     FOR EACH ROW EXECUTE PROCEDURE postcode_update();
 224 ```
 225
 226 Finally populate the postcode table (will take a while):
 227
 228 ```sh
 229 ./utils/setup.php --calculate-postcodes --index --index-noanalyse
 230 ```
 231
 232 This will create a working database. You may also delete the old artificial
 233 postcodes now. Note that this may be expensive and is not absolutely necessary.
 234 The following SQL statement will remove them:
 235
 236 ```sql
 237 DELETE FROM place_addressline a USING placex p
 238  WHERE a.address_place_id = p.place_id and p.osm_type = 'P';
 239 ALTER TABLE placex DISABLE TRIGGER USER;
 240 DELETE FROM placex WHERE osm_type = 'P';
 241 ALTER TABLE placex ENABLE TRIGGER USER;
 242 ```