MariaDB: Difference between revisions

From Alpine Linux
(added links to the production focused documentation)
m (Use apk template.)
 
(18 intermediate revisions by 9 users not shown)
Line 1: Line 1:
[https://mariadb.org/ MariaDB] is a community-developed fork of the MySQL relational database management system intended to remain free under the GNU GPL. It is notable for being led by the original developers of MySQL, who forked it due to concerns over its acquisition by Oracle.
[https://mariadb.org/ MariaDB] is a community-developed fork of the MySQL relational database management system intended to remain free under the GNU GPL. It is notable for being led by the original developers of MySQL, who forked it due to concerns over its acquisition by Oracle.


'''This is the general documentation for normal and common general usage, for professional usage please use [[Production DataBases : mysql]] that is the same as MariaDB but with several modifications focused on production and security!'''
'''This is the general documentation for normal and common general usage, for professional usage please use [[MySQL]] that is the same as MariaDB but with several modifications focused on production and security!'''


== Instalation ==
== Installation ==


Alpine Linux has dummy counterparts packages for those that are not close to that change from ''mysql'' to ''mariadb'' naming packages.
The Alpine Linux repositories no longer include the actual MySQL binaries, installing the <code>mysql-*</code> packages will instead install MariaDB.  


Take in consideration that the user <code>mysql</code> was created during instalation of packages, in the initialization section two users will be created in database init: <code>root</code> and <code>mysql</code>, and in that point only if are in their respective system accounts, will be able to connect to the database service.
Installing <code>mariadb</code> will create the user <code>mysql</code>. When the database is initialized, two users will be added to the database: <code>root</code> and <code>mysql</code>. By default these users will only be accessible if you are logged in as the corresponding system user.


<pre><nowiki>
{{Cmd|apk add {{pkg|mysql|arch=}} {{pkg|mysql-client|arch=}}}}
apk add mysql mysql-client
</nowiki></pre>


That will install the most used ones.. <code>mariadb-cient</code> and <code>mariadb-server</code>, rest of packages are brief described here for more information, here are listed in orden of relevance for production server
Installing the above packages will add the main components of MariaDB to the system: <code>mariadb-cient</code> and <code>mariadb-server</code>. Other available packages are described in the table below, and are listed in order of relevance for a production server.


{| class="wikitable"
{| class="wikitable"
Line 19: Line 17:
! MySQL name package !! Since Alpine: !! Brief usage !! Related package
! MySQL name package !! Since Alpine: !! Brief usage !! Related package
|-
|-
| mysql || v2 || it's a dummy package to easy install of mariadb || mariadb
| {{Pkg|mysql}} || v2 || a transitional package that installs mariadb || mariadb
|-
|-
| mysql-client || v2 || it's a dummy package to easy install of commands tools || mariadb-client
| {{Pkg|mysql-client}} || v2 || a transitional package that installs the mariadb client tools || mariadb-client
|-
|-
| mariadb || v2 || server equivalent to mysql-server || mariadb-common
| {{Pkg|mariadb}} || v2 || server equivalent to mysql-server || mariadb-common
|-
|-
| mariadb-client || v2 || connection command line and tools || mariadb-common
| {{Pkg|mariadb-client}} || v2 || connection command line and tools || mariadb-common
|-
|-
| mariadb-doc || v3.0 || manpages are there! || man man-pages
| {{Pkg|mariadb-doc}} || v3.0 || manpages for mariadb || man man-pages
|-
|-
| mariadb-connector-odbc || edge || coding or making OS level connections, to any DB without libs install || .
| {{Pkg|mariadb-connector-odbc}} || edge || coding or making OS level connections, to any DB without libs install || .
|-
|-
| mariadb-connector-c || v3.8 || coding connection on C sources || mariadb-connector-c-dev
| {{Pkg|mariadb-connector-c}} || v3.8 || coding connection on C sources || mariadb-connector-c-dev
|-
|-
| mariadb-backup || v3.8 || to external backup devices, not widely used, in past was inside mariadb package || .
| {{Pkg|mariadb-backup}} || v3.8 || tool for physical online backups, no longer widely used || .
|-
|-
| mariadb-server-utils || v3.8 || server commands not widely used, in past was inside mariadb package || .
| {{Pkg|mariadb-server-utils}} || v3.8 || server commands not widely used, in past was inside MariaDB package || .
|-
|-
| mariadb-dev || v3.1 || Need for compilations depends on source code || .
| {{Pkg|mariadb-dev}} || v3.1 || development files for MariaDB || .
|-
|-
| mariadb-test || v3.3 || testing suite from MariaDB tools || .
| {{Pkg|mariadb-test}} || v3.3 || testing suite from MariaDB tools || .
|-
|-
| mariadb-mytop || v3.9 || data performance monitoring || .
| {{Pkg|mariadb-mytop}} || v3.9 || data performance monitoring || .
|-
|-
| mariadb-plugin-rocksdb || v3.9 || plain key-value event relational for data || .
| {{Pkg|mariadb-plugin-rocksdb}} || v3.9 || plain key-value event relational for data || .
|-
|-
| mariadb-static || v3.8 || static libs for static non depends linking in builds || .
| {{Pkg|mariadb-static}} || v3.8 || static libs for static non depends linking in builds || .
|-
|-
| mariadb-embedded || v3.9 || the libmysqld identical interface as the C client || mariadb-embedded-dev
| {{Pkg|mariadb-embedded}} || v3.9 || the libmysqld identical interface as the C client || mariadb-embedded-dev
|-
|-
| mariadb-embedded-dev || v3.9 ||  use the normal mysql.h and link with libmysqld instead of libmysqlclient || mariadb-dev
| {{Pkg|mariadb-embedded-dev}} || v3.9 ||  use the normal mysql.h and link with libmysqld instead of libmysqlclient || mariadb-dev
|-
|-
| mariadb-openrc || v3.8 || separate scripts, in past was embebed on server package || .
| {{Pkg|mariadb-openrc}} || v3.8 || separate scripts, in past was embebed on server package || .
|}
|}


== Initialization ==
== Initialization ==


The alpine package of MySQL/MariaDB are like normal tarball of MySQL one, admins must know what they want.. there's no automatic window-like installation here.
The version of MariaDB in the Alpine repositories behave like the MySQL tarball. No graphical tools are included.


The ''datadir'' located at <code>/var/lib/mysql</code> must be owned by the mysql user and group. You can modify this behavior but must edit the service file at <code>/etc/init.d</code> directory. Also, you need to set <code><nowiki>datadir=<YOUR_DATADIR></nowiki></code> under section <code>[mysqld]</code> at the config file.
The ''datadir'' located at {{Path|/var/lib/mysql}} must be owned by the mysql user and group. The location of the ''datadir'' can be changed by editing the <code>mariadb</code> service file in {{Path|/etc/init.d}}. The new location will also need to be set by adding <code><nowiki>datadir=<YOUR_DATADIR></nowiki></code> in the <code>[mysqld]</code> section in a mariadb configuration file.


# Initialize the main mysql database, and the data dir as standardized to <code>/var/lib/mysql</code> by the rc script.<br>/etc/init.d/mariadb setup
Normal initialization of mariadb can be done as follows:
# Then you can start the service but there's no root password set until this point.<br>/etc/init.d/mariadb start
 
# Secure the installation by running<code>mysql_secure_installation</code>
# Initialize the main mysql database, and the data dir as standardized to {{Path|/var/lib/mysql}} by running <code>rc-service mariadb setup</code>
# Setup permissions for manage others users and databases
# Start the main service. At this point there will be no root password set. <code>rc-service mariadb start</code>
# Secure the database by running <code>mysql_secure_installation</code>
# Setup permissions for managing others users and databases


== Configuration ==
== Configuration ==


In order to finish setup into '''MariaDB''' now provide '''this script called <code>mysql_secure_instalation</code> that also are present as <code>mariadb-secure-installation</code>''', too. This script provides minimal and security setup to the database, and here are the questions made explained:
In order to help with the basic configuration of the database engine, MariaDB provides <code>mysql_secure_installation</code>.
This script walks you through the basics of securing the database. The options are explained below.


# '''Enter current password for root (enter for none):''' If you have previously set up a root password, provide it here and press enter. If correctly entered, the response will be <code>OK, successfully used password, moving on...</code>
# '''Enter current password for root (enter for none):''' If you have previously set up a root password, provide it here and press enter. If not, just press enter.
#  '''Switch to unix_socket authentication [Y/n]''' Setting the root password or using the Unix_socket ensures that only admins can log into engine database. MySQL 5.6 and MariaDB 10.2 introduced socket authentication, where system users are the same as the MySQL/MariaDB users. For production servers you should disable this by answering "n", which will give you the response <code>... skipping.</code>
#  '''Switch to unix_socket authentication [Y/n]''' Setting the root password or using the Unix_socket ensures that only admins can log into engine database. For non-production servers just press "n" to setup a root password, which will give you the response <code>... skipping.</code>
# '''Change the root password? [Y/n]''' This gives you the opportunity to change the root password to a stronger one if necessary. If this is not needed, enter 'n'.
# '''Change the root password? [Y/n]''' Here you can change the root password, or set one if needed. Press "Y" and enter the new password.
# '''Remove anonymous users? [Y/n]''' Remove anonymous users created to log in using socket authentication. For production systems, disallow this by answering 'Y', resulting in: <code>... Success!</code>.
# '''Remove anonymous users? [Y/n]''' Remove anonymous users created to log in using socket authentication. Unless you're sure you need this, answer "Y" to remove them.
# '''Disallow root login remotely? [Y/n]''' Normally, root should only be allowed to connect from 'localhost' in order to protect from password sniffing attempts over the network. Enter 'Y' to get: <code>... Success!</code>.
# '''Disallow root login remotely? [Y/n]''' Normally, root should only be allowed to connect from 'localhost' in order to protect from password sniffing attempts over the network. Answer "Y".
# '''Remove test database and access to it? [Y/n]''' By default, MariaDB comes with a database named 'test' that anyone can access. If this is not needed, 'Y'. The response will be: <code>... Success!</code>.
# '''Remove test database and access to it? [Y/n]''' By default, MariaDB comes with a database named 'test' that anyone can access. If this is not needed, answer "Y".
# '''Reload privilege tables now? [Y/n]''' Reloading the privilege tables will ensure that all changes made so far will take effect immediately. Answer 'Y' and the response will be: <code>... Success!</code>.
# '''Reload privilege tables now? [Y/n]''' Reloading the privilege tables will ensure that all changes made so far will take effect immediately. Answer "Y".


After responding to each question, restart the service with <code>rc-service mariadb restart</code>
After the script exits, restart the service with <code>rc-service mariadb restart</code>
 
To start the database daemon on every boot, run <code>rc-update add mariadb default</code>


=== Configuration files and customization ===
=== Configuration files and customization ===


Due today were influenced by systemd standardization, the famous <nowiki>my.cnf</nowiki> are not more the main config file for the server engine. Now only few variables are defined there and all the settings are provided by independent files into the <code>/etc/my.cnf.d/</code> directory, user own config files are under <code>~/.my.cnf</code> config file of each home dir, and are read after global ones; so then we have:
Rather than being stored in {{Path|my.cnf}}, configuration settings for MariaDB are now organized in separate files. The primary configuration is done by adding files to {{Path|/etc/my.cnf.d/}}. User-specific configuration files are stored in {{Path|~/.my.cnf}}. User-specific configuration files are loaded after the system-wide configuration. The locations of the various configuration files are listed below.


{| class="wikitable"
{| class="wikitable"
|-
|-
! Config file !! Path and name !! Versions of Alpine !! Contents to configure
! Config file !! Versions of Alpine !! Contents to configure
|-
|-
| my.cnf || <nowiki>/etc/mysql/my.cnf</nowiki> || v2 to v3.8 || All the directives, Global config file
| {{Path|/etc/mysql/my.cnf}} || v2 to v3.8 || All the directives, global config file
|-
|-
| mariadb-server.cnf || /etc/my.cnf.d/mariadb-server.cnf || since 3.9 || First Global config file, main directives
| {{Path|/etc/my.cnf.d/mariadb-server.cnf}} || since 3.9 || First global config file, main directives
|-
|-
| .my.cnf || <nowiki>$HOME</nowiki> || all || user name only config directives
| {{path|$HOME/.my.cnf}} || all || user name only config directives
|}
|}


As previously mentioned, this page describes basic usage of MariaDB. For professional usage, [[MySQL]] should also be referenced.


Newer system Alpine packages can set in independent files in any case those commands always works and where are not apply just will ignore the output:
* The following command will configure the server to accept all incoming connections. This should only be done for development, or if the database is not exposed to the Internet or a sensitive network.


* On older Alpine system must set config files for MAX ALLOWED PACKETS to minimun proper amount:
{{Cmd|<nowiki>sed -i "s|.*bind-address\s*=.*|bind-address=0.0.0.0|g" /etc/mysql/my.cnf
sed -i "s|.*bind-address\s*=.*|bind-address=0.0.0.0|g" /etc/my.cnf.d/mariadb-server.cnf
</nowiki>}}


<pre>
* For simple installations, disabling hostname search can improve performance, but is only useful for local servers.
<nowiki>
sed -i "s|.*max_allowed_packet\s*=.*|max_allowed_packet = 100M|g" /etc/mysql/my.cnf
sed -i "s|.*max_allowed_packet\s*=.*|max_allowed_packet = 100M|g" /etc/my.cnf.d/mariadb-server.cnf
</nowiki>
</pre>


* Only allow local connections on cases where there's only one server or no expected to connect from others:
{{Cmd|<nowiki>sed -i "s|.*skip-networking.*|skip-networking|g" /etc/mysql/my.cnf
 
<pre>
<nowiki>
sed -i "s|.*bind-address\s*=.*|bind-address=127.0.0.1|g" /etc/mysql/my.cnf
sed -i "s|.*bind-address\s*=.*|bind-address=127.0.0.1|g" /etc/my.cnf.d/mariadb-server.cnf
</nowiki>
</pre>
 
* If are not in domain controller, dont search for hostnames to improve performance responses (ideal for local only servers):
 
<pre>
<nowiki>
sed -i "s|.*skip-networking.*|skip-networking|g" /etc/mysql/my.cnf
sed -i "s|.*skip-networking.*|skip-networking|g" /etc/my.cnf.d/mariadb-server.cnf
sed -i "s|.*skip-networking.*|skip-networking|g" /etc/my.cnf.d/mariadb-server.cnf
</nowiki>
</nowiki>}}
</pre>
 
* Set default charset to UTF8MB4, in newer versions (since Alpine v3.9), just added a new file to added thus customization, but older versions (below Alpine v3.8)of the package does not have a charset section, so you must added manually to the main configuration in each respective section:
 
<pre>
<nowiki>
cat > /etc/my.cnf.d/mariadb-server-default-charset.cnf << EOF
[client]
default-character-set = utf8mb4
 
[mysqld]
collation_server = utf8mb4_unicode_ci
character_set_server = utf8mb4
 
[mysql]
default-character-set = utf8mb4
EOF
</nowiki>
</pre>
 
== Updating or comming from upgrading ==
 
Mayor Upgrades beetween Alpine linux version are so easy as change the repository version, but the MySQL/MariaDB  engine need some extra steps when this are performed:
 
Upgrade databases on major releases
Upon a major version release of mariadb (for example mariadb-10.1.10-1 to mariadb-10.1.18-1), it is wise to upgrade databases:
 
# keep the old database (mysql sheme) structure of the engine daemon, currently this are not more the case, today this not make sense anymore
# upgrade the MariaDB/MySQL packages, of course with must be done if the upgrade process to mayor alpine version does not!
# run the <code>mysql_upgrade -u root -p</code> script, providing the password or root, (from the new package version) against the old still-running database (mysql sheme). This will produce some error messages; however, the upgrade will succeed.
# Restart the service
 
If are unable to run ''mysql_upgrade'' because MySQL cannot start try run MySQL in safemode with <code>mysqld_safe --datadir=/var/lib/mysql/</code> command and then run the <code>mysql_upgrade -u root -p</code> script.
 
= Relevant important notes =
 
== File system notes about the databases managed ==
 
'''BTRFS Notes'''
 
If the database (in <code>/var/lib/mysql</code>) resides on a Btrfs file system, you should consider disabling '''Copy-on-Write''' for the directory before creating any database (schemes), after initialization you can enabled again. But .. on every database creation (scheme creation), you must disabled again, to avoid corrupted data.


'''ZFS Bock sizes'''
== Updating or coming from upgrading ==


ZFS, unlike most other file systems, has a variable record size, or what is commonly referred to as a block size. By default, the recordsize on ZFS is 128KiB, which means it will dynamically allocate blocks of any size from 512B to 128KiB depending on the size of file being written. Most RDBMSes work in 8KiB-sized blocks by default. Although the block size is tunable for MySQL/MariaDB use an 8KiB block size by default.
When upgrading between Alpine Linux releases, MariaDB may also have a major version change, and the databases should be upgraded to match. The recommended steps in this process are detailed below.


It is usually desirable to tune ZFS instead to accommodate the databases, using a command such as <code>zfs set recordsize=8K /var/lib/mysql</code> (or change /var/lib/mysql to the mount point where /var/lib/mysql resides) and in the interest of saving memory, it is best to simply disable ZFS's caching of the database's file data and let the database do its own job  with <code>zfs set primarycache=metadata /var/lib/mysql</code> (or change /var/lib/mysql to the mount point where /var/lib/mysql resides).
# While it may no longer be strictly necessary, it's useful to backup your databases before upgrading the database version.
# Update Alpine Linux and the MariaDB/MySQL packages.
# Install mariadb-server-utils by running <code>apk add {{pkg|mariadb-server-utils|arch=}}</code>.
# Run <code>mysql_upgrade -u root -p</code> script, and provide the password for the root database user.
# Restart the service by running <code>rc-service mariadb restart</code>.


But beware, these kinds of tuning parameters are only if RDBMSes are setup in dedicated partitions, if your root and of course database are all in one partition, dont do that. Separate ones.
If <code>mysql_upgrade</code> fails because MySQL cannot start, try running MySQL in safemode with <code>mysqld_safe --datadir=/var/lib/mysql/</code>, and then run <code>mysql_upgrade -u root -p</code> again.


= See Also =
= See Also =


* [[Production DataBases : mysql]]
* [[MySQL]]
* [[Production LAMP system: Lighttpd + PHP + MySQL]]
* [[Production LAMP system: Lighttpd + PHP + MySQL]]
* [[Alpine newbie developer]]
* [[Alpine newbie lammers]]


[[Category:Newbie]]
[[Category:Newbie]]

Latest revision as of 23:18, 21 March 2024

MariaDB is a community-developed fork of the MySQL relational database management system intended to remain free under the GNU GPL. It is notable for being led by the original developers of MySQL, who forked it due to concerns over its acquisition by Oracle.

This is the general documentation for normal and common general usage, for professional usage please use MySQL that is the same as MariaDB but with several modifications focused on production and security!

Installation

The Alpine Linux repositories no longer include the actual MySQL binaries, installing the mysql-* packages will instead install MariaDB.

Installing mariadb will create the user mysql. When the database is initialized, two users will be added to the database: root and mysql. By default these users will only be accessible if you are logged in as the corresponding system user.

apk add mysql mysql-client

Installing the above packages will add the main components of MariaDB to the system: mariadb-cient and mariadb-server. Other available packages are described in the table below, and are listed in order of relevance for a production server.

MySQL name package Since Alpine: Brief usage Related package
mysql v2 a transitional package that installs mariadb mariadb
mysql-client v2 a transitional package that installs the mariadb client tools mariadb-client
mariadb v2 server equivalent to mysql-server mariadb-common
mariadb-client v2 connection command line and tools mariadb-common
mariadb-doc v3.0 manpages for mariadb man man-pages
mariadb-connector-odbc edge coding or making OS level connections, to any DB without libs install .
mariadb-connector-c v3.8 coding connection on C sources mariadb-connector-c-dev
mariadb-backup v3.8 tool for physical online backups, no longer widely used .
mariadb-server-utils v3.8 server commands not widely used, in past was inside MariaDB package .
mariadb-dev v3.1 development files for MariaDB .
mariadb-test v3.3 testing suite from MariaDB tools .
mariadb-mytop v3.9 data performance monitoring .
mariadb-plugin-rocksdb v3.9 plain key-value event relational for data .
mariadb-static v3.8 static libs for static non depends linking in builds .
mariadb-embedded v3.9 the libmysqld identical interface as the C client mariadb-embedded-dev
mariadb-embedded-dev v3.9 use the normal mysql.h and link with libmysqld instead of libmysqlclient mariadb-dev
mariadb-openrc v3.8 separate scripts, in past was embebed on server package .

Initialization

The version of MariaDB in the Alpine repositories behave like the MySQL tarball. No graphical tools are included.

The datadir located at /var/lib/mysql must be owned by the mysql user and group. The location of the datadir can be changed by editing the mariadb service file in /etc/init.d. The new location will also need to be set by adding datadir=<YOUR_DATADIR> in the [mysqld] section in a mariadb configuration file.

Normal initialization of mariadb can be done as follows:

  1. Initialize the main mysql database, and the data dir as standardized to /var/lib/mysql by running rc-service mariadb setup
  2. Start the main service. At this point there will be no root password set. rc-service mariadb start
  3. Secure the database by running mysql_secure_installation
  4. Setup permissions for managing others users and databases

Configuration

In order to help with the basic configuration of the database engine, MariaDB provides mysql_secure_installation. This script walks you through the basics of securing the database. The options are explained below.

  1. Enter current password for root (enter for none): If you have previously set up a root password, provide it here and press enter. If not, just press enter.
  2. Switch to unix_socket authentication [Y/n] Setting the root password or using the Unix_socket ensures that only admins can log into engine database. For non-production servers just press "n" to setup a root password, which will give you the response ... skipping.
  3. Change the root password? [Y/n] Here you can change the root password, or set one if needed. Press "Y" and enter the new password.
  4. Remove anonymous users? [Y/n] Remove anonymous users created to log in using socket authentication. Unless you're sure you need this, answer "Y" to remove them.
  5. Disallow root login remotely? [Y/n] Normally, root should only be allowed to connect from 'localhost' in order to protect from password sniffing attempts over the network. Answer "Y".
  6. Remove test database and access to it? [Y/n] By default, MariaDB comes with a database named 'test' that anyone can access. If this is not needed, answer "Y".
  7. Reload privilege tables now? [Y/n] Reloading the privilege tables will ensure that all changes made so far will take effect immediately. Answer "Y".

After the script exits, restart the service with rc-service mariadb restart

To start the database daemon on every boot, run rc-update add mariadb default

Configuration files and customization

Rather than being stored in my.cnf, configuration settings for MariaDB are now organized in separate files. The primary configuration is done by adding files to /etc/my.cnf.d/. User-specific configuration files are stored in ~/.my.cnf. User-specific configuration files are loaded after the system-wide configuration. The locations of the various configuration files are listed below.

Config file Versions of Alpine Contents to configure
/etc/mysql/my.cnf v2 to v3.8 All the directives, global config file
/etc/my.cnf.d/mariadb-server.cnf since 3.9 First global config file, main directives
$HOME/.my.cnf all user name only config directives

As previously mentioned, this page describes basic usage of MariaDB. For professional usage, MySQL should also be referenced.

  • The following command will configure the server to accept all incoming connections. This should only be done for development, or if the database is not exposed to the Internet or a sensitive network.

sed -i "s|.*bind-address\s*=.*|bind-address=0.0.0.0|g" /etc/mysql/my.cnf sed -i "s|.*bind-address\s*=.*|bind-address=0.0.0.0|g" /etc/my.cnf.d/mariadb-server.cnf

  • For simple installations, disabling hostname search can improve performance, but is only useful for local servers.

sed -i "s|.*skip-networking.*|skip-networking|g" /etc/mysql/my.cnf sed -i "s|.*skip-networking.*|skip-networking|g" /etc/my.cnf.d/mariadb-server.cnf

Updating or coming from upgrading

When upgrading between Alpine Linux releases, MariaDB may also have a major version change, and the databases should be upgraded to match. The recommended steps in this process are detailed below.

  1. While it may no longer be strictly necessary, it's useful to backup your databases before upgrading the database version.
  2. Update Alpine Linux and the MariaDB/MySQL packages.
  3. Install mariadb-server-utils by running apk add mariadb-server-utils.
  4. Run mysql_upgrade -u root -p script, and provide the password for the root database user.
  5. Restart the service by running rc-service mariadb restart.

If mysql_upgrade fails because MySQL cannot start, try running MySQL in safemode with mysqld_safe --datadir=/var/lib/mysql/, and then run mysql_upgrade -u root -p again.

See Also