Skip to content

Commit b61d638

Browse files
author
Jeff McCormick
committed
update docs
1 parent 9116505 commit b61d638

File tree

3 files changed

+141
-2
lines changed

3 files changed

+141
-2
lines changed

‎docs/build.asciidoc‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,11 +82,12 @@ make pgo
8282
which pgo
8383
....
8484

85-
==== Compile and build the operator Docker image:
85+
==== Compile and build the operator Docker images:
8686
....
8787
cd $COROOT
8888
make operatorimage
89-
docker images | grep operator
89+
make lsimage
90+
docker images | grep crunchydata
9091
....
9192

9293

docs/misc.asciidoc renamed to docs/design.asciidoc

File renamed without changes.

‎docs/user-guide.asciidoc‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
== postgres Operator User Guide
2+
v1.0.0, {docdate}
3+
4+
This document is meant for users and demonstrates
5+
the basic interface of the *pgo* command line interface.
6+
7+
== Create Database
8+
9+
To create a database, use the following:
10+
....
11+
pgo create database mydatabase
12+
....
13+
14+
You can then view that database as:
15+
....
16+
pgo show database mydatabase
17+
....
18+
19+
The output will give you the current status of the database pod
20+
and the IP address of the database service. If you have *postgresql*
21+
installed on your test system you can connect to the
22+
database using the service IP address:
23+
....
24+
psql -h 10.105.121.12 -U postgres postgres
25+
....
26+
27+
You can view *all* databases using the special keyword *all*:
28+
....
29+
pgo show database all
30+
....
31+
32+
== Backup Database
33+
34+
You can start a backup job for a database or cluster as follows:
35+
....
36+
pgo create backup mydatabase
37+
pgo create backup mycluster
38+
....
39+
40+
You can view the backup:
41+
....
42+
pgo show backup mydatabase
43+
pgo show backup mycluster
44+
....
45+
46+
The output of the backup will list the backup snapshots
47+
found in the backup PVC, for example:
48+
....
49+
backup job pods for database mydatabase...
50+
└── backup-mydatabase-63fw1
51+
└── mydatabase
52+
53+
database pod mydatabase is found
54+
55+
├── mydatabase-backups/2017-03-27-13-54-33
56+
├── mydatabase-backups/2017-03-27-13-56-49
57+
└── *mydatabase-backups/2017-03-27-14-02-38*
58+
....
59+
60+
This output is important in that it can let you copy/paste
61+
a backup snapshot path and use it for restoring a database or
62+
essentially cloning a database with an existing backup archive.
63+
64+
For example, to restore a database from a backup archive:
65+
....
66+
pgo create database restoredb --backup-path=mydatabase-backups/2017-03-27-13-56-49 --backup-pvc=crunchy-pvc
67+
....
68+
69+
This will create a new database called *restoredb* based on the
70+
backup found in *mydatabase-backups/2017-03-27-13-56-49*.
71+
72+
73+
== Create Cluster
74+
75+
A cluster in this case consists of a *master* and a *replica* database
76+
that use PostgreSQL streaming replication to form a PostgreSQL
77+
cluster.
78+
79+
Use the *pgo* command to create a cluster:
80+
....
81+
pgo create cluster mycluster
82+
....
83+
84+
View the cluster:
85+
....
86+
pgo show cluster mycluster
87+
....
88+
89+
You will see in the output a variety of Kubernetes objects
90+
where created including:
91+
92+
* a Deployment holding the master PostgreSQL database
93+
* a Deployment holding the replica PostgreSQL database
94+
* a service for the master database
95+
* a service for the replica databases
96+
97+
Since Postgres is a single-master database by design, the master
98+
Deployment is set to a replica count of 1, it can not scale beyond 1.
99+
100+
The replica Deployment is set to an initial value of 2, you will
101+
see there are 2 replica databases running. Those replica databases
102+
are in read-only mode, but you can scale up the number of replicas
103+
beyond 2 if you need higher read scaling.
104+
105+
There are 2 connections available to the postgres cluster, one is
106+
to the master database which allows read-write SQL processing, and
107+
the other is to the set of read-only replica databases. The replica
108+
service performs round-robin load balancing to the 2 replica databases.
109+
110+
You can connect to the master database and verify that it is replicating
111+
to the 2 replica databases as follows:
112+
....
113+
psql -h 10.107.180.159 -U postgres postgres -c 'table pg_stat_replication'
114+
....
115+
116+
You can view *all* clusters using the special keyword *all*:
117+
....
118+
pgo show cluster all
119+
....
120+
121+
122+
== Delete Database and Cluster
123+
124+
You can delete a database as follows:
125+
....
126+
pgo delete database mydatabase
127+
....
128+
129+
Likewise, you can delete a cluster as follows:
130+
....
131+
pgo delete cluster mycluster
132+
....
133+
134+
*Note*, when you delete a database or cluster, the operator
135+
will delete the unique PVC that pertains to the database if one
136+
exists. This is the case when you specify a PVC to be created
137+
for a database instead of using a shared PVC configuration.
138+

0 commit comments

Comments
 (0)