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 postgres commandline. Execute
   7 `psql nominatim` to enter command line mode.
   8
   9
  10 ## 3.2.0 -> master
  11
  12 ### Natural Earth country boundaries no longer needed as fallback
  13
  14 ```
  15 DROP TABLE country_naturalearthdata;
  16 ```
  17
  18 Finally, update all SQL functions:
  19
  20 ```sh
  21 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
  22 ```
  23
  24 ### Configurable Address Levels
  25
  26 The new configurable address levels require a new table. Create it with the
  27 following command:
  28
  29 ```sh
  30 ./utils/update.php --update-address-levels
  31 ```
  32
  33 ## 3.1.0 -> 3.2.0
  34
  35 ### New reverse algorithm
  36
  37 The reverse algorithm has changed and requires new indexes. Run the following
  38 SQL statements to create the indexes:
  39
  40 ```
  41 CREATE INDEX idx_placex_geometry_reverse_lookupPoint
  42   ON placex USING gist (geometry)
  43   WHERE (name is not null or housenumber is not null or rank_address between 26 and 27)
  44     AND class not in ('railway','tunnel','bridge','man_made')
  45     AND rank_address >= 26 AND indexed_status = 0 AND linked_place_id is null;
  46 CREATE INDEX idx_placex_geometry_reverse_lookupPolygon
  47   ON placex USING gist (geometry)
  48   WHERE St_GeometryType(geometry) in ('ST_Polygon', 'ST_MultiPolygon')
  49     AND rank_address between 4 and 25 AND type != 'postcode'
  50     AND name is not null AND indexed_status = 0 AND linked_place_id is null;
  51 CREATE INDEX idx_placex_geometry_reverse_placeNode
  52   ON placex USING gist (geometry)
  53   WHERE osm_type = 'N' AND rank_search between 5 and 25
  54     AND class = 'place' AND type != 'postcode'
  55     AND name is not null AND indexed_status = 0 AND linked_place_id is null;
  56 ```
  57
  58 You also need to grant the website user access to the `country_osm_grid` table:
  59
  60 ```
  61 GRANT SELECT ON table country_osm_grid to "www-user";
  62 ```
  63
  64 Replace the `www-user` with the user name of your website server if necessary.
  65
  66 You can now drop the unused indexes:
  67
  68 ```
  69 DROP INDEX idx_placex_reverse_geometry;
  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.0.0 -> 3.1.0
  79
  80 ### Postcode Table
  81
  82 A new separate table for artificially computed postcode centroids was introduced.
  83 Migration to the new format is possible but **not recommended**.
  84
  85 Create postcode table and indexes, running the following SQL statements:
  86
  87 ```sql
  88 CREATE TABLE location_postcode
  89   (place_id BIGINT, parent_place_id BIGINT, rank_search SMALLINT,
  90    rank_address SMALLINT, indexed_status SMALLINT, indexed_date TIMESTAMP,
  91    country_code varchar(2), postcode TEXT,
  92    geometry GEOMETRY(Geometry, 4326));
  93 CREATE INDEX idx_postcode_geometry ON location_postcode USING GIST (geometry);
  94 CREATE UNIQUE INDEX idx_postcode_id ON location_postcode USING BTREE (place_id);
  95 CREATE INDEX idx_postcode_postcode ON location_postcode USING BTREE (postcode);
  96 GRANT SELECT ON location_postcode TO "www-data";
  97 drop type if exists nearfeaturecentr cascade;
  98 create type nearfeaturecentr as (
  99   place_id BIGINT,
 100   keywords int[],
 101   rank_address smallint,
 102   rank_search smallint,
 103   distance float,
 104   isguess boolean,
 105   postcode TEXT,
 106   centroid GEOMETRY
 107 );
 108 ```
 109
 110 Add postcode column to `location_area` tables with SQL statement:
 111
 112 ```sql
 113 ALTER TABLE location_area ADD COLUMN postcode TEXT;
 114 ```
 115
 116 Then reimport the functions:
 117
 118 ```sh
 119 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
 120 ```
 121
 122 Create appropriate triggers with SQL:
 123
 124 ```sql
 125 CREATE TRIGGER location_postcode_before_update BEFORE UPDATE ON location_postcode
 126     FOR EACH ROW EXECUTE PROCEDURE postcode_update();
 127 ```
 128
 129 Finally populate the postcode table (will take a while):
 130
 131 ```sh
 132 ./utils/setup.php --calculate-postcodes --index --index-noanalyse
 133 ```
 134
 135 This will create a working database. You may also delete the old artificial
 136 postcodes now. Note that this may be expensive and is not absolutely necessary.
 137 The following SQL statement will remove them:
 138
 139 ```sql
 140 DELETE FROM place_addressline a USING placex p
 141  WHERE a.address_place_id = p.place_id and p.osm_type = 'P';
 142 ALTER TABLE placex DISABLE TRIGGER USER;
 143 DELETE FROM placex WHERE osm_type = 'P';
 144 ALTER TABLE placex ENABLE TRIGGER USER;
 145 ```