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