<commit_before>= postgres Operator User Guide
v1.5.2, {docdate}

This document is meant for users and demonstrates
the basic interface of the *pgo* command line interface.

== Create Cluster

To create a database, use the following:
....
pgo create cluster mycluster
....

A more complex example is to create a *series* of clusters such
as:
....
pgo create cluster xraydb --series=3 --labels=project=xray --policies=xrayapp,rlspolicy
....

In the example above, we provision 3 clusters that have a number appended
into their resulting cluster name, apply a user defined label to each
cluster, and also apply user defined policies to each cluster after
they are created.

You can then view that database as:
....
pgo show cluster mydatabase
....

The output will give you the current status of the database pod
and the IP address of the database service.  If you have *postgresql*
installed on your test system you can connect to the
database using the service IP address:
....
psql -h 10.105.121.12 -U postgres postgres
....

You can view *all* databases using the special keyword *all*:
....
pgo show cluster all
....

You can filter the results based on the Postgres Version:
....
pgo show cluster all --version=9.6.2
....

== Backup Cluster

You can start a backup job for a cluster as follows:
....
pgo backup mycluster
....

You can view the backup:
....
pgo show backup mycluster
....

You can view the backup along with a PVC listing:
....
pgo show backup mycluster --show-pvc=true
....

The output of the backup will list the backup snapshots
found in the backup PVC, for example:
....
backup job pods for cluster mycluster...
└── backup-mycluster-63fw1
└── mydatabase

database pod mycluster is found

├── mycluster-backups/2017-03-27-13-54-33
├── mycluster-backups/2017-03-27-13-56-49
└── mycluster-backups/2017-03-27-14-02-38
....

This output is important in that it can let you copy/paste
a backup snapshot path and use it for restoring a database or
essentially cloning a database with an existing backup archive.

For example, to restore a database from a backup archive:
....
pgo create cluster restoredb --backup-path=mycluster-backups/2017-03-27-13-56-49 --backup-pvc=crunchy-pvc --secret-from=mycluster
....

This will create a new database called *restoredb* based on the
backup found in *mycluster-backups/2017-03-27-13-56-49* and the
secrets of the *mycluster* cluster.

Selectors can be used to perform backups as well, for example:
....
pgo backup  --selector=project=xray
....

In this example, any cluster that matches the selector will cause
a backup job to be created.


== Cluster Removal

You can remove a cluster by running:
....
pgo delete cluster restoredb
....

Note, that this command will not remove the PVC associated with
this cluster.  If you want to remove the cluster's old data files,
you will need to remove it manually.

Selectors also apply to the delete command as follows:
....
pgo delete cluster  --selector=project=xray
....

This command will cause any cluster matching the selector
to be removed. 


== Cluster Replication

When you create a Cluster, you will see in the output a variety of Kubernetes objects were created including:

 * a Deployment holding the master PostgreSQL database
 * a Deployment holding the replica PostgreSQL database
 * a service for the master database
 * a service for the replica databases

Since Postgres is a single-master database by design, the master
Deployment is set to a replica count of 1, it can not scale beyond 1.

The replica Deployment is set to an initial value of 0, you will
see there are 0 replica databases running.  Those replica databases
are in read-only mode, but you can scale up the number of replicas
beyond 0 if you need higher read scaling.  To set the number of 
replicas issue the following command:
....
pgo scale mycluster --replica-count=1
....

There are 2 service connections available to the postgres cluster, one is
to the master database which allows read-write SQL processing, and
the other is to the set of read-only replica databases.  The replica
service performs round-robin load balancing to the replica databases.

You can connect to the master database and verify that it is replicating
to the replica databases as follows:
....
psql -h 10.107.180.159 -U postgres postgres -c 'table pg_stat_replication'
....

You can view *all* clusters using the special keyword *all*:
....
pgo show cluster all
....

You can filter the results by Postgres version:
....
pgo show cluster all --version=9.6.2
....


== Minor Cluster Upgrade

You can perform a minor Postgres version upgrade
of either a database or cluster as follows:
....
pgo create upgrade mycluster
....

When you run this command, it will cause the operator
to delete the existing containers of the database or cluster
and recreate them using the currently defined Postgres
container image specified in your pgo configuration file.

The database data files remain untouched, only the container
is updated, this will upgrade your Postgres server version only.

== Major Cluster Upgrade

You can perform a major Postgres version upgrade
of either a database or cluster as follows:
....
pgo upgrade mycluster --upgrade-type=major
....

When you run this command, it will cause the operator
to delete the existing containers of the database or cluster
and recreate them using the currently defined Postgres
container image specified in your pgo configuration file.

The database data files are converted to the new major Postgres<commit_msg>fix type of<commit_after>= postgres Operator User Guide
v1.5.2, {docdate}

This document is meant for users and demonstrates
the basic interface of the *pgo* command line interface.

== Create Cluster

To create a database, use the following:
....
pgo create cluster mycluster
....

A more complex example is to create a *series* of clusters such
as:
....
pgo create cluster xraydb --series=3 --labels=project=xray --policies=xrayapp,rlspolicy
....

In the example above, we provision 3 clusters that have a number appended
into their resulting cluster name, apply a user defined label to each
cluster, and also apply user defined policies to each cluster after
they are created.

You can then view that database as:
....
pgo show cluster mydatabase
....

The output will give you the current status of the database pod
and the IP address of the database service.  If you have *postgresql*
installed on your test system you can connect to the
database using the service IP address:
....
psql -h 10.105.121.12 -U postgres postgres
....

You can view *all* databases using the special keyword *all*:
....
pgo show cluster all
....

You can filter the results based on the Postgres Version:
....
pgo show cluster all --version=9.6.2
....

== Backup Cluster

You can start a backup job for a cluster as follows:
....
pgo backup mycluster
....

You can view the backup:
....
pgo show backup mycluster
....

You can view the backup along with a PVC listing:
....
pgo show backup mycluster --show-pvc=true
....

The output of the backup will list the backup snapshots
found in the backup PVC, for example:
....
backup job pods for cluster mycluster...
└── backup-mycluster-63fw1
└── mydatabase

database pod mycluster is found

├── mycluster-backups/2017-03-27-13-54-33
├── mycluster-backups/2017-03-27-13-56-49
└── mycluster-backups/2017-03-27-14-02-38
....

This output is important in that it can let you copy/paste
a backup snapshot path and use it for restoring a database or
essentially cloning a database with an existing backup archive.

For example, to restore a database from a backup archive:
....
pgo create cluster restoredb --backup-path=mycluster-backups/2017-03-27-13-56-49 --backup-pvc=crunchy-pvc --secret-from=mycluster
....

This will create a new database called *restoredb* based on the
backup found in *mycluster-backups/2017-03-27-13-56-49* and the
secrets of the *mycluster* cluster.

Selectors can be used to perform backups as well, for example:
....
pgo backup  --selector=project=xray
....

In this example, any cluster that matches the selector will cause
a backup job to be created.


== Cluster Removal

You can remove a cluster by running:
....
pgo delete cluster restoredb
....

Note, that this command will not remove the PVC associated with
this cluster.  If you want to remove the cluster's old data files,
you will need to remove it manually.

Selectors also apply to the delete command as follows:
....
pgo delete cluster  --selector=project=xray
....

This command will cause any cluster matching the selector
to be removed. 


== Cluster Replication

When you create a Cluster, you will see in the output a variety of Kubernetes objects were created including:

 * a Deployment holding the master PostgreSQL database
 * a Deployment holding the replica PostgreSQL database
 * a service for the master database
 * a service for the replica databases

Since Postgres is a single-master database by design, the master
Deployment is set to a replica count of 1, it can not scale beyond 1.

The replica Deployment is set to an initial value of 0, you will
see there are 0 replica databases running.  Those replica databases
are in read-only mode, but you can scale up the number of replicas
beyond 0 if you need higher read scaling.  To set the number of 
replicas issue the following command:
....
pgo scale mycluster --replica-count=1
....

There are 2 service connections available to the postgres cluster, one is
to the master database which allows read-write SQL processing, and
the other is to the set of read-only replica databases.  The replica
service performs round-robin load balancing to the replica databases.

You can connect to the master database and verify that it is replicating
to the replica databases as follows:
....
psql -h 10.107.180.159 -U postgres postgres -c 'table pg_stat_replication'
....

You can view *all* clusters using the special keyword *all*:
....
pgo show cluster all
....

You can filter the results by Postgres version:
....
pgo show cluster all --version=9.6.2
....


== Minor Cluster Upgrade

You can perform a minor Postgres version upgrade
of either a database or cluster as follows:
....
pgo upgrade mycluster
....

When you run this command, it will cause the operator
to delete the existing containers of the database or cluster
and recreate them using the currently defined Postgres
container image specified in your pgo configuration file.

The database data files remain untouched, only the container
is updated, this will upgrade your Postgres server version only.

== Major Cluster Upgrade

You can perform a major Postgres version upgrade
of either a database or cluster as follows:
....
pgo upgrade mycluster --upgrade-type=major
....

When you run this command, it will cause the operator
to delete the existing containers of the database or cluster
and recreate them using the currently defined Postgres
container image specified in your pgo configuration file.

The database data files are converted to the new major Postgres
{'fraction_non_alphanumeric': 0.07124082298558869, 'fraction_numerical': 0.020302728179099068, 'mean_word_length': 3.643939393939394, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '204750', 'n_tokens_mistral': 3118, 'n_tokens_neox': 2907, 'n_words': 1612}