Pull changes from upstream repository.
This commit is contained in:
Marek Skalický
parent
1d148b2116
commit
98e4e0c8b3
49 changed files with 4414 additions and 3 deletions
439
root/help.1
Normal file
439
root/help.1
Normal file
|
|
@ -0,0 +1,439 @@
|
|||
.TH MySQL 5.7 SQL Database Server container image
|
||||
.PP
|
||||
This container image includes MySQL 5.7 SQL database server for OpenShift and general usage.
|
||||
Users can choose between RHEL and CentOS based images.
|
||||
The RHEL image is available in the Red Hat Container Catalog
|
||||
\[la]https://access.redhat.com/containers/#/registry.access.redhat.com/rhscl/mysql-57-rhel7\[ra]
|
||||
as registry.access.redhat.com/rhscl/mysql\-57\-rhel7.
|
||||
The CentOS image is then available on Docker Hub
|
||||
\[la]https://hub.docker.com/r/centos/mysql-57-centos7/\[ra]
|
||||
as centos/mysql\-57\-centos7.
|
||||
|
||||
.SH Description
|
||||
.PP
|
||||
This container image provides a containerized packaging of the MySQL mysqld daemon
|
||||
and client application. The mysqld server daemon accepts connections from clients
|
||||
and provides access to content from MySQL databases on behalf of the clients.
|
||||
You can find more information on the MySQL project from the project Web site
|
||||
(
|
||||
\[la]https://www.mysql.com/\[ra]).
|
||||
|
||||
.SH Usage
|
||||
.PP
|
||||
For this, we will assume that you are using the MySQL 5.7 container image from the
|
||||
Red Hat Container Catalog called \fB\fCrhscl/mysql\-57\-rhel7\fR\&.
|
||||
If you want to set only the mandatory environment variables and not store
|
||||
the database in a host directory, execute the following command:
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
$ docker run \-d \-\-name mysql\_database \-e MYSQL\_USER=user \-e MYSQL\_PASSWORD=pass \-e MYSQL\_DATABASE=db \-p 3306:3306 rhscl/mysql\-57\-rhel7
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
This will create a container named \fB\fCmysql\_database\fR running MySQL with database
|
||||
\fB\fCdb\fR and user with credentials \fB\fCuser:pass\fR\&. Port 3306 will be exposed and mapped
|
||||
to the host. If you want your database to be persistent across container executions,
|
||||
also add a \fB\fC\-v /host/db/path:/var/lib/mysql/data\fR argument. This will be the MySQL
|
||||
data directory.
|
||||
|
||||
.PP
|
||||
If the database directory is not initialized, the entrypoint script will first
|
||||
run \fB\fCmysql\_install\_db\fR
|
||||
\[la]https://dev.mysql.com/doc/refman/en/mysql-install-db.html\[ra]
|
||||
and setup necessary database users and passwords. After the database is initialized,
|
||||
or if it was already present, \fB\fCmysqld\fR is executed and will run as PID 1. You can
|
||||
stop the detached container by running \fB\fCdocker stop mysql\_database\fR\&.
|
||||
|
||||
.SH Environment variables and volumes
|
||||
.PP
|
||||
The image recognizes the following environment variables that you can set during
|
||||
initialization by passing \fB\fC\-e VAR=VALUE\fR to the Docker run command.
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_USER\fR\fP
|
||||
.br
|
||||
User name for MySQL account to be created
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_PASSWORD\fR\fP
|
||||
.br
|
||||
Password for the user account
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_DATABASE\fR\fP
|
||||
.br
|
||||
Database name
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_ROOT\_PASSWORD\fR\fP
|
||||
.br
|
||||
Password for the root user (optional)
|
||||
|
||||
.PP
|
||||
The following environment variables influence the MySQL configuration file. They are all optional.
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_LOWER\_CASE\_TABLE\_NAMES (default: 0)\fR\fP
|
||||
.br
|
||||
Sets how the table names are stored and compared
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_MAX\_CONNECTIONS (default: 151)\fR\fP
|
||||
.br
|
||||
The maximum permitted number of simultaneous client connections
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_MAX\_ALLOWED\_PACKET (default: 200M)\fR\fP
|
||||
.br
|
||||
The maximum size of one packet or any generated/intermediate string
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_FT\_MIN\_WORD\_LEN (default: 4)\fR\fP
|
||||
.br
|
||||
The minimum length of the word to be included in a FULLTEXT index
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_FT\_MAX\_WORD\_LEN (default: 20)\fR\fP
|
||||
.br
|
||||
The maximum length of the word to be included in a FULLTEXT index
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_AIO (default: 1)\fR\fP
|
||||
.br
|
||||
Controls the \fB\fCinnodb\_use\_native\_aio\fR setting value in case the native AIO is broken. See
|
||||
\[la]http://help.directadmin.com/item.php?id=529\[ra]
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_TABLE\_OPEN\_CACHE (default: 400)\fR\fP
|
||||
.br
|
||||
The number of open tables for all threads
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_KEY\_BUFFER\_SIZE (default: 32M or 10% of available memory)\fR\fP
|
||||
.br
|
||||
The size of the buffer used for index blocks
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_SORT\_BUFFER\_SIZE (default: 256K)\fR\fP
|
||||
.br
|
||||
The size of the buffer used for sorting
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_READ\_BUFFER\_SIZE (default: 8M or 5% of available memory)\fR\fP
|
||||
.br
|
||||
The size of the buffer used for a sequential scan
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_INNODB\_BUFFER\_POOL\_SIZE (default: 32M or 50% of available memory)\fR\fP
|
||||
.br
|
||||
The size of the buffer pool where InnoDB caches table and index data
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_INNODB\_LOG\_FILE\_SIZE (default: 8M or 15% of available available)\fR\fP
|
||||
.br
|
||||
The size of each log file in a log group
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_INNODB\_LOG\_BUFFER\_SIZE (default: 8M or 15% of available memory)\fR\fP
|
||||
.br
|
||||
The size of the buffer that InnoDB uses to write to the log files on disk
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_DEFAULTS\_FILE (default: /etc/my.cnf)\fR\fP
|
||||
.br
|
||||
Point to an alternative configuration file
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_BINLOG\_FORMAT (default: statement)\fR\fP
|
||||
.br
|
||||
Set sets the binlog format, supported values are \fB\fCrow\fR and \fB\fCstatement\fR
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_LOG\_QUERIES\_ENABLED (default: 0)\fR\fP
|
||||
.br
|
||||
To enable query logging set this to \fB\fC1\fR
|
||||
|
||||
.PP
|
||||
You can also set the following mount points by passing the \fB\fC\-v /host:/container\fR flag to Docker.
|
||||
|
||||
.PP
|
||||
\fB\fB\fC/var/lib/mysql/data\fR\fP
|
||||
.br
|
||||
MySQL data directory
|
||||
|
||||
.PP
|
||||
\fBNotice: 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.\fP
|
||||
|
||||
.SH MySQL auto\-tuning
|
||||
.PP
|
||||
When the MySQL image is run with the \fB\fC\-\-memory\fR parameter set and you didn't
|
||||
specify value for some parameters, their values will be automatically
|
||||
calculated based on the available memory.
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_KEY\_BUFFER\_SIZE (default: 10%)\fR\fP
|
||||
.br
|
||||
\fB\fCkey\_buffer\_size\fR
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_READ\_BUFFER\_SIZE (default: 5%)\fR\fP
|
||||
.br
|
||||
\fB\fCread\_buffer\_size\fR
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_INNODB\_BUFFER\_POOL\_SIZE (default: 50%)\fR\fP
|
||||
.br
|
||||
\fB\fCinnodb\_buffer\_pool\_size\fR
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_INNODB\_LOG\_FILE\_SIZE (default: 15%)\fR\fP
|
||||
.br
|
||||
\fB\fCinnodb\_log\_file\_size\fR
|
||||
|
||||
.PP
|
||||
\fB\fB\fCMYSQL\_INNODB\_LOG\_BUFFER\_SIZE (default: 15%)\fR\fP
|
||||
.br
|
||||
\fB\fCinnodb\_log\_buffer\_size\fR
|
||||
|
||||
.SH MySQL root user
|
||||
.PP
|
||||
The root user has no password set by default, only allowing local connections.
|
||||
You can set it by setting the \fB\fCMYSQL\_ROOT\_PASSWORD\fR environment variable. This
|
||||
will allow you to login to the root account remotely. Local connections will
|
||||
still not require a password.
|
||||
|
||||
.PP
|
||||
To disable remote root access, simply unset \fB\fCMYSQL\_ROOT\_PASSWORD\fR and restart
|
||||
the container.
|
||||
|
||||
.SH Changing passwords
|
||||
.PP
|
||||
Since passwords are part of the image configuration, the only supported method
|
||||
to change passwords for the database user (\fB\fCMYSQL\_USER\fR) and root user is by
|
||||
changing the environment variables \fB\fCMYSQL\_PASSWORD\fR and \fB\fCMYSQL\_ROOT\_PASSWORD\fR,
|
||||
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 Default my.cnf file
|
||||
.PP
|
||||
With environment variables we are able to customize a lot of different parameters
|
||||
or configurations for the mysql bootstrap configurations. If you'd prefer to use
|
||||
your own configuration file, you can override the \fB\fCMYSQL\_DEFAULTS\_FILE\fR env
|
||||
variable with the full path of the file you wish to use. For example, the default
|
||||
location is \fB\fC/etc/my.cnf\fR but you can change it to \fB\fC/etc/mysql/my.cnf\fR by setting
|
||||
\fB\fCMYSQL\_DEFAULTS\_FILE=/etc/mysql/my.cnf\fR
|
||||
|
||||
.SH Extending image
|
||||
.PP
|
||||
This image can be extended using source\-to\-image
|
||||
\[la]https://github.com/openshift/source-to-image\[ra]\&.
|
||||
|
||||
.PP
|
||||
For example, to build a customized MariaDB database image \fB\fCmy\-mysql\-rhel7\fR
|
||||
with a configuration in \fB\fC\~/image\-configuration/\fR run:
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
$ s2i build \~/image\-configuration/ rhscl/mysql\-57\-rhel7 my\-mysql\-rhel7
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
The directory passed to \fB\fCs2i build\fR can contain these directories:
|
||||
|
||||
.PP
|
||||
\fB\fCmysql\-cfg/\fR
|
||||
When starting the container, files from this directory will be used as
|
||||
a configuration for the \fB\fCmysqld\fR daemon.
|
||||
\fB\fCenvsubst\fR command is run on this file to still allow customization of
|
||||
the image using environmental variables
|
||||
|
||||
.PP
|
||||
\fB\fCmysql\-pre\-init/\fR
|
||||
Shell scripts (\fB\fC*.sh\fR) available in this directory are sourced before
|
||||
\fB\fCmysqld\fR daemon is started.
|
||||
|
||||
.PP
|
||||
\fB\fCmysql\-init/\fR
|
||||
Shell scripts (\fB\fC*.sh\fR) available in this directory are sourced when
|
||||
\fB\fCmysqld\fR daemon is started locally. In this phase, use \fB\fC${mysql\_flags}\fR
|
||||
to connect to the locally running daemon, for example \fB\fCmysql $mysql\_flags < dump.sql\fR
|
||||
|
||||
.PP
|
||||
Variables that can be used in the scripts provided to s2i:
|
||||
|
||||
.PP
|
||||
\fB\fC$mysql\_flags\fR
|
||||
arguments for the \fB\fCmysql\fR tool that will connect to the locally running \fB\fCmysqld\fR during initialization
|
||||
|
||||
.PP
|
||||
\fB\fC$MYSQL\_RUNNING\_AS\_MASTER\fR
|
||||
variable defined when the container is run with \fB\fCrun\-mysqld\-master\fR command
|
||||
|
||||
.PP
|
||||
\fB\fC$MYSQL\_RUNNING\_AS\_SLAVE\fR
|
||||
variable defined when the container is run with \fB\fCrun\-mysqld\-slave\fR command
|
||||
|
||||
.PP
|
||||
\fB\fC$MYSQL\_DATADIR\_FIRST\_INIT\fR
|
||||
variable defined when the container was initialized from the empty data dir
|
||||
|
||||
.PP
|
||||
During \fB\fCs2i build\fR all provided files are copied into \fB\fC/opt/app\-root/src\fR
|
||||
directory into the resulting image. If some configuration files are present
|
||||
in the destination directory, files with the same name are overwritten.
|
||||
Also only one file with the same name can be used for customization and user
|
||||
provided files are preferred over default files in
|
||||
\fB\fC/usr/share/container\-scripts/mysql/\fR\- so it is possible to overwrite them.
|
||||
|
||||
.PP
|
||||
Same configuration directory structure can be used to customize the image
|
||||
every time the image is started using \fB\fCdocker run\fR\&. The directory has to be
|
||||
mounted into \fB\fC/opt/app\-root/src/\fR in the image
|
||||
(\fB\fC\-v ./image\-configuration/:/opt/app\-root/src/\fR).
|
||||
This overwrites customization built into the image.
|
||||
|
||||
.SH Securing the connection with SSL
|
||||
.PP
|
||||
In order to secure the connection with SSL, use the extending feature described
|
||||
above. In particular, put the SSL certificates into a separate directory:
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
sslapp/mysql\-certs/server\-cert\-selfsigned.pem
|
||||
sslapp/mysql\-certs/server\-key.pem
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
And then put a separate configuration file into mysql\-cfg:
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
$> cat sslapp/mysql\-cfg/ssl.cnf
|
||||
[mysqld]
|
||||
ssl\-key=${APP\_DATA}/mysql\-certs/server\-key.pem
|
||||
ssl\-cert=${APP\_DATA}/mysql\-certs/server\-cert\-selfsigned.pem
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Such a directory \fB\fCsslapp\fR can then be mounted into the container with \-v,
|
||||
or a new container image can be built using s2i.
|
||||
|
||||
.SH Upgrading and data directory version checking
|
||||
.PP
|
||||
MySQL and MariaDB use versions that consist of three numbers X.Y.Z (e.g. 5.6.23).
|
||||
For version changes in Z part, the server's binary data format stays compatible and thus no
|
||||
special upgrade procedure is needed. For upgrades from X.Y to X.Y+1, consider doing manual
|
||||
steps as described at
|
||||
|
||||
\[la]https://dev.mysql.com/doc/refman/5.7/en/upgrading-from-previous-series.html\[ra]\&.
|
||||
|
||||
.PP
|
||||
Skipping versions like from X.Y to X.Y+2 or downgrading to lower version is not supported;
|
||||
the only exception is ugrading from MariaDB 5.5 to MariaDB 10.0.
|
||||
|
||||
.PP
|
||||
\fBImportant\fP: Upgrading to a new version is always risky and users are expected to make a full
|
||||
back\-up of all data before.
|
||||
|
||||
.PP
|
||||
A safer solution to upgrade is to dump all data using \fB\fCmysqldump\fR or \fB\fCmysqldbexport\fR and then
|
||||
load the data using \fB\fCmysql\fR or \fB\fCmysqldbimport\fR into an empty (freshly initialized) database.
|
||||
|
||||
.PP
|
||||
Another way of proceeding with the upgrade is starting the new version of the \fB\fCmysqld\fR daemon
|
||||
and run \fB\fCmysql\_upgrade\fR right after the start. This so called in\-place upgrade is generally
|
||||
faster for large data directory, but only possible if upgrading from the very previous version,
|
||||
so skipping versions is not supported.
|
||||
|
||||
.PP
|
||||
This container detects whether the data needs to be upgraded using \fB\fCmysql\_upgrade\fR and
|
||||
we can control it by setting \fB\fCMYSQL\_DATADIR\_ACTION\fR variable, which can have one or more of the following values:
|
||||
.IP \(bu 2
|
||||
\fB\fCupgrade\-warn\fR \-\- If the data version can be determined and the data come from a different version
|
||||
of the daemon, a warning is printed but the container starts. This is the default value.
|
||||
Since historically the version file \fB\fCmysql\_upgrade\_info\fR was not created, when using this option,
|
||||
the version file is created if not exist, but no \fB\fCmysql\_upgrade\fR will be called.
|
||||
However, this automatic creation will be removed after few months, since the version should be
|
||||
created on most deployments at that point.
|
||||
.IP \(bu 2
|
||||
\fB\fCupgrade\-auto\fR \-\- \fB\fCmysql\_upgrade\fR is run at the beginning of the container start, when the local
|
||||
daemon is running, but only if the data version can be determined and the data come
|
||||
with the very previous version. A warning is printed if the data come from even older
|
||||
or newer version. This value effectively enables automatic upgrades,
|
||||
but it is always risky and users should still back\-up all the data before starting the newer container.
|
||||
Set this option only if you have very good back\-ups at any moment and you are fine to fail\-over
|
||||
from the back\-up.
|
||||
.IP \(bu 2
|
||||
\fB\fCupgrade\-force\fR \-\- \fB\fCmysql\_upgrade \-\-force\fR is run at the beginning of the container start, when the local
|
||||
daemon is running, no matter what version of the daemon the data come from.
|
||||
This is also the way to create the missing version file \fB\fCmysql\_upgrade\_info\fR if not present
|
||||
in the root of the data directory; this file holds information about the version of the data.
|
||||
|
||||
.PP
|
||||
There are also some other actions that you may want to run at the beginning of the container start,
|
||||
when the local daemon is running, no matter what version of the data is detected:
|
||||
.IP \(bu 2
|
||||
\fB\fCoptimize\fR \-\- runs \fB\fCmysqlcheck \-\-optimize\fR\&. It optimizes all the tables.
|
||||
.IP \(bu 2
|
||||
\fB\fCanalyze\fR \-\- runs \fB\fCmysqlcheck \-\-analyze\fR\&. It analyzes all the tables.
|
||||
.IP \(bu 2
|
||||
\fB\fCdisable\fR \-\- nothing is done regarding data directory version.
|
||||
|
||||
.PP
|
||||
Multiple values are separated by comma and run in\-order, e.g. \fB\fCMYSQL\_DATADIR\_ACTION="optimize,analyze"\fR\&.
|
||||
|
||||
.SH Changing the replication binlog\_format
|
||||
.PP
|
||||
Some applications may wish to use \fB\fCrow\fR binlog\_formats (for example, those built
|
||||
with change\-data\-capture in mind). The default replication/binlog format is
|
||||
\fB\fCstatement\fR but to change it you can set the \fB\fCMYSQL\_BINLOG\_FORMAT\fR environment
|
||||
variable. For example \fB\fCMYSQL\_BINLOG\_FORMAT=row\fR\&. Now when you run the database
|
||||
with \fB\fCmaster\fR replication turned on (ie, set the Docker/container \fB\fCcmd\fR to be
|
||||
\fB\fCrun\-mysqld\-master\fR) the binlog will emit the actual data for the rows that change
|
||||
as opposed to the statements (ie, DML like insert...) that caused the change.
|
||||
|
||||
.SH Troubleshooting
|
||||
.PP
|
||||
The mysqld deamon in the container logs to the standard output, so the log is available in the container log. The log can be examined by running:
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
docker logs <container>
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.SH See also
|
||||
.PP
|
||||
Dockerfile and other sources for this container image are available on
|
||||
|
||||
\[la]https://github.com/sclorg/mysql-container\[ra]\&.
|
||||
In that repository, Dockerfile for CentOS is called Dockerfile, Dockerfile
|
||||
for RHEL is called Dockerfile.rhel7.
|
||||
340
root/usr/share/container-scripts/mysql/README.md
Normal file
340
root/usr/share/container-scripts/mysql/README.md
Normal file
|
|
@ -0,0 +1,340 @@
|
|||
MySQL 5.7 SQL Database Server container image
|
||||
==========================================
|
||||
|
||||
This container image includes MySQL 5.7 SQL database server for OpenShift and general usage.
|
||||
Users can choose between RHEL and CentOS based images.
|
||||
The RHEL image is available in the [Red Hat Container Catalog](https://access.redhat.com/containers/#/registry.access.redhat.com/rhscl/mysql-57-rhel7)
|
||||
as registry.access.redhat.com/rhscl/mysql-57-rhel7.
|
||||
The CentOS image is then available on [Docker Hub](https://hub.docker.com/r/centos/mysql-57-centos7/)
|
||||
as centos/mysql-57-centos7.
|
||||
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
This container image provides a containerized packaging of the MySQL mysqld daemon
|
||||
and client application. The mysqld server daemon accepts connections from clients
|
||||
and provides access to content from MySQL databases on behalf of the clients.
|
||||
You can find more information on the MySQL project from the project Web site
|
||||
(https://www.mysql.com/).
|
||||
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
For this, we will assume that you are using the MySQL 5.7 container image from the
|
||||
Red Hat Container Catalog called `rhscl/mysql-57-rhel7`.
|
||||
If you want to set only the mandatory environment variables and not store
|
||||
the database in a host directory, execute the following command:
|
||||
|
||||
```
|
||||
$ docker run -d --name mysql_database -e MYSQL_USER=user -e MYSQL_PASSWORD=pass -e MYSQL_DATABASE=db -p 3306:3306 rhscl/mysql-57-rhel7
|
||||
```
|
||||
|
||||
This will create a container named `mysql_database` running MySQL with database
|
||||
`db` and user with credentials `user:pass`. Port 3306 will be exposed and mapped
|
||||
to the host. If you want your database to be persistent across container executions,
|
||||
also add a `-v /host/db/path:/var/lib/mysql/data` argument. This will be the MySQL
|
||||
data directory.
|
||||
|
||||
If the database directory is not initialized, the entrypoint script will first
|
||||
run [`mysql_install_db`](https://dev.mysql.com/doc/refman/en/mysql-install-db.html)
|
||||
and setup necessary database users and passwords. After the database is initialized,
|
||||
or if it was already present, `mysqld` is executed and will run as PID 1. You can
|
||||
stop the detached container by running `docker stop mysql_database`.
|
||||
|
||||
|
||||
Environment variables and volumes
|
||||
---------------------------------
|
||||
|
||||
The image recognizes the following environment variables that you can set during
|
||||
initialization by passing `-e VAR=VALUE` to the Docker run command.
|
||||
|
||||
**`MYSQL_USER`**
|
||||
User name for MySQL account to be created
|
||||
|
||||
**`MYSQL_PASSWORD`**
|
||||
Password for the user account
|
||||
|
||||
**`MYSQL_DATABASE`**
|
||||
Database name
|
||||
|
||||
**`MYSQL_ROOT_PASSWORD`**
|
||||
Password for the root user (optional)
|
||||
|
||||
|
||||
The following environment variables influence the MySQL configuration file. They are all optional.
|
||||
|
||||
**`MYSQL_LOWER_CASE_TABLE_NAMES (default: 0)`**
|
||||
Sets how the table names are stored and compared
|
||||
|
||||
**`MYSQL_MAX_CONNECTIONS (default: 151)`**
|
||||
The maximum permitted number of simultaneous client connections
|
||||
|
||||
**`MYSQL_MAX_ALLOWED_PACKET (default: 200M)`**
|
||||
The maximum size of one packet or any generated/intermediate string
|
||||
|
||||
**`MYSQL_FT_MIN_WORD_LEN (default: 4)`**
|
||||
The minimum length of the word to be included in a FULLTEXT index
|
||||
|
||||
**`MYSQL_FT_MAX_WORD_LEN (default: 20)`**
|
||||
The maximum length of the word to be included in a FULLTEXT index
|
||||
|
||||
**`MYSQL_AIO (default: 1)`**
|
||||
Controls the `innodb_use_native_aio` setting value in case the native AIO is broken. See http://help.directadmin.com/item.php?id=529
|
||||
|
||||
**`MYSQL_TABLE_OPEN_CACHE (default: 400)`**
|
||||
The number of open tables for all threads
|
||||
|
||||
**`MYSQL_KEY_BUFFER_SIZE (default: 32M or 10% of available memory)`**
|
||||
The size of the buffer used for index blocks
|
||||
|
||||
**`MYSQL_SORT_BUFFER_SIZE (default: 256K)`**
|
||||
The size of the buffer used for sorting
|
||||
|
||||
**`MYSQL_READ_BUFFER_SIZE (default: 8M or 5% of available memory)`**
|
||||
The size of the buffer used for a sequential scan
|
||||
|
||||
**`MYSQL_INNODB_BUFFER_POOL_SIZE (default: 32M or 50% of available memory)`**
|
||||
The size of the buffer pool where InnoDB caches table and index data
|
||||
|
||||
**`MYSQL_INNODB_LOG_FILE_SIZE (default: 8M or 15% of available available)`**
|
||||
The size of each log file in a log group
|
||||
|
||||
**`MYSQL_INNODB_LOG_BUFFER_SIZE (default: 8M or 15% of available memory)`**
|
||||
The size of the buffer that InnoDB uses to write to the log files on disk
|
||||
|
||||
**`MYSQL_DEFAULTS_FILE (default: /etc/my.cnf)`**
|
||||
Point to an alternative configuration file
|
||||
|
||||
**`MYSQL_BINLOG_FORMAT (default: statement)`**
|
||||
Set sets the binlog format, supported values are `row` and `statement`
|
||||
|
||||
**`MYSQL_LOG_QUERIES_ENABLED (default: 0)`**
|
||||
To enable query logging set this to `1`
|
||||
|
||||
|
||||
You can also set the following mount points by passing the `-v /host:/container` flag to Docker.
|
||||
|
||||
**`/var/lib/mysql/data`**
|
||||
MySQL data directory
|
||||
|
||||
|
||||
**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.**
|
||||
|
||||
|
||||
MySQL auto-tuning
|
||||
-----------------
|
||||
|
||||
When the MySQL image is run with the `--memory` parameter set and you didn't
|
||||
specify value for some parameters, their values will be automatically
|
||||
calculated based on the available memory.
|
||||
|
||||
**`MYSQL_KEY_BUFFER_SIZE (default: 10%)`**
|
||||
`key_buffer_size`
|
||||
|
||||
**`MYSQL_READ_BUFFER_SIZE (default: 5%)`**
|
||||
`read_buffer_size`
|
||||
|
||||
**`MYSQL_INNODB_BUFFER_POOL_SIZE (default: 50%)`**
|
||||
`innodb_buffer_pool_size`
|
||||
|
||||
**`MYSQL_INNODB_LOG_FILE_SIZE (default: 15%)`**
|
||||
`innodb_log_file_size`
|
||||
|
||||
**`MYSQL_INNODB_LOG_BUFFER_SIZE (default: 15%)`**
|
||||
`innodb_log_buffer_size`
|
||||
|
||||
|
||||
|
||||
MySQL root user
|
||||
---------------------------------
|
||||
The root user has no password set by default, only allowing local connections.
|
||||
You can set it by setting the `MYSQL_ROOT_PASSWORD` environment variable. This
|
||||
will allow you to login to the root account remotely. Local connections will
|
||||
still not require a password.
|
||||
|
||||
To disable remote root access, simply unset `MYSQL_ROOT_PASSWORD` and restart
|
||||
the container.
|
||||
|
||||
|
||||
Changing passwords
|
||||
------------------
|
||||
|
||||
Since passwords are part of the image configuration, the only supported method
|
||||
to change passwords for the database user (`MYSQL_USER`) and root user is by
|
||||
changing the environment variables `MYSQL_PASSWORD` and `MYSQL_ROOT_PASSWORD`,
|
||||
respectively.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Default my.cnf file
|
||||
-------------------
|
||||
With environment variables we are able to customize a lot of different parameters
|
||||
or configurations for the mysql bootstrap configurations. If you'd prefer to use
|
||||
your own configuration file, you can override the `MYSQL_DEFAULTS_FILE` env
|
||||
variable with the full path of the file you wish to use. For example, the default
|
||||
location is `/etc/my.cnf` but you can change it to `/etc/mysql/my.cnf` by setting
|
||||
`MYSQL_DEFAULTS_FILE=/etc/mysql/my.cnf`
|
||||
|
||||
|
||||
Extending image
|
||||
---------------
|
||||
This image can be extended using [source-to-image](https://github.com/openshift/source-to-image).
|
||||
|
||||
For example, to build a customized MariaDB database image `my-mysql-rhel7`
|
||||
with a configuration in `~/image-configuration/` run:
|
||||
|
||||
```
|
||||
$ s2i build ~/image-configuration/ rhscl/mysql-57-rhel7 my-mysql-rhel7
|
||||
```
|
||||
|
||||
The directory passed to `s2i build` can contain these directories:
|
||||
|
||||
`mysql-cfg/`
|
||||
When starting the container, files from this directory will be used as
|
||||
a configuration for the `mysqld` daemon.
|
||||
`envsubst` command is run on this file to still allow customization of
|
||||
the image using environmental variables
|
||||
|
||||
`mysql-pre-init/`
|
||||
Shell scripts (`*.sh`) available in this directory are sourced before
|
||||
`mysqld` daemon is started.
|
||||
|
||||
`mysql-init/`
|
||||
Shell scripts (`*.sh`) available in this directory are sourced when
|
||||
`mysqld` daemon is started locally. In this phase, use `${mysql_flags}`
|
||||
to connect to the locally running daemon, for example `mysql $mysql_flags < dump.sql`
|
||||
|
||||
Variables that can be used in the scripts provided to s2i:
|
||||
|
||||
`$mysql_flags`
|
||||
arguments for the `mysql` tool that will connect to the locally running `mysqld` during initialization
|
||||
|
||||
`$MYSQL_RUNNING_AS_MASTER`
|
||||
variable defined when the container is run with `run-mysqld-master` command
|
||||
|
||||
`$MYSQL_RUNNING_AS_SLAVE`
|
||||
variable defined when the container is run with `run-mysqld-slave` command
|
||||
|
||||
`$MYSQL_DATADIR_FIRST_INIT`
|
||||
variable defined when the container was initialized from the empty data dir
|
||||
|
||||
During `s2i build` all provided files are copied into `/opt/app-root/src`
|
||||
directory into the resulting image. If some configuration files are present
|
||||
in the destination directory, files with the same name are overwritten.
|
||||
Also only one file with the same name can be used for customization and user
|
||||
provided files are preferred over default files in
|
||||
`/usr/share/container-scripts/mysql/`- so it is possible to overwrite them.
|
||||
|
||||
Same configuration directory structure can be used to customize the image
|
||||
every time the image is started using `docker run`. The directory has to be
|
||||
mounted into `/opt/app-root/src/` in the image
|
||||
(`-v ./image-configuration/:/opt/app-root/src/`).
|
||||
This overwrites customization built into the image.
|
||||
|
||||
|
||||
Securing the connection with SSL
|
||||
--------------------------------
|
||||
In order to secure the connection with SSL, use the extending feature described
|
||||
above. In particular, put the SSL certificates into a separate directory:
|
||||
|
||||
sslapp/mysql-certs/server-cert-selfsigned.pem
|
||||
sslapp/mysql-certs/server-key.pem
|
||||
|
||||
And then put a separate configuration file into mysql-cfg:
|
||||
|
||||
$> cat sslapp/mysql-cfg/ssl.cnf
|
||||
[mysqld]
|
||||
ssl-key=${APP_DATA}/mysql-certs/server-key.pem
|
||||
ssl-cert=${APP_DATA}/mysql-certs/server-cert-selfsigned.pem
|
||||
|
||||
Such a directory `sslapp` can then be mounted into the container with -v,
|
||||
or a new container image can be built using s2i.
|
||||
|
||||
|
||||
Upgrading and data directory version checking
|
||||
---------------------------------------------
|
||||
|
||||
MySQL and MariaDB use versions that consist of three numbers X.Y.Z (e.g. 5.6.23).
|
||||
For version changes in Z part, the server's binary data format stays compatible and thus no
|
||||
special upgrade procedure is needed. For upgrades from X.Y to X.Y+1, consider doing manual
|
||||
steps as described at
|
||||
https://dev.mysql.com/doc/refman/5.7/en/upgrading-from-previous-series.html.
|
||||
|
||||
Skipping versions like from X.Y to X.Y+2 or downgrading to lower version is not supported;
|
||||
the only exception is ugrading from MariaDB 5.5 to MariaDB 10.0.
|
||||
|
||||
**Important**: Upgrading to a new version is always risky and users are expected to make a full
|
||||
back-up of all data before.
|
||||
|
||||
A safer solution to upgrade is to dump all data using `mysqldump` or `mysqldbexport` and then
|
||||
load the data using `mysql` or `mysqldbimport` into an empty (freshly initialized) database.
|
||||
|
||||
Another way of proceeding with the upgrade is starting the new version of the `mysqld` daemon
|
||||
and run `mysql_upgrade` right after the start. This so called in-place upgrade is generally
|
||||
faster for large data directory, but only possible if upgrading from the very previous version,
|
||||
so skipping versions is not supported.
|
||||
|
||||
This container detects whether the data needs to be upgraded using `mysql_upgrade` and
|
||||
we can control it by setting `MYSQL_DATADIR_ACTION` variable, which can have one or more of the following values:
|
||||
|
||||
* `upgrade-warn` -- If the data version can be determined and the data come from a different version
|
||||
of the daemon, a warning is printed but the container starts. This is the default value.
|
||||
Since historically the version file `mysql_upgrade_info` was not created, when using this option,
|
||||
the version file is created if not exist, but no `mysql_upgrade` will be called.
|
||||
However, this automatic creation will be removed after few months, since the version should be
|
||||
created on most deployments at that point.
|
||||
* `upgrade-auto` -- `mysql_upgrade` is run at the beginning of the container start, when the local
|
||||
daemon is running, but only if the data version can be determined and the data come
|
||||
with the very previous version. A warning is printed if the data come from even older
|
||||
or newer version. This value effectively enables automatic upgrades,
|
||||
but it is always risky and users should still back-up all the data before starting the newer container.
|
||||
Set this option only if you have very good back-ups at any moment and you are fine to fail-over
|
||||
from the back-up.
|
||||
* `upgrade-force` -- `mysql_upgrade --force` is run at the beginning of the container start, when the local
|
||||
daemon is running, no matter what version of the daemon the data come from.
|
||||
This is also the way to create the missing version file `mysql_upgrade_info` if not present
|
||||
in the root of the data directory; this file holds information about the version of the data.
|
||||
|
||||
There are also some other actions that you may want to run at the beginning of the container start,
|
||||
when the local daemon is running, no matter what version of the data is detected:
|
||||
|
||||
* `optimize` -- runs `mysqlcheck --optimize`. It optimizes all the tables.
|
||||
* `analyze` -- runs `mysqlcheck --analyze`. It analyzes all the tables.
|
||||
* `disable` -- nothing is done regarding data directory version.
|
||||
|
||||
Multiple values are separated by comma and run in-order, e.g. `MYSQL_DATADIR_ACTION="optimize,analyze"`.
|
||||
|
||||
|
||||
Changing the replication binlog_format
|
||||
--------------------------------------
|
||||
Some applications may wish to use `row` binlog_formats (for example, those built
|
||||
with change-data-capture in mind). The default replication/binlog format is
|
||||
`statement` but to change it you can set the `MYSQL_BINLOG_FORMAT` environment
|
||||
variable. For example `MYSQL_BINLOG_FORMAT=row`. Now when you run the database
|
||||
with `master` replication turned on (ie, set the Docker/container `cmd` to be
|
||||
`run-mysqld-master`) the binlog will emit the actual data for the rows that change
|
||||
as opposed to the statements (ie, DML like insert...) that caused the change.
|
||||
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
The mysqld deamon in the container logs to the standard output, so the log is available in the container log. The log can be examined by running:
|
||||
|
||||
docker logs <container>
|
||||
|
||||
|
||||
See also
|
||||
--------
|
||||
Dockerfile and other sources for this container image are available on
|
||||
https://github.com/sclorg/mysql-container.
|
||||
In that repository, Dockerfile for CentOS is called Dockerfile, Dockerfile
|
||||
for RHEL is called Dockerfile.rhel7.
|
||||
Loading…
Add table
Add a link
Reference in a new issue