<commit_before>= Examples & Use Cases - Crunchy Containers for PostgreSQL
Crunchy Data Solutions, Inc.
:toc: left
v1.4.1, {docdate}
:title-logo-image: image:crunchy_logo.png["CrunchyData Logo",align="center",scaledwidth="80%"]

== Container Examples

=== basic - Running a single database container


==== Docker

Create the container with this command:
....
cd $CCPROOT/examples/docker/basic
./run.sh
....

This script will do the following:

 * create a data volume to persist PostgreSQL data files to
 * start up a container named *basic*
 * initialize the database using the passed in environment variables, building a user, database, schema, and table based on the environment variable values.
 * maps the PostgreSQL port of 5432 in the container to your local host port of 12000.

To start the instance, run the following commands:
....
docker start basic
....

The container creates a default database called *userdb*, a default
user called *testuser* with a default password of *password*, you can
use this to connect from your local host as follows:
....
psql -h localhost -p 12000 -U testuser -W userdb
....

To shut down the instance, run the following commands:
....
docker stop basic
....


==== Kubernetes

This example starts a single postgres container and service, the most simple
of examples.

Running the example:
....
examples/kube/basic/run.sh
kubectl get pod basic
kubectl get service basic
kubectl logs basic
....

After the database starts up you can connect to it as follows:
....
psql -h basic -U postgres postgres
....


==== OpenShift

This OpenShift template will create a single master PostgreSQL instance.


Running the example:

....
cd $CCPROOT/examples/openshift/basic
./run.sh
....

You can see what passwords were generated by running this command:

....
oc describe pod basic | grep PG
....

You can run the following command to test the database, entering
the value of PG_PASSWORD from above for the password when prompted:

....
psql -h basic.openshift.svc.cluster.local -U testuser userdb
....

=== master-replica - Creating a master and replica database cluster


==== Docker

Run the container with this command:
....
cd $CCPROOT/examples/docker/master-replica
./run.sh
....

This script will do the following:

 * create a docker volume using the local driver for the master
 * create a docker volume using the local driver for the replica
 * start up a container named master binding to port 12000
 * start up a container named replica binding to port 12002
 * initialize the database using the passed in environment variables, building a user, database, schema, and table based on the environment variable values.
 * maps the PostgreSQL port of 5432 in the container to your local host port of 12000.

To start the instance, run the following commands:
....
docker start master replica
....

The container creates a default database called *userdb*, a default
user called *testuser* with a default password of *password*, you can
use this to connect from your local host as follows:
....
psql -h localhost -p 12007 -U testuser -W userdb
psql -h localhost -p 12008 -U testuser -W userdb
....

To shut down the instance, run the following commands:
....
docker stop master replica
....


==== Kubernetes

This example starts a master pod, master service, replica pod, and replica
service.  The replica is a replica of the master.  This example uses
emptyDir volumes for persistence.  This example does not allow
you to scale up the replicas.

Running the example:
....<commit_msg>add docker-compose example under master-replica<commit_after>= Examples & Use Cases - Crunchy Containers for PostgreSQL
Crunchy Data Solutions, Inc.
:toc: left
v1.4.1, {docdate}
:title-logo-image: image:crunchy_logo.png["CrunchyData Logo",align="center",scaledwidth="80%"]

== Container Examples

=== basic - Running a single database container


==== Docker

Create the container with this command:
....
cd $CCPROOT/examples/docker/basic
./run.sh
....

This script will do the following:

 * create a data volume to persist PostgreSQL data files to
 * start up a container named *basic*
 * initialize the database using the passed in environment variables, building a user, database, schema, and table based on the environment variable values.
 * maps the PostgreSQL port of 5432 in the container to your local host port of 12000.

To start the instance, run the following commands:
....
docker start basic
....

The container creates a default database called *userdb*, a default
user called *testuser* with a default password of *password*, you can
use this to connect from your local host as follows:
....
psql -h localhost -p 12000 -U testuser -W userdb
....

To shut down the instance, run the following commands:
....
docker stop basic
....


==== Kubernetes

This example starts a single postgres container and service, the most simple
of examples.

Running the example:
....
examples/kube/basic/run.sh
kubectl get pod basic
kubectl get service basic
kubectl logs basic
....

After the database starts up you can connect to it as follows:
....
psql -h basic -U postgres postgres
....


==== OpenShift

This OpenShift template will create a single master PostgreSQL instance.


Running the example:

....
cd $CCPROOT/examples/openshift/basic
./run.sh
....

You can see what passwords were generated by running this command:

....
oc describe pod basic | grep PG
....

You can run the following command to test the database, entering
the value of PG_PASSWORD from above for the password when prompted:

....
psql -h basic.openshift.svc.cluster.local -U testuser userdb
....

=== master-replica - Creating a master and replica database cluster


==== Docker

Run the container with this command:
....
cd $CCPROOT/examples/docker/master-replica
./run.sh
....

This script will do the following:

 * create a docker volume using the local driver for the master
 * create a docker volume using the local driver for the replica
 * start up a container named master binding to port 12000
 * start up a container named replica binding to port 12002
 * initialize the database using the passed in environment variables, building a user, database, schema, and table based on the environment variable values.
 * maps the PostgreSQL port of 5432 in the container to your local host port of 12000.

To start the instance, run the following commands:
....
docker start master replica
....

The container creates a default database called *userdb*, a default
user called *testuser* with a default password of *password*, you can
use this to connect from your local host as follows:
....
psql -h localhost -p 12007 -U testuser -W userdb
psql -h localhost -p 12008 -U testuser -W userdb
....

To shut down the instance, run the following commands:
....
docker stop master replica
....

==== Docker-Compose

This is a *docker-compose* example of deploying master
and read replicas using the crunchy-postgres image from DockerHub.

To install docker-compose, please follow the instructions located
in the link:https://docs.docker.com/compose/install/[official Docker documentation].

You can also access docker-compose by setting up the following Vagrant/VirtualBox
virtualized environment containing CentOS 7, Docker, and docker-compose:
https://github.com/jasonodonnell/docker-vm

To deploy this example, run the following commands:

....
cd $CCPROOT/examples/compose/master-replica
docker-compose up
....

Optionally, to deploy more than one replica, run the following:

....
docker-compose up --scale db-replica=3
....

To psql into the created database containers, first identify the ports exposed
on the containers:

....
docker ps
....

Next, using psql, connect to the service:

....
psql -d userdb -h 0.0.0.0 -p <CONTAINER_PORT> -U testuser
....

*Note:* See *PG_PASSWORD* in *docker-compose.yml* for the user password.

To tear down the example, run the following:

....
docker-compose stop
docker-compose rm
....

==== Kubernetes

This example starts a master pod, master service, replica pod, and replica
service.  The replica is a replica of the master.  This example uses
emptyDir volumes for persistence.  This example does not allow
you to scale up the replicas.

Running the example:
....
{'fraction_non_alphanumeric': 0.08580817916260955, 'fraction_numerical': 0.012414800389483933, 'mean_word_length': 3.642372881355932, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 4, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 1, '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': '5066636', 'n_tokens_mistral': 2372, 'n_tokens_neox': 2186, 'n_words': 1117}