Skip to content

Commit 6f1855d

Browse files
gbartolinigbartolini
authored
docs: update PostGIS instructions (cloudnative-pg#7146)
Leverage the new feature for declarative management of extensions in the example to deploy PostGIS. Closes cloudnative-pg#7144 Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
1 parent 10a87e1 commit 6f1855d

File tree

2 files changed

+65
-51
lines changed

2 files changed

+65
-51
lines changed

‎docs/src/postgis.md‎

Lines changed: 45 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ do this in two ways:
4646

4747
## Create a new PostgreSQL cluster with PostGIS
4848

49-
Let's suppose you want to create a new PostgreSQL 14 cluster with PostGIS 3.2.
49+
Let's suppose you want to create a new PostgreSQL 17 cluster with PostGIS 3.2.
5050

5151
The first step is to ensure you use the right PostGIS container image for the
5252
operand, and properly set the `.spec.imageName` option in the `Cluster`
@@ -59,7 +59,7 @@ provides some guidance on how the creation of a PostGIS cluster can be done.
5959
Please consider that, although convention over configuration applies in
6060
CloudNativePG, you should spend time configuring and tuning your system for
6161
production. Also the `imageName` in the example below deliberately points
62-
to the latest available image for PostgreSQL 14 - you should use a specific
62+
to the latest available image for PostgreSQL 17 - you should use a specific
6363
image name or, preferably, the SHA256 digest for true immutability.
6464

6565
```yaml
@@ -68,71 +68,75 @@ kind: Cluster
6868
metadata:
6969
name: postgis-example
7070
spec:
71-
instances: 3
72-
imageName: ghcr.io/cloudnative-pg/postgis:14
73-
bootstrap:
74-
initdb:
75-
postInitTemplateSQL:
76-
- CREATE EXTENSION postgis;
77-
- CREATE EXTENSION postgis_topology;
78-
- CREATE EXTENSION fuzzystrmatch;
79-
- CREATE EXTENSION postgis_tiger_geocoder;
80-
71+
instances: 1
72+
imageName: ghcr.io/cloudnative-pg/postgis:17
8173
storage:
8274
size: 1Gi
75+
postgresql:
76+
parameters:
77+
log_statement: ddl
78+
---
79+
apiVersion: postgresql.cnpg.io/v1
80+
kind: Database
81+
metadata:
82+
name: postgis-example-app
83+
spec:
84+
name: app
85+
owner: app
86+
cluster:
87+
name: postgis-example
88+
extensions:
89+
- name: postgis
90+
- name: postgis_topology
91+
- name: fuzzystrmatch
92+
- name: postgis_tiger_geocoder
8393
```
8494
85-
The example relies on the `postInitTemplateSQL` option which executes a list of
86-
queries against the `template1` database, before the actual creation of the
87-
application database (called `app`). This means that, once you have applied the
88-
manifest and the cluster is up, you will have the above extensions installed in
89-
both the template database and the application database, ready for use.
95+
The example leverages the `Database` resource's declarative extension
96+
management to add the specified extensions to the `app` database.
9097

9198
!!! Info
92-
Take some time and look at the available options in `.spec.bootstrap.initdb`
93-
from the [API reference](cloudnative-pg.v1.md#postgresql-cnpg-io-v1-BootstrapInitDB), such as
94-
`postInitApplicationSQL`.
99+
For more details, see the
100+
["Managing Extensions in a Database" section](declarative_database_management.md#managing-extensions-in-a-database).
95101

96102
You can easily verify the available version of PostGIS that is in the
97103
container, by connecting to the `app` database (you might obtain different
98104
values from the ones in this document):
99105

100106
```console
101-
$ kubectl exec -ti postgis-example-1 -- psql app
102-
Defaulted container "postgres" out of: postgres, bootstrap-controller (init)
103-
psql (17.4 (Debian 17.4-1.pgdg110+1))
107+
$ kubectl cnpg psql postgis-example -- app
108+
psql (17.4 (Debian 17.4-1.pgdg110+2))
104109
Type "help" for help.
105110
106111
app=# SELECT * FROM pg_available_extensions WHERE name ~ '^postgis' ORDER BY 1;
107112
name | default_version | installed_version | comment
108113
--------------------------+-----------------+-------------------+------------------------------------------------------------
109-
postgis | 3.2.2 | 3.2.2 | PostGIS geometry and geography spatial types and functions
110-
postgis-3 | 3.2.2 | | PostGIS geometry and geography spatial types and functions
111-
postgis_raster | 3.2.2 | | PostGIS raster types and functions
112-
postgis_raster-3 | 3.2.2 | | PostGIS raster types and functions
113-
postgis_sfcgal | 3.2.2 | | PostGIS SFCGAL functions
114-
postgis_sfcgal-3 | 3.2.2 | | PostGIS SFCGAL functions
115-
postgis_tiger_geocoder | 3.2.2 | 3.2.2 | PostGIS tiger geocoder and reverse geocoder
116-
postgis_tiger_geocoder-3 | 3.2.2 | | PostGIS tiger geocoder and reverse geocoder
117-
postgis_topology | 3.2.2 | 3.2.2 | PostGIS topology spatial types and functions
118-
postgis_topology-3 | 3.2.2 | | PostGIS topology spatial types and functions
114+
postgis | 3.5.2 | 3.5.2 | PostGIS geometry and geography spatial types and functions
115+
postgis-3 | 3.5.2 | | PostGIS geometry and geography spatial types and functions
116+
postgis_raster | 3.5.2 | | PostGIS raster types and functions
117+
postgis_raster-3 | 3.5.2 | | PostGIS raster types and functions
118+
postgis_sfcgal | 3.5.2 | | PostGIS SFCGAL functions
119+
postgis_sfcgal-3 | 3.5.2 | | PostGIS SFCGAL functions
120+
postgis_tiger_geocoder | 3.5.2 | 3.5.2 | PostGIS tiger geocoder and reverse geocoder
121+
postgis_tiger_geocoder-3 | 3.5.2 | | PostGIS tiger geocoder and reverse geocoder
122+
postgis_topology | 3.5.2 | 3.5.2 | PostGIS topology spatial types and functions
123+
postgis_topology-3 | 3.5.2 | | PostGIS topology spatial types and functions
119124
(10 rows)
120125
```
121126

122-
The next step is to verify that the extensions listed in the
123-
`postInitTemplateSQL` section have been correctly installed in the `app`
124-
database.
127+
The next step is to verify that the extensions listed in the `Database`
128+
resource have been correctly installed in the `app` database.
125129

126130
```console
127131
app=# \dx
128132
List of installed extensions
129133
Name | Version | Schema | Description
130134
------------------------+---------+------------+------------------------------------------------------------
131-
fuzzystrmatch | 1.1 | public | determine similarities and distance between strings
135+
fuzzystrmatch | 1.2 | public | determine similarities and distance between strings
132136
plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language
133-
postgis | 3.2.2 | public | PostGIS geometry and geography spatial types and functions
134-
postgis_tiger_geocoder | 3.2.2 | tiger | PostGIS tiger geocoder and reverse geocoder
135-
postgis_topology | 3.2.2 | topology | PostGIS topology spatial types and functions
137+
postgis | 3.5.2 | public | PostGIS geometry and geography spatial types and functions
138+
postgis_tiger_geocoder | 3.5.2 | tiger | PostGIS tiger geocoder and reverse geocoder
139+
postgis_topology | 3.5.2 | topology | PostGIS topology spatial types and functions
136140
(5 rows)
137141
```
138142

@@ -142,6 +146,6 @@ Finally:
142146
app=# SELECT postgis_full_version();
143147
postgis_full_version
144148
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
145-
POSTGIS="3.2.2 628da50" [EXTENSION] PGSQL="140" GEOS="3.9.0-CAPI-1.16.2" PROJ="7.2.1" LIBXML="2.9.10" LIBJSON="0.15" LIBPROTOBUF="1.3.3" WAGYU="0.5.0 (Internal)" TOPOLOGY
149+
POSTGIS="3.5.2 dea6d0a" [EXTENSION] PGSQL="170" GEOS="3.9.0-CAPI-1.16.2" PROJ="7.2.1 NETWORK_ENABLED=OFF URL_ENDPOINT=https://cdn.proj.org USER_WRITABLE_DIRECTORY=/tmp/proj DATABASE_PATH=/usr/share/proj/proj.db" (compiled against PROJ 7.2.1) LIBXML="2.9.10" LIBJSON="0.15" LIBPROTOBUF="1.3.3" WAGYU="0.5.0 (Internal)" TOPOLOGY
146150
(1 row)
147151
```

‎docs/src/samples/postgis-example.yaml‎

Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,25 @@ kind: Cluster
33
metadata:
44
name: postgis-example
55
spec:
6-
instances: 3
7-
imageName: ghcr.io/cloudnative-pg/postgis:14
8-
bootstrap:
9-
initdb:
10-
postInitTemplateSQL:
11-
- CREATE EXTENSION postgis;
12-
- CREATE EXTENSION postgis_topology;
13-
- CREATE EXTENSION fuzzystrmatch;
14-
- CREATE EXTENSION postgis_tiger_geocoder;
15-
6+
instances: 1
7+
imageName: ghcr.io/cloudnative-pg/postgis:17
168
storage:
179
size: 1Gi
10+
postgresql:
11+
parameters:
12+
log_statement: ddl
13+
---
14+
apiVersion: postgresql.cnpg.io/v1
15+
kind: Database
16+
metadata:
17+
name: postgis-example-app
18+
spec:
19+
name: app
20+
owner: app
21+
cluster:
22+
name: postgis-example
23+
extensions:
24+
- name: postgis
25+
- name: postgis_topology
26+
- name: fuzzystrmatch
27+
- name: postgis_tiger_geocoder

0 commit comments

Comments
 (0)