From: Robert Silén Date: Mon, 13 May 2024 08:19:10 +0000 (+0300) Subject: Followups for Bug 1467006: Updating db_server.rst and mysql.rst regarding mariadb... X-Git-Tag: bugzilla-5.2~18 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=13189a9805f0cf1dee961f8838786e2f13ae7eba;p=thirdparty%2Fbugzilla.git Followups for Bug 1467006: Updating db_server.rst and mysql.rst regarding mariadb (#169) --- diff --git a/docs/en/rst/installing/db_server.rst b/docs/en/rst/installing/db_server.rst index 8a7d89633b..a06f878502 100644 --- a/docs/en/rst/installing/db_server.rst +++ b/docs/en/rst/installing/db_server.rst @@ -3,15 +3,16 @@ Database Server ############### -Bugzilla requires a database to store its data. We recommend either MySQL or -PostgreSQL for production installations. Oracle 10 should work fine, but very -little or no testing has been done with Oracle 11 and 12. SQLite is easy to -configure but, due to its limitations, it should only be used for testing +Bugzilla requires a database to store its data. We recommend MariaDB, MySQL +or PostgreSQL for production installations. Oracle 10 should work fine, but +very little or no testing has been done with Oracle 11 and 12. SQLite is easy +to configure but, due to its limitations, it should only be used for testing purposes and very small installations. .. toctree:: :maxdepth: 1 + mariadb mysql postgresql oracle diff --git a/docs/en/rst/installing/mariadb.rst b/docs/en/rst/installing/mariadb.rst new file mode 100644 index 0000000000..8cf625f0a3 --- /dev/null +++ b/docs/en/rst/installing/mariadb.rst @@ -0,0 +1,128 @@ +.. _mariadb: + +MariaDB +####### + +The minimum required version is MariaDB 10.0.5. + +It's possible to test which version of MariaDB you have installed with: + +:command:`mariadb -e 'select version()'` + +For MariaDB versions prior to 10.4.6, replace the :command:`mariadb` command +with :command:`mysql` with the same arguments. + +Installing +========== + +Windows +------- + +Download the MariaDB 32-bit or 64-bit MSI installer from the +`MariaDB website `_ (~66 MB). + +MariaDB has a standard Windows installer. It's ok to select a the +default install options. The rest of this documentation assumes assume you +have installed MariaDB into :file:`C:\\mysql`. Adjust paths appropriately if not. + +Linux/Mac OS X +-------------- + +The package install instructions given previously should have installed MariaDB +on your machine, if it didn't come with it already. + +If you did install MariaDB manually rather than from a package, make sure the +server is started when the machine boots. + +Create the Database +=================== + +You need to create a database for Bugzilla to use. Run the :file:`mariadb` +command-line client and enter: + +:: + CREATE DATABASE IF NOT EXISTS bugs CHARACTER SET = 'utf8'; + +The above command makes sure a database like that doesn't exist already. + +.. _mysql-add-user: + +Add a User +========== + +You need to add a new MariaDB user for Bugzilla to use. Run the :file:`mariadb` +command-line client and enter: + +:: + + GRANT SELECT, INSERT, + UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES, + CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.* + TO bugs@localhost IDENTIFIED BY '$DB_PASS'; + +You need to replace ``$DB_PASS`` with a strong password you have chosen. +Write that password down somewhere. + +The above command permits an account called ``bugs`` +to connect from the local machine, ``localhost``. Modify the command to +reflect your setup if you will be connecting from another +machine or as a different user. + +Change Configuration +==================== + +To change MariaDB's configuration, you need to edit your MariaDB +configuration file, which is: + +* Red Hat/Fedora: :file:`/etc/my.cnf` +* Debian/Ubuntu: :file:`/etc/mysql/my.cnf` +* Windows: :file:`C:\\mysql\\bin\\my.ini` +* Mac OS X: :file:`/etc/my.cnf` + +Or :file:`mariadb.cnf` on Unix-like operating systems. + +.. _mysql-max-allowed-packet: + +Allow Large Attachments and Many Comments +----------------------------------------- + +By default on some systems, MariaDB will only allow you to insert things +into the database that are smaller than 1MB. + +Bugzilla attachments +may be larger than this. Also, Bugzilla combines all comments +on a single bug into one field for full-text searching, and the +combination of all comments on a single bug could in some cases +be larger than 1MB. + +We recommend that you allow at least 16MB packets by +adding or altering the ``max_allowed_packet`` parameter in your MariaDB +configuration in the ``[mysqld]`` section, so that the number is at least +16M, like this (note that it's ``M``, not ``MB``): + +:: + + [mysqld] + # Allow packets up to 16M + max_allowed_packet=16M + +.. _mysql-small-words: + +Allow Small Words in Full-Text Indexes +-------------------------------------- + +By default, words must be at least four characters in length +in order to be indexed by MariaDB's full-text indexes. This causes +a lot of Bugzilla-specific words to be missed, including "cc", +"ftp" and "uri". + +MariaDB can be configured to index those words by setting the +``ft_min_word_len`` param to the minimum size of the words to index. + +:: + + [mysqld] + # Allow small words in full-text indexes + ft_min_word_len=2 + +.. _mysql-attach-table-size: diff --git a/docs/en/rst/installing/mysql.rst b/docs/en/rst/installing/mysql.rst index 02ce984d08..10e42d3225 100644 --- a/docs/en/rst/installing/mysql.rst +++ b/docs/en/rst/installing/mysql.rst @@ -3,13 +3,7 @@ MySQL ##### -It is strongly advised to use MariaDB which is a drop-in replacement for -MySQL and is fully compatible with Bugzilla. If MySQL must be used, be -aware that the minimum required version is MySQL 5.0.15 and that MySQL 8 -or higher cannot be used at this time. - -All commands in this document work regardless of whether MySQL or -MariaDB are used. +The minimum required version is MySQL 5.6.12. It's possible to test which version of MySQL you have installed with: @@ -21,12 +15,14 @@ Installing Windows ------- -Download the MariaDB 32-bit or 64-bit MSI installer from the -`MariaDB website `_ (~66 MB). +Download the MySQL Installer for Windows from the +[MySQL website](https://dev.mysql.com/downloads/windows/installer/) +(sizes vary based on the installer version). -MariaDB has a standard Windows installer. It's ok to select a the -default install options. The rest of this documentation assumes assume you -have installed MariaDB into :file:`C:\\mysql`. Adjust paths appropriately if not. +MySQL provides a standard Windows installer. It is recommended to select the +default installation options unless you have specific requirements. This +documentation assumes that you have installed MySQL in `C:\mysql`. Adjust paths +appropriately if your installation directory differs. Linux/Mac OS X -------------- @@ -86,7 +82,7 @@ configuration file, which is: * Red Hat/Fedora: :file:`/etc/my.cnf` * Debian/Ubuntu: :file:`/etc/mysql/my.cnf` * Windows: :file:`C:\\mysql\\bin\\my.ini` -* Mac OS X: :file:`/etc/my/cnf` +* Mac OS X: :file:`/etc/my.cnf` .. _mysql-max-allowed-packet: