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