190 lines
5.3 KiB
Groff
190 lines
5.3 KiB
Groff
.\"t
|
|
.\" WARNING: Do not edit this file manually, it is generated from README.md automatically.
|
|
.\"
|
|
.\"t
|
|
.\" Automatically generated by Pandoc 1.16.0.2
|
|
.\"
|
|
.TH "POSTGRESQL\-95\-RHEL7" "1" "February 22, 2017" "Container Image Pages" ""
|
|
.hy
|
|
.SH PostgreSQL Docker image
|
|
.PP
|
|
This repository contains Dockerfiles for PostgreSQL images for general
|
|
usage and OpenShift.
|
|
Users can choose between RHEL and CentOS based images.
|
|
.SS Environment variables and volumes
|
|
.PP
|
|
The image recognizes the following environment variables that you can
|
|
set during initialization by passing \f[C]\-e\ VAR=VALUE\f[] to the
|
|
Docker run command.
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(26.7n) lw(43.3n).
|
|
T{
|
|
Variable name
|
|
T}@T{
|
|
Description
|
|
T}
|
|
_
|
|
T{
|
|
\f[C]POSTGRESQL_USER\f[]
|
|
T}@T{
|
|
User name for PostgreSQL account to be created
|
|
T}
|
|
T{
|
|
\f[C]POSTGRESQL_PASSWORD\f[]
|
|
T}@T{
|
|
Password for the user account
|
|
T}
|
|
T{
|
|
\f[C]POSTGRESQL_DATABASE\f[]
|
|
T}@T{
|
|
Database name
|
|
T}
|
|
T{
|
|
\f[C]POSTGRESQL_ADMIN_PASSWORD\f[]
|
|
T}@T{
|
|
Password for the \f[C]postgres\f[] admin account (optional)
|
|
T}
|
|
.TE
|
|
.PP
|
|
The following environment variables influence the PostgreSQL
|
|
configuration file.
|
|
They are all optional.
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(15.7n) lw(37.6n) lw(16.7n).
|
|
T{
|
|
Variable name
|
|
T}@T{
|
|
Description
|
|
T}@T{
|
|
Default
|
|
T}
|
|
_
|
|
T{
|
|
\f[C]POSTGRESQL_MAX_CONNECTIONS\f[]
|
|
T}@T{
|
|
The maximum number of client connections allowed
|
|
T}@T{
|
|
100
|
|
T}
|
|
T{
|
|
\f[C]POSTGRESQL_MAX_PREPARED_TRANSACTIONS\f[]
|
|
T}@T{
|
|
Sets the maximum number of transactions that can be in the "prepared"
|
|
state.
|
|
If you are using prepared transactions, you will probably want this to
|
|
be at least as large as max_connections
|
|
T}@T{
|
|
0
|
|
T}
|
|
T{
|
|
\f[C]POSTGRESQL_SHARED_BUFFERS\f[]
|
|
T}@T{
|
|
Sets how much memory is dedicated to PostgreSQL to use for caching data
|
|
T}@T{
|
|
32M
|
|
T}
|
|
T{
|
|
\f[C]POSTGRESQL_EFFECTIVE_CACHE_SIZE\f[]
|
|
T}@T{
|
|
Set to an estimate of how much memory is available for disk caching by
|
|
the operating system and within the database itself
|
|
T}@T{
|
|
128M
|
|
T}
|
|
.TE
|
|
.PP
|
|
You can also set the following mount points by passing the
|
|
\f[C]\-v\ /host:/container\f[] flag to Docker.
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l.
|
|
T{
|
|
Volume mount point
|
|
T}@T{
|
|
Description
|
|
T}
|
|
_
|
|
T{
|
|
\f[C]/var/lib/pgsql/data\f[]
|
|
T}@T{
|
|
PostgreSQL database cluster directory
|
|
T}
|
|
.TE
|
|
.PP
|
|
\f[B]Notice: When mouting a directory from the host into the container,
|
|
ensure that the mounted directory has the appropriate permissions and
|
|
that the owner and group of the directory matches the user UID or name
|
|
which is running inside the container.\f[]
|
|
.SS Usage
|
|
.PP
|
|
For this, we will assume that you are using the
|
|
\f[C]openshift/postgresql\-92\-centos7\f[] image.
|
|
If you want to set only the mandatory environment variables and not
|
|
store the database in a host directory, execute the following command:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ docker\ run\ \-d\ \-\-name\ postgresql_database\ \-e\ POSTGRESQL_USER=user\ \-e\ POSTGRESQL_PASSWORD=pass\ \-e\ POSTGRESQL_DATABASE=db\ \-p\ 5432:5432\ openshift/postgresql\-92\-centos7
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
This will create a container named \f[C]postgresql_database\f[] running
|
|
PostgreSQL with database \f[C]db\f[] and user with credentials
|
|
\f[C]user:pass\f[].
|
|
Port 5432 will be exposed and mapped to the host.
|
|
If you want your database to be persistent across container executions,
|
|
also add a \f[C]\-v\ /host/db/path:/var/lib/pgsql/data\f[] argument.
|
|
This will be the PostgreSQL database cluster directory.
|
|
.PP
|
|
If the database cluster directory is not initialized, the entrypoint
|
|
script will first run
|
|
\f[C]initdb\f[] (http://www.postgresql.org/docs/9.2/static/app-initdb.html)
|
|
and setup necessary database users and passwords.
|
|
After the database is initialized, or if it was already present,
|
|
\f[C]postgres\f[] (http://www.postgresql.org/docs/9.2/static/app-postgres.html)
|
|
is executed and will run as PID 1.
|
|
You can stop the detached container by running
|
|
\f[C]docker\ stop\ postgresql_database\f[].
|
|
.SS PostgreSQL auto\-tuning
|
|
.PP
|
|
When the PostgreSQL image is run with the \f[C]\-\-memory\f[] parameter
|
|
set and if there are no values provided for
|
|
\f[C]POSTGRESQL_SHARED_BUFFERS\f[] and
|
|
\f[C]POSTGRESQL_EFFECTIVE_CACHE_SIZE\f[] those values are automatically
|
|
calculated based on the value provided in the \f[C]\-\-memory\f[]
|
|
parameter.
|
|
.PP
|
|
The values are calculated based on the
|
|
upstream (https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server)
|
|
formulas.
|
|
For the \f[C]shared_buffers\f[] we use 1/4 of given memory and for the
|
|
\f[C]effective_cache_size\f[] we set the value to 1/2 of the given
|
|
memory.
|
|
.SS PostgreSQL admin account
|
|
.PP
|
|
The admin account \f[C]postgres\f[] has no password set by default, only
|
|
allowing local connections.
|
|
You can set it by setting the \f[C]POSTGRESQL_ADMIN_PASSWORD\f[]
|
|
environment variable when initializing your container.
|
|
This will allow you to login to the \f[C]postgres\f[] account remotely.
|
|
Local connections will still not require a password.
|
|
.SS Changing passwords
|
|
.PP
|
|
Since passwords are part of the image configuration, the only supported
|
|
method to change passwords for the database user
|
|
(\f[C]POSTGRESQL_USER\f[]) and \f[C]postgres\f[] admin user is by
|
|
changing the environment variables \f[C]POSTGRESQL_PASSWORD\f[] and
|
|
\f[C]POSTGRESQL_ADMIN_PASSWORD\f[], respectively.
|
|
.PP
|
|
Changing database passwords through SQL statements or any way other than
|
|
through the environment variables aforementioned will cause a mismatch
|
|
between the values stored in the variables and the actual passwords.
|
|
Whenever a database container starts it will reset the passwords to the
|
|
values stored in the environment variables.
|
|
.SH AUTHORS
|
|
Red Hat.
|