]> git.openstreetmap.org Git - nominatim.git/blob - docs/admin/Migration.md
docs: minor spelling corrections
[nominatim.git] / docs / admin / Migration.md
1 # Database Migrations
2
3 Since version 3.7.0 Nominatim offers automatic migrations. Please follow
4 the following steps:
5
6 * stop any updates that are potentially running
7 * update Nominatim to the nwer version
8 * goto your project directory and run `nominatim admin --migrate`
9 * (optionally) restart updates
10
11 Below you find additional migrations and hints about other structural and
12 breaking changes.
13
14 !!! note
15     If you are migrating from a version <3.6, then you still have to follow
16     the manual migration steps up to 3.6.
17
18 ## 3.6.0 -> master
19
20 ### New location for data files
21
22 External data files for Wikipedia importance, postcodes etc. are no longer
23 expected to reside in the source tree by default. Instead they will be searched
24 in the project directory. If you have an automated setup script you must
25 either adapt the download location or explicitly set the location of the
26 files to the old place in your `.env`.
27
28 ### Introducing `nominatim` command line tool
29
30 The various php utilities have been replaced with a single `nominatim`
31 command line tool. Make sure to adapt any scripts. There is no direct 1:1
32 matching between the old utilities and the commands of nominatim CLI. The
33 following list gives you a list of nominatim sub-commands that contain
34 functionality of each script:
35
36 * ./utils/setup.php: `import`, `freeze`, `refresh`
37 * ./utils/update.php: `replication`, `add-data`, `index`, `refresh`
38 * ./utils/specialphrases.php: `special-phrases`
39 * ./utils/check_import_finished.php: `admin`
40 * ./utils/warm.php: `admin`
41 * ./utils/export.php: `export`
42
43 Try `nominatim <command> --help` for more information about each subcommand.
44
45 `./utils/query.php` no longer exists in its old form. `nominatim search`
46 provides a replacement but returns different output.
47
48 ## 3.5.0 -> 3.6.0
49
50 ### Change of layout of search_name_* tables
51
52 The table need a different index for nearest place lookup. Recreate the
53 indexes using the following shell script:
54
55 ```bash
56 for table in `psql -d nominatim -c "SELECT tablename FROM pg_tables WHERE tablename LIKE 'search_name_%'" -tA | grep -v search_name_blank`;
57 do
58     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))";
59 done
60 ```
61
62 ### Removal of html output
63
64 The debugging UI is no longer directly provided with Nominatim. Instead we
65 now provide a simple Javascript application. Please refer to
66 [Setting up the Nominatim UI](../Setup-Nominatim-UI) for details on how to
67 set up the UI.
68
69 The icons served together with the API responses have been moved to the
70 nominatim-ui project as well. If you want to keep the `icon` field in the
71 response, you need to set `CONST_MapIcon_URL` to the URL of the `/mapicon`
72 directory of nominatim-ui.
73
74 ### Change order during indexing
75
76 When reindexing places during updates, there is now a different order used
77 which needs a different database index. Create it with the following SQL command:
78
79 ```sql
80 CREATE INDEX idx_placex_pendingsector_rank_address
81   ON placex
82   USING BTREE (rank_address, geometry_sector)
83   WHERE indexed_status > 0;
84 ```
85
86 You can then drop the old index with:
87
88 ```sql
89 DROP INDEX idx_placex_pendingsector;
90 ```
91
92 ### Unused index
93
94 This index has been unused ever since the query using it was changed two years ago. Saves about 12GB on a planet installation.
95
96 ```sql
97 DROP INDEX idx_placex_geometry_reverse_lookupPoint;
98 ```
99
100 ### Switching to dotenv
101
102 As part of the work changing the configuration format, the configuration for
103 the website is now using a separate configuration file. To create the
104 configuration file, run the following command after updating:
105
106 ```sh
107 ./utils/setup.php --setup-website
108 ```
109
110 ## 3.4.0 -> 3.5.0
111
112 ### New Wikipedia/Wikidata importance tables
113
114 The `wikipedia_*` tables have a new format that also includes references to
115 Wikidata. You need to update the computation functions and the tables as
116 follows:
117
118   * download the new Wikipedia tables as described in the import section
119   * reimport the tables: `./utils/setup.php --import-wikipedia-articles`
120   * update the functions: `./utils/setup.php --create-functions --enable-diff-updates`
121   * create a new lookup index:
122 ```sql
123 CREATE INDEX idx_placex_wikidata
124   ON placex
125   USING BTREE ((extratags -> 'wikidata'))
126   WHERE extratags ? 'wikidata'
127     AND class = 'place'
128     AND osm_type = 'N'
129     AND rank_search < 26;
130 ```
131   * compute importance: `./utils/update.php --recompute-importance`
132
133 The last step takes about 10 hours on the full planet.
134
135 Remove one function (it will be recreated in the next step):
136
137 ```sql
138 DROP FUNCTION create_country(hstore,character varying);
139 ```
140
141 Finally, update all SQL functions:
142
143 ```sh
144 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
145 ```
146
147 ## 3.3.0 -> 3.4.0
148
149 ### Reorganisation of location_area_country table
150
151 The table `location_area_country` has been optimized. You need to switch to the
152 new format when you run updates. While updates are disabled, run the following
153 SQL commands:
154
155 ```sql
156 CREATE TABLE location_area_country_new AS
157   SELECT place_id, country_code, geometry FROM location_area_country;
158 DROP TABLE location_area_country;
159 ALTER TABLE location_area_country_new RENAME TO location_area_country;
160 CREATE INDEX idx_location_area_country_geometry ON location_area_country USING GIST (geometry);
161 CREATE INDEX idx_location_area_country_place_id ON location_area_country USING BTREE (place_id);
162 ```
163
164 Finally, update all SQL functions:
165
166 ```sh
167 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
168 ```
169
170 ## 3.2.0 -> 3.3.0
171
172 ### New database connection string (DSN) format
173
174 Previously database connection setting (`CONST_Database_DSN` in `settings/*.php`) had the format
175
176    * (simple) `pgsql://@/nominatim`
177    * (complex) `pgsql://johndoe:secret@machine1.domain.com:1234/db1`
178
179 The new format is
180
181    * (simple) `pgsql:dbname=nominatim`
182    * (complex) `pgsql:dbname=db1;host=machine1.domain.com;port=1234;user=johndoe;password=secret`
183
184 ### Natural Earth country boundaries no longer needed as fallback
185
186 ```sql
187 DROP TABLE country_naturalearthdata;
188 ```
189
190 Finally, update all SQL functions:
191
192 ```sh
193 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
194 ```
195
196 ### Configurable Address Levels
197
198 The new configurable address levels require a new table. Create it with the
199 following command:
200
201 ```sh
202 ./utils/update.php --update-address-levels
203 ```
204
205 ## 3.1.0 -> 3.2.0
206
207 ### New reverse algorithm
208
209 The reverse algorithm has changed and requires new indexes. Run the following
210 SQL statements to create the indexes:
211
212 ```sql
213 CREATE INDEX idx_placex_geometry_reverse_lookupPoint
214   ON placex
215   USING gist (geometry)
216   WHERE (name IS NOT null or housenumber IS NOT null or rank_address BETWEEN 26 AND 27)
217     AND class NOT IN ('railway','tunnel','bridge','man_made')
218     AND rank_address >= 26
219     AND indexed_status = 0
220     AND linked_place_id IS null;
221 CREATE INDEX idx_placex_geometry_reverse_lookupPolygon
222   ON placex USING gist (geometry)
223   WHERE St_GeometryType(geometry) in ('ST_Polygon', 'ST_MultiPolygon')
224     AND rank_address between 4 and 25
225     AND type != 'postcode'
226     AND name is not null
227     AND indexed_status = 0
228     AND linked_place_id is null;
229 CREATE INDEX idx_placex_geometry_reverse_placeNode
230   ON placex USING gist (geometry)
231   WHERE osm_type = 'N'
232     AND rank_search between 5 and 25
233     AND class = 'place'
234     AND type != 'postcode'
235     AND name is not null
236     AND indexed_status = 0
237     AND linked_place_id is null;
238 ```
239
240 You also need to grant the website user access to the `country_osm_grid` table:
241
242 ```sql
243 GRANT SELECT ON table country_osm_grid to "www-user";
244 ```
245
246 Replace the `www-user` with the user name of your website server if necessary.
247
248 You can now drop the unused indexes:
249
250 ```sql
251 DROP INDEX idx_placex_reverse_geometry;
252 ```
253
254 Finally, update all SQL functions:
255
256 ```sh
257 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
258 ```
259
260 ## 3.0.0 -> 3.1.0
261
262 ### Postcode Table
263
264 A new separate table for artificially computed postcode centroids was introduced.
265 Migration to the new format is possible but **not recommended**.
266
267 Create postcode table and indexes, running the following SQL statements:
268
269 ```sql
270 CREATE TABLE location_postcode
271   (place_id BIGINT, parent_place_id BIGINT, rank_search SMALLINT,
272    rank_address SMALLINT, indexed_status SMALLINT, indexed_date TIMESTAMP,
273    country_code varchar(2), postcode TEXT,
274    geometry GEOMETRY(Geometry, 4326));
275 CREATE INDEX idx_postcode_geometry ON location_postcode USING GIST (geometry);
276 CREATE UNIQUE INDEX idx_postcode_id ON location_postcode USING BTREE (place_id);
277 CREATE INDEX idx_postcode_postcode ON location_postcode USING BTREE (postcode);
278 GRANT SELECT ON location_postcode TO "www-data";
279 DROP TYPE IF EXISTS nearfeaturecentr CASCADE;
280 CREATE TYPE nearfeaturecentr AS (
281   place_id BIGINT,
282   keywords int[],
283   rank_address smallint,
284   rank_search smallint,
285   distance float,
286   isguess boolean,
287   postcode TEXT,
288   centroid GEOMETRY
289 );
290 ```
291
292 Add postcode column to `location_area` tables with SQL statement:
293
294 ```sql
295 ALTER TABLE location_area ADD COLUMN postcode TEXT;
296 ```
297
298 Then reimport the functions:
299
300 ```sh
301 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
302 ```
303
304 Create appropriate triggers with SQL:
305
306 ```sql
307 CREATE TRIGGER location_postcode_before_update BEFORE UPDATE ON location_postcode
308     FOR EACH ROW EXECUTE PROCEDURE postcode_update();
309 ```
310
311 Finally populate the postcode table (will take a while):
312
313 ```sh
314 ./utils/setup.php --calculate-postcodes --index --index-noanalyse
315 ```
316
317 This will create a working database. You may also delete the old artificial
318 postcodes now. Note that this may be expensive and is not absolutely necessary.
319 The following SQL statement will remove them:
320
321 ```sql
322 DELETE FROM place_addressline a USING placex p
323  WHERE a.address_place_id = p.place_id and p.osm_type = 'P';
324 ALTER TABLE placex DISABLE TRIGGER USER;
325 DELETE FROM placex WHERE osm_type = 'P';
326 ALTER TABLE placex ENABLE TRIGGER USER;
327 ```