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