Koha Solutions

Installation & setup

MySQL or MariaDB for Koha, and which version

Install MariaDB from your distribution's own repository. Both work — Koha depends on a virtual package that either satisfies — but one of them is what everybody else is running.

Updated 2026-08-12 · Tested against Koha 26.05

Install MariaDB from your distribution's own repository — sudo apt install mariadb-server — and let the version be whatever that release ships. Koha depends on the virtual package virtual-mysql-server, so MySQL satisfies it equally; MariaDB is the recommendation because it is what the community runs, tests against and answers questions about.

Step 1Install it before you create the instance

Terminal
$ sudo apt -y install mariadb-server$ sudo systemctl enable --now mariadb$ sudo mysql_secure_installation

Order matters: koha-create does not install a database server, it connects to one. Creating an instance first simply fails.

You will not need the root password again during normal use. Koha connects as its own generated user, one per instance, and koha-mysql reads those credentials out of the instance configuration for you:

Terminal
$ sudo koha-mysql library -e "SELECT VERSION();" VERSION()10.11.13-MariaDB-0+deb12u1

Which one, honestly

ChoiceWhat it means for you
<strong>MariaDB from the distribution</strong>The default. Present in Debian and Ubuntu, satisfies Koha's dependency, and matches what almost every published Koha answer assumes.
<strong>MySQL from the distribution</strong>Works. You will occasionally hit a difference in defaults — SQL mode, authentication plugin — that a MariaDB-shaped answer does not mention.
<strong>Either, from the vendor's own repository</strong>Adds a second moving part with its own upgrade schedule, for a version Koha does not ask for. Worth it only if your institution already standardises on it.
<strong>A managed cloud database</strong>Supported — the host and credentials are just configuration — but plan for the latency of every query crossing a network, and check that the provider allows the settings below.

The version question is usually the wrong question

What matters is that the server is one your distribution ships and patches, not that it is the newest. Koha does not need a recent feature; it needs a database that receives security updates for as long as the catalog lives.

The settings that actually matter

Two, and both are about characters rather than performance.

Character set

A library catalog contains names, titles and subjects in scripts the person who installed the server does not read. The database has to store all of them, which means UTF-8 throughout — the database, the tables and the connection. A modern Debian or Ubuntu MariaDB defaults to a UTF-8 collation, so this is normally already right, and worth confirming rather than assuming:

Terminal
$ sudo koha-mysql library -e "SHOW VARIABLES LIKE 'character_set_database';" Variable_name	Valuecharacter_set_database	utf8mb4

Getting this wrong is not a cosmetic problem: records imported into a database with the wrong character set are damaged at the moment they are written, and no later fix recovers what was lost. Check it before the first import, not after.

SQL mode

Strict SQL modes cause Koha to reject writes that older, laxer settings accepted — most visibly during a migration, where a stray empty value in a date column becomes an error rather than a zero date. If an import fails with Incorrect date value or Data truncated, this is why, and the answer is to clean the data rather than to loosen the mode permanently on a live catalog.

Whatever you choose, back it up as an instance

A mysqldump of the Koha database is not a Koha backup. It leaves out koha-conf.xml — the database credentials, the ports, the paths — so restoring it onto a rebuilt server gives you a database nothing can open. koha-dump captures both, which is why it is the command to use: see backing up Koha with koha-dump.

Why Koha does not simply require one of them

The packaging depends on mysql-client | virtual-mysql-client rather than on a named product. virtual-mysql-client is a Debian convention: any package providing a MySQL-compatible client — MariaDB's, MySQL's — satisfies it. The same pattern is used for the server. So the dependency states what Koha needs (a MySQL-protocol database) instead of who supplies it.

That is why both work, and why the honest recommendation is about the community rather than about the software. When notices stop sending or an index needs rebuilding, the answer you find will have been written by somebody running MariaDB on Debian. Matching that costs nothing at install time and saves an afternoon later — which is the same reasoning behind picking the distribution.

The one thing worth deciding deliberately is where the database runs. On the same server is simplest and is what the packaging assumes. Elsewhere is entirely supported, and turns every page load into a network round trip — fine on a fast local network, painful across a WAN, and the first thing to check when a catalog is inexplicably slow.

Share this article

Would rather not do this yourself? We do it as a service — and if you would rather it were already done, it is on Koha Cloud before you log in.