Installation Guide · Step 7

Configure the Mifos X database

Configure the database used by Apache Fineract, create dedicated users and databases, protect credentials, enable persistent storage, prepare backups and test restoration.

Start database setup Backup and restore

Before configuration

Prerequisites

✓A selected and tested Apache Fineract release
✓A database version supported by that Fineract release
✓Administrative access to the database server
✓A dedicated database user for Apache Fineract
✓Secure storage for database credentials
✓Persistent database storage
✓Separate backup storage
✓A staging environment for testing migrations and restoration

Configuration register

Database values to document

Setting	Guidance
Database hostname	Use a private hostname, Docker service name or private network address. Do not expose the database publicly.
Database port	Use the database engine's configured port and restrict access through the firewall.
Platform database	Stores tenant connection information and platform-level configuration.
Tenant database	Stores operational data such as clients, products, loans, savings, transactions and accounting entries.
Application username	Use a dedicated non-administrative database user for Apache Fineract.
Connection pool	Tune only after observing application load, database capacity and connection usage.
Character set	Use a Unicode-compatible character set suitable for multilingual customer and institutional data.
Time zone	Keep database, application and reporting time-zone settings consistent and documented.

Step-by-step

Configure the Fineract database

Confirm the selected database engine

Review the selected Apache Fineract release documentation and deployment files before choosing a database version.

cd /path/to/fineract

find . -maxdepth 4 -type f \
  \( -name "docker-compose*.yml" -o -name "application*.properties" -o -name "application*.yml" \) \
  -print | sort

grep -R "jdbc:\|datasource\|mysql\|mariadb\|postgres" -n \
  config fineract-provider 2>/dev/null | head -120

Expected result: You should identify the database engine and connection settings expected by the selected release.

Create a dedicated database user

Do not use the database root or administrative account for normal application access.

CREATE USER 'fineract_app'@'%' IDENTIFIED BY 'REPLACE_WITH_STRONG_PASSWORD';

Expected result: A separate application account should exist for Apache Fineract.

Create the required databases

Create the platform and tenant databases required by the selected deployment model.

CREATE DATABASE fineract_tenants
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

CREATE DATABASE fineract_default
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

Expected result: The platform and tenant databases should appear in the database catalogue.

Grant controlled permissions

Grant only the permissions required for the application and migrations.

GRANT ALL PRIVILEGES ON fineract_tenants.* TO 'fineract_app'@'%';
GRANT ALL PRIVILEGES ON fineract_default.* TO 'fineract_app'@'%';

FLUSH PRIVILEGES;

Expected result: The application user should be able to access only the required databases.

Test database login

Verify the application user credentials before starting Apache Fineract.

mysql \
  -h DATABASE_HOST \
  -P 3306 \
  -u fineract_app \
  -p

Expected result: The dedicated application user should connect successfully.

Store credentials securely

Keep credentials outside the Git repository and restrict file permissions.

mkdir -p /opt/mifos/config

touch /opt/mifos/config/database.env
chmod 600 /opt/mifos/config/database.env

nano /opt/mifos/config/database.env

Expected result: The environment file should be readable only by the deployment user.

Configure persistent storage

Ensure database data remains available when containers restart or are recreated.

docker volume ls

docker inspect DATABASE_CONTAINER_NAME | \
  grep -A20 -B5 Mounts

Expected result: The database should use a named volume or securely mounted persistent directory.

Start the database first

Confirm database health before starting Apache Fineract.

docker compose up -d database

docker compose ps
docker compose logs --tail=200 database

Expected result: The database service should show a healthy or running status without recurring errors.

Start Apache Fineract and monitor migrations

Watch the backend logs carefully while Liquibase validates and updates the schema.

docker compose up -d fineract

docker compose logs -f fineract

Expected result: Liquibase migrations should complete successfully and Fineract should start.

Verify database growth and connectivity

Confirm that expected tables exist and the backend health check succeeds.

mysql \
  -h DATABASE_HOST \
  -u fineract_app \
  -p \
  -e "SHOW DATABASES; USE fineract_default; SHOW TABLES;"

curl -k \
  https://127.0.0.1:8443/fineract-provider/actuator/health

Expected result: Tables should exist in the tenant database and the Fineract health endpoint should respond.

Data protection

Backup and restore

A backup is useful only after it has been successfully restored and validated in a separate environment.

Create a logical database backup

mysqldump \
  --single-transaction \
  --routines \
  --triggers \
  --events \
  -h DATABASE_HOST \
  -u BACKUP_USER \
  -p \
  fineract_default \
  > fineract_default_$(date +%F_%H-%M-%S).sql

Compress the backup

gzip fineract_default_YYYY-MM-DD_HH-MM-SS.sql

Verify the backup file

gzip -t fineract_default_YYYY-MM-DD_HH-MM-SS.sql.gz

ls -lh fineract_default_YYYY-MM-DD_HH-MM-SS.sql.gz

Restore into a staging database

gunzip -c fineract_default_YYYY-MM-DD_HH-MM-SS.sql.gz | \
  mysql \
    -h STAGING_DATABASE_HOST \
    -u RESTORE_USER \
    -p \
    fineract_staging

Upgrade safety

Database migration rules

!Never run untested migrations directly on production.
!Restore production data into staging before an upgrade.
!Record the currently deployed Fineract version and database schema.
!Review release notes and Liquibase changes.
!Take complete backups before starting the upgrade.
!Stop write traffic during controlled migrations where required.
!Retain the previous application version for rollback.
!Validate balances, transactions, accounting and reports after migration.

Troubleshooting

Common database problems

Access denied for database user

Verify the username, password, allowed host, database grants and authentication plugin.

Unknown database

Confirm the platform and tenant databases were created using the names configured in Fineract.

Connection refused

Check the hostname, port, firewall, container network and database service status.

Too many connections

Review the application connection pool, database connection limit and abandoned connections.

Liquibase checksum failure

Do not manually clear checksums in production without understanding the migration history and testing recovery.

Disk space exhausted

Review database growth, logs, binary logs, temporary files, backups and volume capacity.

MifosX database services

Need help securing or migrating a Fineract database?

MifosX provides Apache Fineract database configuration, migration, backup design, restore testing, performance tuning and production support.

Talk to a Mifos expert Talk to a MifosX expert

← Previous: Mifos Web App Next: Nginx, domain and SSL →