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