How to Retrieve the Koha Database Username and Password

This guide explains how to retrieve the MySQL database username and password for your Koha instance. These credentials are stored in koha-conf.xml and are distinct from your Koha staff login — they are used for the Koha web installer, direct database access, and some administrative tasks.

Database Credentials vs. Staff Login

It is important not to confuse the two sets of credentials:

The database credentials are set automatically when the Koha instance is created. The staff login is set during the Koha web installer and can be reset — see How to Reset the Koha Admin Password.

Step 1: Connect to Your Instance

Connect to your EC2 instance via SSM Session Manager or EC2 Instance Connect. See How to Connect to Your Koha EC2 Server for full details.

Step 2: Retrieve the Credentials

Method A — Using koha-passwd (quickest)

koha-passwd reads the password directly from koha-conf.xml:

sudo koha-passwd library

When run in an interactive terminal, it displays the username and password, then clears the screen after you press Enter:

Username for library: koha_library
Password for library: <generated-password>
Press enter to clear the screen...

To get just the password without the interactive prompt (useful in scripts):

sudo koha-passwd library | cat

Method B — Reading koha-conf.xml directly

The credentials are stored in /etc/koha/sites/<instance>/koha-conf.xml. You can read specific fields using xmlstarlet:

# Database username
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/library/koha-conf.xml

# Database password
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/library/koha-conf.xml

# Database name
sudo xmlstarlet sel -t -v 'yazgfs/config/database' /etc/koha/sites/library/koha-conf.xml

Or read the relevant section directly with grep:

sudo grep -E '<user>|<pass>|<database>|<hostname>' /etc/koha/sites/library/koha-conf.xml | tail -4

Example output:

<database>koha_library</database>
<hostname>localhost</hostname>
<user>koha_library</user>
<pass>generated-password-here</pass>

When You Need These Credentials

Koha web installer: During initial setup, the web installer asks for the database username and password to create the Koha schema. Use the credentials from koha-conf.xml.

Direct MySQL access: If you need to run SQL queries against the Koha database directly:

# Using the koha-mysql wrapper (recommended — no credentials needed)
sudo koha-mysql library

# Or using mysql directly with credentials from koha-conf.xml
sudo mysql -u koha_library -p koha_library

The koha-mysql wrapper is the recommended approach — it reads credentials from koha-conf.xml automatically.

Backup and restore: Some backup tools or scripts may require the database credentials directly.

Frequently Asked Questions

Does the database password change automatically?

Yes — on KohaSupport AMIs, the database password is automatically regenerated on every instance restart. An Ansible playbook (rotate_koha_secrets) runs at boot via a cron @reboot job. It generates new passwords for the Koha MySQL user and the MySQL maintenance user, updates koha-conf.xml with the new value, and restarts Koha services. This means koha-passwd library will return a different password after every reboot — that is expected behaviour.

Can I change the database password manually?

It is not recommended. If you need to rotate the database password outside of a reboot, re-run the secrets rotation playbook directly: sudo ansible-playbook /etc/ansible/rotate_koha_secrets_playbook.yml. Do not change the MySQL user password without also updating koha-conf.xml, or Koha will fail to connect to its database.

I can’t find koha-conf.xml — where is it?

The file is at /etc/koha/sites/<instance-name>/koha-conf.xml where <instance-name> is typically library. To list all instances: sudo koha-list.

The password contains special characters — is that normal?

Yes. Koha generates strong passwords with punctuation characters. Be careful when using the password in scripts or connection strings — quote it appropriately.