]> git.openstreetmap.org Git - nominatim.git/blob - docs/admin/Migration.md
Merge branch 'fix-getcol-zero' of https://github.com/eyusupov/Nominatim into eyusupov...
[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.3.0 -> 3.4.0
10
11 ### Reorganisation of location_area_country table
12
13 The table `location_area_country` has been optimized. You need to switch to the
14 new format when you run updates. While updates are disabled, run the following
15 SQL commands:
16
17 ```sql
18 CREATE TABLE location_area_country_new AS
19   SELECT place_id, country_code, geometry FROM location_area_country;
20 DROP TABLE location_area_country;
21 ALTER TABLE location_area_country_new RENAME TO location_area_country;
22 CREATE INDEX idx_location_area_country_geometry ON location_area_country USING GIST (geometry);
23 CREATE INDEX idx_location_area_country_place_id ON location_area_country USING BTREE (place_id);
24 ```
25
26 ## 3.2.0 -> 3.3.0
27
28 ### New database connection string (DSN) format
29
30 Previously database connection setting (`CONST_Database_DSN` in `settings/*.php`) had the format
31
32    * (simple) `pgsql://@/nominatim`
33    * (complex) `pgsql://johndoe:secret@machine1.domain.com:1234/db1`
34
35 The new format is
36
37    * (simple) `pgsql:dbname=nominatim`
38    * (complex) `pgsql:dbname=db1;host=machine1.domain.com;port=1234;user=johndoe;password=secret`
39
40 ### Natural Earth country boundaries no longer needed as fallback
41
42 ```
43 DROP TABLE country_naturalearthdata;
44 ```
45
46 Finally, update all SQL functions:
47
48 ```sh
49 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
50 ```
51
52 ### Configurable Address Levels
53
54 The new configurable address levels require a new table. Create it with the
55 following command:
56
57 ```sh
58 ./utils/update.php --update-address-levels
59 ```
60
61 ## 3.1.0 -> 3.2.0
62
63 ### New reverse algorithm
64
65 The reverse algorithm has changed and requires new indexes. Run the following
66 SQL statements to create the indexes:
67
68 ```
69 CREATE INDEX idx_placex_geometry_reverse_lookupPoint
70   ON placex USING gist (geometry)
71   WHERE (name is not null or housenumber is not null or rank_address between 26 and 27)
72     AND class not in ('railway','tunnel','bridge','man_made')
73     AND rank_address >= 26 AND indexed_status = 0 AND linked_place_id is null;
74 CREATE INDEX idx_placex_geometry_reverse_lookupPolygon
75   ON placex USING gist (geometry)
76   WHERE St_GeometryType(geometry) in ('ST_Polygon', 'ST_MultiPolygon')
77     AND rank_address between 4 and 25 AND type != 'postcode'
78     AND name is not null AND indexed_status = 0 AND linked_place_id is null;
79 CREATE INDEX idx_placex_geometry_reverse_placeNode
80   ON placex USING gist (geometry)
81   WHERE osm_type = 'N' AND rank_search between 5 and 25
82     AND class = 'place' AND type != 'postcode'
83     AND name is not null AND indexed_status = 0 AND linked_place_id is null;
84 ```
85
86 You also need to grant the website user access to the `country_osm_grid` table:
87
88 ```
89 GRANT SELECT ON table country_osm_grid to "www-user";
90 ```
91
92 Replace the `www-user` with the user name of your website server if necessary.
93
94 You can now drop the unused indexes:
95
96 ```
97 DROP INDEX idx_placex_reverse_geometry;
98 ```
99
100 Finally, update all SQL functions:
101
102 ```sh
103 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
104 ```
105
106 ## 3.0.0 -> 3.1.0
107
108 ### Postcode Table
109
110 A new separate table for artificially computed postcode centroids was introduced.
111 Migration to the new format is possible but **not recommended**.
112
113 Create postcode table and indexes, running the following SQL statements:
114
115 ```sql
116 CREATE TABLE location_postcode
117   (place_id BIGINT, parent_place_id BIGINT, rank_search SMALLINT,
118    rank_address SMALLINT, indexed_status SMALLINT, indexed_date TIMESTAMP,
119    country_code varchar(2), postcode TEXT,
120    geometry GEOMETRY(Geometry, 4326));
121 CREATE INDEX idx_postcode_geometry ON location_postcode USING GIST (geometry);
122 CREATE UNIQUE INDEX idx_postcode_id ON location_postcode USING BTREE (place_id);
123 CREATE INDEX idx_postcode_postcode ON location_postcode USING BTREE (postcode);
124 GRANT SELECT ON location_postcode TO "www-data";
125 drop type if exists nearfeaturecentr cascade;
126 create type nearfeaturecentr as (
127   place_id BIGINT,
128   keywords int[],
129   rank_address smallint,
130   rank_search smallint,
131   distance float,
132   isguess boolean,
133   postcode TEXT,
134   centroid GEOMETRY
135 );
136 ```
137
138 Add postcode column to `location_area` tables with SQL statement:
139
140 ```sql
141 ALTER TABLE location_area ADD COLUMN postcode TEXT;
142 ```
143
144 Then reimport the functions:
145
146 ```sh
147 ./utils/setup.php --create-functions --enable-diff-updates --create-partition-functions
148 ```
149
150 Create appropriate triggers with SQL:
151
152 ```sql
153 CREATE TRIGGER location_postcode_before_update BEFORE UPDATE ON location_postcode
154     FOR EACH ROW EXECUTE PROCEDURE postcode_update();
155 ```
156
157 Finally populate the postcode table (will take a while):
158
159 ```sh
160 ./utils/setup.php --calculate-postcodes --index --index-noanalyse
161 ```
162
163 This will create a working database. You may also delete the old artificial
164 postcodes now. Note that this may be expensive and is not absolutely necessary.
165 The following SQL statement will remove them:
166
167 ```sql
168 DELETE FROM place_addressline a USING placex p
169  WHERE a.address_place_id = p.place_id and p.osm_type = 'P';
170 ALTER TABLE placex DISABLE TRIGGER USER;
171 DELETE FROM placex WHERE osm_type = 'P';
172 ALTER TABLE placex ENABLE TRIGGER USER;
173 ```