A server built from the earlier version of this guide is stuck. The 12.0 repository that mariadb_repo_setup configured still answers, but 12.0.2 is the last build it will ever serve. Servers pointed at deb.mariadb.org/12.0 by hand fare worse: apt gets a 404. MariaDB has since shipped 12.3 as the long-term branch of the 12 series, and that’s the one to install MariaDB 12.3 on Ubuntu with today.
This guide adds the official repository in the deb822 format with a signed keyring, installs the server, creates a database and user, opens remote access behind ufw, and upgrades a 12.0 box in place. Every command below ran on fresh Ubuntu 26.04 and 24.04 servers in November 2026, installing MariaDB 12.3.3 from deb.mariadb.org, and the upgrade path was replayed on a 24.04 server set up exactly as the old guide left it.
Pick the MariaDB line to run
Run 12.3 if you want the newest features with a long support window. It is an LTS release, and the MariaDB maintenance policy keeps community support for it until June 2029. The rolling lines move faster but are supported for months, not years, and 12.0 has already stopped getting new builds. So unless you’re testing upcoming features on a throwaway box, pick an LTS line and let apt bring you its point releases.
| Option | Type | Community support ends | Who should pick it |
|---|---|---|---|
| MariaDB 12.3 (this guide) | LTS | June 2029 | New servers that want current features |
| MariaDB 11.8 | LTS | June 2028 | Shops standardised on the previous LTS |
| MariaDB 11.4 | LTS | May 2029 | Apps certified against 11.4 |
| MariaDB 13.x | Rolling | A few months per release | Testing upcoming features |
| Ubuntu archive package | Distro | Follows the Ubuntu release | No third-party repo allowed (11.8 on 26.04, 10.11 on 24.04) |
The odd row is 11.4, which MariaDB supports almost a year longer than the newer 11.8, so read the policy page for your line instead of assuming every LTS gets the same window. If your policy forbids extra apt sources, use the package Ubuntu ships instead and follow our guide to install MariaDB from the Ubuntu 26.04 archive. Teams that settled on an older LTS can use the MariaDB 11.8 install on Ubuntu or the MariaDB 11.4 LTS guide, which use the same repository layout with a different version path.
Prerequisites
The lab servers were small cloud VMs with 2 vCPUs and 4 GB of RAM, which is a floor for testing, not a production size. Production sizing depends on your working set, because the InnoDB buffer pool should hold the hot data, so plan memory around database size and connection count rather than CPU. You need:
- Ubuntu 26.04 LTS or 24.04 LTS, amd64 or arm64
- A user with sudo rights
- Outbound HTTPS to deb.mariadb.org, mariadb.org and the mirrors deb.mariadb.org redirects to
- No other MySQL or MariaDB server already installed
Check the last item before you start. A leftover mysql-server package fights the MariaDB packages over the same data directory and the same mysql system user, so apt will try to remove one to install the other. If you find one, back up its data and remove it on purpose rather than letting apt decide.
Add the MariaDB repository
Start by confirming what Ubuntu would install on its own. On 26.04 the archive candidate is the 11.8 package, and on 24.04 it’s 10.11, so without the extra repository you’d quietly get an older branch than you asked for.
apt-cache policy mariadb-server | head -4
On the 26.04 server the candidate came straight from the Ubuntu archive:
mariadb-server:
Installed: (none)
Candidate: 1:11.8.6-5ubuntu0.1
Version table:
Now download the MariaDB release signing key into /etc/apt/keyrings. Keeping it there, rather than in the global trusted keyring, means apt trusts this key only for the source file that names it. That matters because a key in the global keyring can vouch for packages from any repository on the box, which is exactly why apt-key was retired.
sudo apt-get install -y apt-transport-https curl
sudo mkdir -p /etc/apt/keyrings
sudo curl -fsSL -o /etc/apt/keyrings/mariadb-keyring.asc https://mariadb.org/mariadb_release_signing_key.pgp
Next, write the source file in deb822 format. The Suites line reads the codename from /etc/os-release, so the same command works on both releases: it filled in resolute on 26.04 and noble on 24.04. The Signed-By line ties the source to the keyring you just downloaded.
echo "X-Repolib-Name: MariaDB
Types: deb
URIs: https://deb.mariadb.org/12.3/ubuntu
Suites: $(. /etc/os-release && echo $VERSION_CODENAME)
Components: main
Signed-By: /etc/apt/keyrings/mariadb-keyring.asc" | sudo tee /etc/apt/sources.list.d/mariadb.sources
The tee echo shows what landed on disk. Check that Suites holds your codename and not an empty value. An empty suite means /etc/os-release has no VERSION_CODENAME line, and apt can’t find a suite with no name, so edit the file and type the codename in by hand:
X-Repolib-Name: MariaDB
Types: deb
URIs: https://deb.mariadb.org/12.3/ubuntu
Suites: resolute
Components: main
Signed-By: /etc/apt/keyrings/mariadb-keyring.asc
Refresh the package lists and look at the candidate again. The 12.3 in the URI pins you to the LTS branch, so a later apt upgrade brings point releases within it but never jumps you to a rolling line.
sudo apt-get update
apt-cache policy mariadb-server | sed -n "4,10p"
The MariaDB build now wins on version number, with the Ubuntu package still listed below it as a fallback. Both repositories carry priority 500, so apt simply takes the higher version and you don’t need a pin file:

The apt-get update output may show a mirror hostname such as mirrors.xtom.nl instead of deb.mariadb.org. That is expected, because deb.mariadb.org redirects each request to a nearby mirror. The signature check still runs against the keyring you downloaded, so a mirror cannot slip in packages that MariaDB did not sign.
Install MariaDB server and client
Install the server, the client and mariadb-backup in one go. The backup tool has to match the server’s version for hot physical backups, so it’s worth pulling from the same repository now rather than mixing sources later and finding out during a restore.
sudo apt-get install -y mariadb-server mariadb-client mariadb-backup
On 26.04 apt pulled in 31 packages, and the service started and was enabled at boot without any extra step. Confirm the client version, the service state and the server defaults in one pass:
mariadb --version
systemctl status mariadb --no-pager | head -11
sudo mariadb -e "SELECT VERSION(); SELECT @@character_set_server, @@collation_server;"
Look for active (running) and the “Taking your SQL requests now” status line. The collation is the newer utf8mb4_uca1400_ai_ci, which sorts and compares text differently from the old utf8mb4_general_ci. So if you import a dump from a 10.x server whose app relied on the old sort order, set the collation per database rather than assuming it carried over.

The migrated-from-my.cnf-settings.conf drop-in is written by the server package’s install script. It moves settings that systemd has to own, such as open file limits, out of my.cnf and into the unit. You can leave it alone, but remember it exists when a limit you set in my.cnf seems to be ignored.
The same commands on Ubuntu 24.04 replaced a 10.11 candidate and installed 32 packages, one more than on 26.04. The service, collation and loopback binding came out identical, so the rest of this guide applies to both releases unchanged:

By default the server listens only on loopback. That is the safe choice for a fresh box, because nothing outside the server can reach port 3306 until you decide it should, and we’ll change it deliberately in the remote access section.
sudo ss -tlnp | grep 3306
Only 127.0.0.1:3306 should appear:
LISTEN 0 80 127.0.0.1:3306 0.0.0.0:* users:(("mariadbd",pid=3166,fd=28))
The 24.04 server showed the same loopback-only listener, so neither release exposes the database until you change it.
Check the defaults before you harden anything
Most guides tell you to run mariadb-secure-installation straight after the install. On this release it’s largely redundant, and the script says so itself the moment it starts. Look at what a fresh install actually contains first, so you know what you’re hardening:
sudo mariadb -e "SELECT User, Host, JSON_VALUE(Priv, \"$.plugin\") AS plugin FROM mysql.global_priv; SHOW DATABASES;"
There are three local system accounts, no anonymous user and no test database. Those last two are the main things the script exists to remove, so on a fresh install there’s little left for it to do:

Don’t be thrown by the plugin column showing mysql_native_password for root. JSON_VALUE returns only the first method, and SHOW GRANTS FOR 'root'@'localhost' reveals the full chain: IDENTIFIED VIA mysql_native_password USING 'invalid' OR unix_socket. No password can match 'invalid', so root actually gets in through the unix socket, which is why sudo mariadb logs you in with no password. Running the script anyway is harmless. On the 26.04 server it opened with this note and then found nothing to drop:
sudo mariadb-secure-installation
The banner is the useful part of the output:
NOTE: MariaDB is secure by default. Running this script is mostly
unecessary and it will likely be removed in a future release,
but it is for now preserved for backwards compatibility.
Answer n to switching to unix_socket and to changing the root password, since root is already protected. Do not build new provisioning code around this script, because upstream plans to remove it and your Ansible role or cloud-init file would break on that release. Creating the accounts you need with plain SQL, as the next section does, is the version that keeps working.
Create a database and an application user
Applications should never log in as root. Create one database and one user scoped to it, and keep the host part as narrow as the app allows, because a leaked app password then exposes one database from one place instead of the whole server. For an app on the same machine, a localhost user is all you need:
sudo mariadb -e "CREATE DATABASE appdb; CREATE USER 'appuser'@'localhost' IDENTIFIED BY 'Str0ng#Passw0rd'; GRANT ALL PRIVILEGES ON appdb.* TO 'appuser'@'localhost';"
Replace the password with your own, then log in as the new user to prove the grant works. You should see appdb and information_schema and nothing else:
mariadb -u appuser -p'Str0ng#Passw0rd' -e 'SELECT CURRENT_USER(); SHOW DATABASES;'
The output confirms the account and its scope:
CURRENT_USER()
appuser@localhost
Database
appdb
information_schema
If mysql or performance_schema show up in that list, the user has more than you meant to give it. Check the grant with SHOW GRANTS and look for a stray *.* before the app goes live.
Use caching_sha2_password for MySQL clients
MariaDB ships a caching_sha2_password plugin for applications whose MySQL driver expects MySQL 8 style authentication. It isn’t new to this line, since it is also in recent 11.4 and 11.8 builds, and the plugin documentation positions it as a migration aid, recommending MariaDB’s own PARSEC plugin for new setups. Use it when you’re moving an app off MySQL and its driver won’t negotiate anything else. It isn’t loaded by default, and the library name doesn’t match the plugin name, which cost us two failed attempts in the lab. Load it from auth_mysql_sha2:
sudo mariadb -e "INSTALL PLUGIN caching_sha2_password SONAME 'auth_mysql_sha2';"
Restart the server straight away. The plugin needs an RSA key pair in the data directory, and in the lab it was the restart that generated it. When we ran a query in the same call as INSTALL PLUGIN instead, the client lost its connection on both 26.04 and 24.04, so treat the restart as part of the install step.
sudo systemctl restart mariadb
sudo ls /var/lib/mysql/ | grep pem
Both private_key.pem and public_key.pem should be listed. Since appuser@localhost already exists from the previous step, the SHA2 account gets its own name, appsha. Create it with the plugin and check the grant:
sudo mariadb -e "CREATE USER 'appsha'@'localhost' IDENTIFIED VIA caching_sha2_password USING PASSWORD('Str0ng#Passw0rd'); GRANT ALL PRIVILEGES ON appdb.* TO 'appsha'@'localhost'; SHOW GRANTS FOR 'appsha'@'localhost';"
The grant shows the SHA2 hash format, shortened here:
Grants for appsha@localhost
GRANT USAGE ON *.* TO `appsha`@`localhost` IDENTIFIED VIA caching_sha2_password USING '$A$005$...'
GRANT ALL PRIVILEGES ON `appdb`.* TO `appsha`@`localhost`
Log in as appsha over TCP to prove the plugin accepts it, and check which TLS version the session got:
mariadb -u appsha -p'Str0ng#Passw0rd' -h 127.0.0.1 -e "SELECT CURRENT_USER(); SHOW STATUS LIKE 'Ssl_version';"
The 24.04 server returned the SHA2 account on an encrypted session:
CURRENT_USER()
appsha@localhost
Variable_name Value
Ssl_version TLSv1.3
That TLSv1.3 came without any certificate setup on our side. It matters for this plugin, because it sends the password either over a secure channel or through the RSA key exchange, and TLS being on by default means you skip the RSA dance. The 26.04 session below shows the whole sequence, from the wrong library name to a TLS login:

For apps on other hosts, the plain IDENTIFIED BY form in the next section is enough unless the driver insists on SHA2. We would only reach for the plugin when a client library refuses to connect without it.
Allow remote connections through ufw
Opening MariaDB to the network takes three changes: the bind address, the firewall and a user whose host part matches the client. Miss any one and the client fails with a different error, so do them together and test once at the end. A refused connection usually means the bind address, a timeout means the firewall, and an access denied error means the user. In this example the database server is 10.0.1.51 and the app servers live in 10.0.1.0/24.
Put the bind change in its own file instead of editing 50-server.cnf. Files in mariadb.conf.d load in name order, so 60-remote-access.cnf overrides the package default. Because the package never touches a file it didn’t ship, the setting also survives every upgrade without a dpkg config prompt:
echo '[mysqld]
bind-address = 0.0.0.0' | sudo tee /etc/mysql/mariadb.conf.d/60-remote-access.cnf
sudo systemctl restart mariadb
Then allow SSH before you enable ufw, so you don’t lock yourself out of a remote server, and open 3306 only to the app subnet. The OpenSSH profile opens port 22 only, so if sshd listens elsewhere, allow that port instead (for example sudo ufw allow 2222/tcp). If you’re already locked out, the cloud provider’s serial console lets you add the rule from outside the firewall:
sudo ufw allow OpenSSH
sudo ufw allow from 10.0.1.0/24 to any port 3306 proto tcp
sudo ufw --force enable
sudo ufw status numbered
The listener has moved to 0.0.0.0:3306, and rule 2 limits who can reach it. There is no IPv6 rule for 3306, which is what you want when the app subnet is IPv4 only:

More rule patterns, such as deleting by number or limiting by interface, are in our UFW firewall commands reference. Now create a user whose host matches the subnet. It reuses the appdb database from earlier, and it is a separate account from appuser@localhost with its own password:
sudo mariadb -e "CREATE USER 'appuser'@'10.0.1.%' IDENTIFIED BY 'Str0ng#Passw0rd'; GRANT ALL PRIVILEGES ON appdb.* TO 'appuser'@'10.0.1.%';"
Test from an app server in that subnet (10.0.1.50 here) with the client installed. The @@hostname column proves you reached the database host and not a local server that happens to have the same user:
mariadb -h 10.0.1.51 -u appuser -p'Str0ng#Passw0rd' -e 'SELECT @@hostname, CURRENT_USER(), VERSION();'
The 24.04 database server answered with the subnet account:
@@hostname CURRENT_USER() VERSION()
db02 [email protected].% 12.3.3-MariaDB-ubu2404
If you plan a replica next, the same bind and firewall changes apply on both nodes, and our MariaDB replication guide for Ubuntu and Debian picks up from here.
Upgrade an existing 12.0 server
The earlier version of this guide set up the repository with mariadb_repo_setup and the mariadb-12.0 flag. That repository still answers, so nothing ever errors, but 12.0.2 is the last build on it, and the script also drops a pin file that gives dlm.mariadb.com priority 1000. The result is a server that reports nothing to upgrade, quietly, forever. We rebuilt that server on 24.04 with the old command and a small shop.orders table to check afterwards. See where yours stands:
apt-cache policy mariadb-server | sed -n "1,6p"
Installed and candidate are the same 12.0 build, served from the 12.0 path at the pinned priority:
mariadb-server:
Installed: 1:12.0.2+maria~ubu2404
Candidate: 1:12.0.2+maria~ubu2404
Version table:
*** 1:12.0.2+maria~ubu2404 1000
1000 https://dlm.mariadb.com/repo/mariadb-server/12.0/repo/ubuntu noble/main amd64 Packages
Take a backup before any server upgrade, because a package upgrade rewrites the system tables and there is no clean way back down once it has. A logical dump or a mariadb-backup copy takes minutes on a small database, and our guide to MariaDB backup with point-in-time recovery covers both. With that done, rerun the setup script with the 12.3 version:
curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | sudo bash -s -- --mariadb-server-version=mariadb-12.3 --skip-maxscale
The script renames the old source file with a .old_1.disabled suffix, writes the 12.3 path and runs apt-get update itself, so the candidate changes straight away. Our lab server had the newer mariadb.sources file; a server set up before mid-2026 more likely has mariadb.list, and the script sets that one aside the same way. We passed --skip-maxscale because a plain database server never uses the MaxScale repository; leave the flag off if you run MaxScale. Now upgrade only the MariaDB packages, so the database change isn’t mixed with unrelated system updates and any problem has one obvious cause:
sudo apt-get install -y --only-upgrade mariadb-server mariadb-client mariadb-backup
Apt upgraded 10 packages, restarted the service and ran mariadb-upgrade on its own. Check the version, the sample rows we created before the upgrade, and the upgrade marker file:
sudo mariadb -e "SELECT VERSION(); SELECT * FROM shop.orders;"
sudo cat /var/lib/mysql/mariadb_upgrade_info
The rows survived, and the marker file names the new release, which means the system tables were upgraded too. If that file still shows the old version, run sudo mariadb-upgrade by hand before you let the app back in:

The whole upgrade took under a minute with no config changes. On a busy server, plan a short maintenance window anyway, because the service restarts during the package swap and every open connection drops. Apps with a connection pool usually reconnect on their own; older ones may need a restart.
Upgrade a hand-written deb.mariadb.org source
If you wrote the source file yourself against deb.mariadb.org/12.0, apt-get update already fails with the Release file error covered in the troubleshooting section. Swap the URI in place and run the same backup and --only-upgrade steps. We tested this on a second 24.04 server that held the last 12.0 release from archive.mariadb.org:
sudo sed -i "s|^URIs:.*|URIs: https://deb.mariadb.org/12.3/ubuntu|" /etc/apt/sources.list.d/mariadb.sources
sudo apt-get update
sudo apt-get install -y --only-upgrade mariadb-server mariadb-client mariadb-backup
That path ended in the same place, 12.3.3 with every row intact and the marker file updated:

An older one-line mariadb.list file works the same way: change 12.0 to 12.3 in its URL, or delete it and write the deb822 file from the repository section. Never keep both, because apt warns about the duplicate source on every update.
Try the new SQL features
Compared with the previous LTS, this line brings a long list of additions, and the official MariaDB 12.3 changes and improvements page has all of them. These are the ones we ran on the upgraded server, and none needs any configuration:
IS JSONpredicate from the SQL standardUPDATEandDELETEreading from a CTE- Triggers that fire on more than one event
SET SESSION AUTHORIZATIONto act as another user
The examples use the small shop.orders table from our upgrade test. If you don’t have it, create it first:
sudo mariadb -e "CREATE DATABASE shop; CREATE TABLE shop.orders (id INT AUTO_INCREMENT PRIMARY KEY, item VARCHAR(40), qty INT); INSERT INTO shop.orders (item,qty) VALUES ('keyboard',3),('monitor',1),('cable',12);"
The CTE form saves you a temporary table when an update depends on a filtered set. This one bumps the quantity on every order above two:
sudo mariadb shop -e "WITH big AS (SELECT id FROM orders WHERE qty > 2) UPDATE orders SET qty = qty + 1 WHERE id IN (SELECT id FROM big); SELECT * FROM orders;"
Only the keyboard and cable rows qualified, and only they changed:
id item qty
1 keyboard 4
2 monitor 1
3 cable 13
Multi-event triggers remove the old habit of writing one identical trigger per event. That duplication is where audit logic drifts, because someone fixes the insert trigger and forgets the update one. A single AFTER INSERT OR UPDATE trigger now feeds an audit table:
sudo mariadb shop -e "CREATE TABLE audit_log (at DATETIME, note VARCHAR(60)); CREATE TRIGGER orders_audit AFTER INSERT OR UPDATE ON orders FOR EACH ROW INSERT INTO audit_log VALUES (NOW(), CONCAT('order ', NEW.id, ' qty ', NEW.qty)); INSERT INTO orders (item,qty) VALUES ('mouse',2); UPDATE orders SET qty=5 WHERE item='monitor'; SELECT note FROM audit_log;"
Both the insert and the update were logged by the one trigger:
note
order 4 qty 2
order 2 qty 5
SET SESSION AUTHORIZATION is the one DBAs will use most. It lets you test a user’s grants from a root session without knowing their password, so you stop creating throwaway accounts to check a permission. Create a read-only reporter user, switch to it, and try a read and a delete in the same call:
sudo mariadb -e "CREATE USER 'reporter'@'localhost' IDENTIFIED BY 'R3port!ng2026'; GRANT SELECT ON shop.* TO 'reporter'@'localhost'; SET SESSION AUTHORIZATION 'reporter'@'localhost'; SELECT CURRENT_USER(); SELECT COUNT(*) FROM shop.orders; DELETE FROM shop.orders;"
The session ran as reporter, counted the four orders and was refused the delete with ERROR 1142 (42000): DELETE command denied, which is the grant doing its job. IS JSON is the simpler check, handy for validating documents before they reach a JSON column:
sudo mariadb -e "SELECT '{\"a\":1}' IS JSON AS valid_doc, 'not json' IS JSON AS bad_doc;"
The valid document returns 1 and the plain string returns 0. Both results from the lab server:

On the storage side, the latest point release adds an innodb_index_shrink variable. It defaults to ON, which keeps the old behaviour. Turning it off trades slightly sparser index pages for less latch contention on write-heavy tables whose rows grow on update, so leave it alone unless you have measured that contention.
Troubleshooting errors from the lab
Each of these came up while building the servers for this guide, with the exact message apt or the server printed.
The repository does not have a Release file
This is what a server whose source points at deb.mariadb.org/12.0 gets on apt-get update:
Ign:5 https://mirror.mariadb.org/repo/12.0/ubuntu noble InRelease
Err:6 https://mirror.mariadb.org/repo/12.0/ubuntu noble Release
404 Not Found [IP: 192.0.2.10 443]
Reading package lists...
E: The repository 'https://deb.mariadb.org/12.0/ubuntu noble Release' does not have a Release file.
MariaDB removed the 12.0 tree from deb.mariadb.org, and the maintenance policy now lists only the 13.x rolling releases. The packages survive on archive.mariadb.org, and the dlm.mariadb.com path that mariadb_repo_setup writes still serves 12.0.2, but neither will get a newer 12.0 build. Change the URI to the 12.3 path as shown in the upgrade section. The same message appears if Suites names a codename the repository does not build for, so check that line too.
ERROR 1126: Can’t open shared library auth_caching_sha2_password.so
Guessing the library name from the plugin name fails, because the file is auth_mysql_sha2.so. Use INSTALL PLUGIN caching_sha2_password SONAME 'auth_mysql_sha2'; instead of INSTALL SONAME 'auth_caching_sha2_password', then restart the service.
ERROR 1524: Plugin ‘caching_sha2_password’ is not loaded
You ran CREATE USER ... IDENTIFIED VIA caching_sha2_password before loading the plugin. Load it with the command above, restart the service, then create the user again.
ERROR 2013: Lost connection to server during query
We hit this on the query straight after loading the SHA2 plugin, in the same client call, on both test releases. On the 24.04 server the journal explained it with caching_sha2_password: failed to read private_key.pem: 2 "No such file or directory". A sudo systemctl restart mariadb created private_key.pem and public_key.pem in /var/lib/mysql, and every login after that worked. Check journalctl -u mariadb whenever a client drops like this, because the client error never says why. The fix was the same on 26.04, so if you script the plugin install, put the restart right after INSTALL PLUGIN and only then run any query.
ERROR 1698 (28000): Access denied for user
In our case the user simply didn’t exist yet, because the CREATE USER had failed earlier in the same chained command. Query mysql.user as root and confirm both the name and the host part match how the client connects. Remember that 'appuser'@'localhost' and 'appuser'@'10.0.1.%' are separate accounts with separate passwords.
Harden it for production
A single server with remote access is a working start, not a production setup. Before real traffic lands on it, we’d cover these:
- Scheduled backups with tested restores
innodb_buffer_pool_sizesized to your working set- A replica or a Galera cluster for failover
- ufw rules reviewed whenever the app subnet changes
Backups come first, because every other item on that list assumes you can rebuild the data. For high availability, our MariaDB Galera cluster on Ubuntu with ProxySQL builds on the same repository. Running Debian elsewhere in the fleet? The MariaDB 12 guide for Debian uses a matching layout, and RHEL-family hosts are covered in the Rocky Linux and AlmaLinux version of this guide. If you’re newer to the server internals, one of the MySQL and MariaDB books we recommend fills the gaps faster than release notes do.