]> git.openstreetmap.org Git - nominatim.git/blob - docs/admin/Migration.md
Merge branch 'separate-compilation' of https://github.com/eyusupov/Nominatim into...
[nominatim.git] / 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 -> master
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 ```