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