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