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