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