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