Prerequisites#

• Vault CLI installed on your machine
• Docker & Docker Compose (to run MariaDB)
• A Unix-like terminal (Linux, macOS, or WSL on Windows)

Configuration Placeholders#

The table below lists the placeholder variables used throughout this guide. Replace them with your environment’s actual values:

Step 1: Install Vault (Dev Mode)#

For local testing and exploration, you don’t need a full production Vault setup (unsealing, persistent storage backends, etc.). The dev server starts pre-unsealed with an in-memory storage backend — perfect for learning.

1
brew tap hashicorp/tap
2
brew install hashicorp/tap/vault

1
sudo apt update
2
sudo apt install -y gnupg wget lsb-release
3

4
wget -O- https://apt.releases.hashicorp.com/gpg \
5
  | gpg --dearmor \
6
  | sudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg > /dev/null
7

8
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" \
9
  | sudo tee /etc/apt/sources.list.d/hashicorp.list
10

11
sudo apt update
12
sudo apt install -y vault

1
vault --version

1
Vault v2.0.4 (c9e9d1d4ddd4b55aae79a8949adffa9e96338720), built 2026-08-03T16:14:36Z

1
vault server -dev -dev-root-token-id="root"

1
WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
2
and starts unsealed with a single unseal key. The root token is already
3
authenticated to the CLI, so you can immediately begin using Vault.
4

5
You may need to set the following environment variables:
6

7
    $ export VAULT_ADDR='http://127.0.0.1:8200'
8

9
The unseal key and root token are displayed below in case you want to
10
seal/unseal the Vault or re-authenticate.
11

12
Unseal Key: c+pRvn/2UC6tGpAH5ucQ9Qejufbxnpl/u0UuHTWnoKc=
13
Root Token: root
14

15
Development mode should NOT be used in production installations!

1
export VAULT_ADDR='http://127.0.0.1:8200'
2
export VAULT_TOKEN='root'

1
vault status

1
Key             Value
2
---             -----
3
Seal Type       shamir
4
Initialized     true
5
Sealed          false
6
Total Shares    1
7
Threshold       1
8
Version         2.0.4
9
Build Date      2026-08-03T16:14:36Z
10
Storage Type    inmem
11
Cluster Name    vault-cluster-b032d240
12
Cluster ID      3ae78de0-3009-c9b6-5993-caba26940ba5
13
HA Enabled      false

Alternative: Run Vault Without Dev Mode (via config.hcl)#

Dev mode is great for quick exploration, but it stores everything in-memory (wiped on process exit) and starts fully unsealed automatically — which doesn’t reflect how Vault behaves in a real environment. If you want a more realistic setup (persistent data, manual init/unseal), use a configuration file instead.

1
storage "file" {
2
  path = "/opt/vault/data"
3
}
4

5
listener "tcp" {
6
  address     = "<VAULT_HOST>:<VAULT_PORT>"
7
  tls_disable = true
8
}
9

10
api_addr = "http://<VAULT_HOST>:<VAULT_PORT>"
11
ui       = true

1
sudo mkdir -p /opt/vault/data
2
sudo chown -R $(whoami) /opt/vault/data

1
vault server -config=config.hcl

1
==> Vault server configuration:
2

3
                     Cgo: disabled
4
              Go Version: go1.26.5
5
              Listener 1: tcp (addr: "<VAULT_HOST>:8200", cluster address: "<VAULT_HOST>:8201", tls: "disabled")
6
                   Mlock: supported: true, enabled: false
7
           Recovery Mode: false
8
                 Storage: file
9
                 Version: Vault v2.0.4, built 2026-08-03T16:14:36Z
10

11
==> Vault server started! Log data will stream in below:
12

13
[INFO]  proxy environment: http_proxy="" https_proxy="" no_proxy=""
14
[INFO]  incrementing seal generation: generation=1
15
[INFO]  core: Initializing version history cache for core
16
[INFO]  events: Starting event system
17
[INFO]  core: security barrier not initialized
18
[INFO]  core: seal configuration missing, not initialized

1
export VAULT_ADDR='http://<VAULT_HOST>:<VAULT_PORT>'

1
vault operator init

1
Unseal Key 1: xxxxx
2
Unseal Key 2: xxxxx
3
Unseal Key 3: xxxxx
4
Unseal Key 4: xxxxx
5
Unseal Key 5: xxxxx
6

7
Initial Root Token: hvs.xxxxxxxxxxxxxxxx

1
vault operator unseal   # Enter Unseal Key 1
2
vault operator unseal   # Enter Unseal Key 2
3
vault operator unseal   # Enter Unseal Key 3

1
vault status

1
vault login
2
# Enter the Initial Root Token from `vault operator init`

Step 2: Set Up MariaDB (Docker Compose)#

Create a docker-compose.yml file to spin up a MariaDB instance:

1
services:
2
  database:
3
    container_name: mariadb
4
    image: mariadb:latest
5
    restart: always
6
    ports:
7
      - "<MARIADB_PORT>:3306"
8
    environment:
9
      - MARIADB_ROOT_PASSWORD=<MARIADB_ROOT_PASSWORD>
10
    volumes:
11
      - mariadb-data:/var/lib/mysql
12

13
volumes:
14
  mariadb-data:
15
    name: mariadb-data

Start the container:

1
docker compose up -d

Verify it’s running:

1
docker ps

Output:

1
CONTAINER ID   IMAGE            COMMAND                  CREATED         STATUS         PORTS                    NAMES
2
de13ac6ba5cb   mariadb:latest   "docker-entrypoint.s…"   4 seconds ago   Up 3 seconds   0.0.0.0:3306->3306/tcp   mariadb

With this configuration, MariaDB is accessible at:

The root credentials are what Vault uses as its management account — Vault will authenticate as root to create and revoke dynamic user accounts on your behalf.

Step 3: Configure Vault Database Secrets Engine#

Before proceeding, make sure that MariaDB at <MARIADB_HOST>:<MARIADB_PORT> is reachable from the machine where Vault is running.

1
vault secrets enable database

1
Success! Enabled the database secrets engine at: database/

1
vault write database/config/mariadb \
2
  plugin_name=mysql-database-plugin \
3
  connection_url="{{username}}:{{password}}@tcp(<MARIADB_HOST>:<MARIADB_PORT>)/" \
4
  allowed_roles="*" \
5
  username="root" \
6
  password="<MARIADB_ROOT_PASSWORD>"

1
vault write database/roles/db-admin \
2
  db_name=mariadb \
3
  creation_statements="CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}';" \
4
  creation_statements="GRANT ALL PRIVILEGES ON *.* TO '{{name}}'@'%';" \
5
  revocation_statements="DROP USER '{{name}}'@'%';" \
6
  default_ttl="1h" \
7
  max_ttl="1h"

1
vault write database/roles/db-read-only \
2
  db_name=mariadb \
3
  creation_statements="CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}';" \
4
  creation_statements="GRANT SELECT ON *.* TO '{{name}}'@'%';" \
5
  revocation_statements="DROP USER '{{name}}'@'%';" \
6
  default_ttl="1h" \
7
  max_ttl="1h"

Step 4: Generate Dynamic Credentials#

With the roles in place, request credentials on demand. You no longer need to know or manage any static passwords.

Admin credentials:

1
vault read database/creds/db-admin

Read-only credentials:

1
vault read database/creds/db-read-only

Example output:

1
Key                Value
2
---                -----
3
lease_id           database/creds/db-read-only/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6
4
lease_duration     1h
5
lease_renewable    true
6
password           yY-57n3X5UQhxnmFRP3f
7
username           v-root-db-read-onl-crBWVqVh2Hc1

Each invocation creates a brand-new MariaDB user with a randomly generated username and password. When the TTL expires, Vault automatically executes the revocation_statements to drop that user from MariaDB.

Step 5: Verify the Credentials#

Use the freshly generated credentials to authenticate against MariaDB:

1
mariadb -h <MARIADB_HOST> \
2
  -u v-root-db-read-onl-crBWVqVh2Hc1 \
3
  -pyY-57n3X5UQhxnmFRP3f \
4
  -e "SHOW DATABASES;"

Expected behavior:

• Credentials from db-admin can execute any SQL operation (DDL, DML, etc.)
• Credentials from db-read-only: SELECT queries succeed; INSERT, DROP, etc., are rejected with an access denied error

If both behave as expected, the Vault and MariaDB integration is working correctly.

Step 6 (Optional): Lease Management & Manual Revocation#

1
vault list sys/leases/lookup/database/creds/db-read-only

1
vault lease revoke database/creds/db-read-only/<lease_id>

1
vault lease revoke -prefix database/creds/db-read-only/

Why This Matters: Security Benefits#

What’s Next#

Once you’ve verified the basic flow, consider exploring these advanced capabilities:

• Root credential rotation — Let Vault manage and rotate the root password it uses:

  1
  vault write -force database/rotate-root/mariadb
  

  After this command, only Vault knows the root password.

• Static roles — For existing long-lived database users that need periodic password rotation rather than dynamic creation.

• Vault Agent — A sidecar daemon that automatically fetches and renews credentials, injecting them into your application’s environment or config files with zero code changes.

• Vault API / SDK — Integrate dynamic credential retrieval directly into your application at startup time using the Vault HTTP API or language-specific SDKs (Go, Python, Java, etc.).

Conclusion#

By integrating HashiCorp Vault’s Database Secrets Engine with MariaDB, you fundamentally change how applications access your database:

• No more static passwords — credentials are generated on-demand and never stored in plaintext
• Automatic isolation — every consumer gets a unique credential, making audit logs precise and breach impact minimal
• Zero-config revocation — credentials expire automatically; incident response is a single vault lease revoke command away

This pattern is the foundation of secrets management at scale and applies equally well to PostgreSQL, MySQL, Oracle, MongoDB, and other supported database engines.

Reference: Vault MySQL/MariaDB Database Secrets Engine — HashiCorp Docs