]> git.openstreetmap.org Git - nominatim.git/blob - docs/admin/Migration.md
Merge remote-tracking branch 'upstream/master'
[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.5.0 -> master
10
11 ### Change of layout of search_name_* tables
12
13 The table need a different index for nearest place lookup. Recreate the
14 indexs suing the following shell script:
15
16 ```bash
17 for table in `psql -d nominatim -c "SELECT tablename FROM pg_tables WHERE tablename LIKE 'search_name_%'" -tA | grep -v search_name_blank`;
18 do
19     psql -d nominatim -c "DROP INDEX idx_${table}_centroid_place; CREATE INDEX idx_${table}_centroid_place ON ${table} USING gist (centroid) WHERE ((address_rank >= 2) AND (address_rank <= 25)); DROP INDEX idx_${table}_centroid_street; CREATE INDEX idx_${table}_centroid_street ON ${table} USING gist (centroid) WHERE ((address_rank >= 26) AND (address_rank <= 27))";
20 done
21 ```
22
23 ### Removal of html output
24
25 The debugging UI is no longer directly provided with Nominatim. Instead we
26 now provide a simple Javascript application. Please refer to
27 [Setting up the Nominatim UI](../Setup-Nominatim-UI) for details on how to
28 set up the UI.
29
30 The icons served together with the API responses have been moved to the
31 nominatim-ui project as well. If you want to keep the `icon` field in the
32 response, you need to set `CONST_MapIcon_URL` to the URL of the `/mapicon`
33 directory of nominatim-ui.
34
35 ### Change order during indexing
36
37 When reindexing places during updates, there is now a different order used
38 which needs a different database index. Create it with the following SQL command:
39
40 ```sql
41 CREATE INDEX idx_placex_pendingsector_rank_address
42   ON placex USING BTREE (rank_address, geometry_sector) where indexed_status > 0;
43 ```
44
45 You can then drop the old index with:
46
47 ```sql
48 DROP INDEX idx_placex_pendingsector
49 ```
50
51 ### Unused index
52
53 This index has been unused ever since the query using it was changed two years ago. Saves about 12GB on a planet installation.
54
55 ```sql
56 DROP INDEX idx_placex_geometry_reverse_lookupPoint
57 ```
58
59 ### Switching to dotenv
60
61 As part of the work changing the configuration format, the configuration for
62 the website is now using a separate configuration file. To create the
63 configuration file, run the following command after updating:
64
65 ```sh
66 ./utils/setup.php --setup-website
67 ```
68
69 ## 3.4.0 -> 3.5.0
70
71 ### New Wikipedia/Wikidata importance tables
72
73 The `wikipedia_*` tables have a new format that also includes references to
74 Wikidata. You need to update the computation functions and the tables as
75 follows:
76
77   * download the new Wikipedia tables as described in the import section
78   * reimport the tables: `./utils/setup.php --import-wikipedia-articles`
79   * update the functions: `./utils/setup.php --create-functions --enable-diff-updates`
80   * create a new lookup index:
81 ```
82 CREATE INDEX idx_placex_wikidata on placex
83 USING BTREE ((extratags -> 'wikidata'))
84 WHERE extratags ? 'wikidata' and class = 'place' and osm_type = 'N' and rank_search < 26
85 ```
86   * compute importance: `./utils/update.php --recompute-importance`
87
88 The last step takes about 10 hours on the full planet.
89
90 Remove one function (it will be recreated in the next step):
91
92 ```sql
93 DROP FUNCTION create_country(hstore,character varying);
94 ```
95
96 Finally, update all SQL functions:
97
98 ```sh
99 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
100 ```
101
102 ## 3.3.0 -> 3.4.0
103
104 ### Reorganisation of location_area_country table
105
106 The table `location_area_country` has been optimized. You need to switch to the
107 new format when you run updates. While updates are disabled, run the following
108 SQL commands:
109
110 ```sql
111 CREATE TABLE location_area_country_new AS
112   SELECT place_id, country_code, geometry FROM location_area_country;
113 DROP TABLE location_area_country;
114 ALTER TABLE location_area_country_new RENAME TO location_area_country;
115 CREATE INDEX idx_location_area_country_geometry ON location_area_country USING GIST (geometry);
116 CREATE INDEX idx_location_area_country_place_id ON location_area_country USING BTREE (place_id);
117 ```
118
119 Finally, update all SQL functions:
120
121 ```sh
122 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
123 ```
124
125 ## 3.2.0 -> 3.3.0
126
127 ### New database connection string (DSN) format
128
129 Previously database connection setting (`CONST_Database_DSN` in `settings/*.php`) had the format
130
131    * (simple) `pgsql://@/nominatim`
132    * (complex) `pgsql://johndoe:secret@machine1.domain.com:1234/db1`
133
134 The new format is
135
136    * (simple) `pgsql:dbname=nominatim`
137    * (complex) `pgsql:dbname=db1;host=machine1.domain.com;port=1234;user=johndoe;password=secret`
138
139 ### Natural Earth country boundaries no longer needed as fallback
140
141 ```
142 DROP TABLE country_naturalearthdata;
143 ```
144
145 Finally, update all SQL functions:
146
147 ```sh
148 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
149 ```
150
151 ### Configurable Address Levels
152
153 The new configurable address levels require a new table. Create it with the
154 following command:
155
156 ```sh
157 ./utils/update.php --update-address-levels
158 ```
159
160 ## 3.1.0 -> 3.2.0
161
162 ### New reverse algorithm
163
164 The reverse algorithm has changed and requires new indexes. Run the following
165 SQL statements to create the indexes:
166
167 ```
168 CREATE INDEX idx_placex_geometry_reverse_lookupPoint
169   ON placex USING gist (geometry)
170   WHERE (name is not null or housenumber is not null or rank_address between 26 and 27)
171     AND class not in ('railway','tunnel','bridge','man_made')
172     AND rank_address >= 26 AND indexed_status = 0 AND linked_place_id is null;
173 CREATE INDEX idx_placex_geometry_reverse_lookupPolygon
174   ON placex USING gist (geometry)
175   WHERE St_GeometryType(geometry) in ('ST_Polygon', 'ST_MultiPolygon')
176     AND rank_address between 4 and 25 AND type != 'postcode'
177     AND name is not null AND indexed_status = 0 AND linked_place_id is null;
178 CREATE INDEX idx_placex_geometry_reverse_placeNode
179   ON placex USING gist (geometry)
180   WHERE osm_type = 'N' AND rank_search between 5 and 25
181     AND class = 'place' AND type != 'postcode'
182     AND name is not null AND indexed_status = 0 AND linked_place_id is null;
183 ```
184
185 You also need to grant the website user access to the `country_osm_grid` table:
186
187 ```
188 GRANT SELECT ON table country_osm_grid to "www-user";
189 ```
190
191 Replace the `www-user` with the user name of your website server if necessary.
192
193 You can now drop the unused indexes:
194
195 ```
196 DROP INDEX idx_placex_reverse_geometry;
197 ```
198
199 Finally, update all SQL functions:
200
201 ```sh
202 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
203 ```
204
205 ## 3.0.0 -> 3.1.0
206
207 ### Postcode Table
208
209 A new separate table for artificially computed postcode centroids was introduced.
210 Migration to the new format is possible but **not recommended**.
211
212 Create postcode table and indexes, running the following SQL statements:
213
214 ```sql
215 CREATE TABLE location_postcode
216   (place_id BIGINT, parent_place_id BIGINT, rank_search SMALLINT,
217    rank_address SMALLINT, indexed_status SMALLINT, indexed_date TIMESTAMP,
218    country_code varchar(2), postcode TEXT,
219    geometry GEOMETRY(Geometry, 4326));
220 CREATE INDEX idx_postcode_geometry ON location_postcode USING GIST (geometry);
221 CREATE UNIQUE INDEX idx_postcode_id ON location_postcode USING BTREE (place_id);
222 CREATE INDEX idx_postcode_postcode ON location_postcode USING BTREE (postcode);
223 GRANT SELECT ON location_postcode TO "www-data";
224 drop type if exists nearfeaturecentr cascade;
225 create type nearfeaturecentr as (
226   place_id BIGINT,
227   keywords int[],
228   rank_address smallint,
229   rank_search smallint,
230   distance float,
231   isguess boolean,
232   postcode TEXT,
233   centroid GEOMETRY
234 );
235 ```
236
237 Add postcode column to `location_area` tables with SQL statement:
238
239 ```sql
240 ALTER TABLE location_area ADD COLUMN postcode TEXT;
241 ```
242
243 Then reimport the functions:
244
245 ```sh
246 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
247 ```
248
249 Create appropriate triggers with SQL:
250
251 ```sql
252 CREATE TRIGGER location_postcode_before_update BEFORE UPDATE ON location_postcode
253     FOR EACH ROW EXECUTE PROCEDURE postcode_update();
254 ```
255
256 Finally populate the postcode table (will take a while):
257
258 ```sh
259 ./utils/setup.php --calculate-postcodes --index --index-noanalyse
260 ```
261
262 This will create a working database. You may also delete the old artificial
263 postcodes now. Note that this may be expensive and is not absolutely necessary.
264 The following SQL statement will remove them:
265
266 ```sql
267 DELETE FROM place_addressline a USING placex p
268  WHERE a.address_place_id = p.place_id and p.osm_type = 'P';
269 ALTER TABLE placex DISABLE TRIGGER USER;
270 DELETE FROM placex WHERE osm_type = 'P';
271 ALTER TABLE placex ENABLE TRIGGER USER;
272 ```