Authentication Profiles

Command

Command authentication profiles allow you to retrieve credentials dynamically by executing shell commands. This enables integration with external secret managers like 1Password CLI, HashiCorp Vault, AWS Secrets Manager, and any custom credential retrieval scripts.

Key Benefits

Secret Manager Integration: Connect to 1Password, Vault, AWS Secrets Manager, etc.
Dynamic Credentials: Retrieve fresh credentials on each connection
Custom Scripts: Use any script or CLI tool that outputs credentials
Environment Variables: Connection details are available as environment variables
Credential Caching: Optional caching to reduce secret manager calls

Configuration Options

Command

The shell command to execute. Connection configuration values are available as environment variables:

Variable	Description
`${host}`	Database host
`${port}`	Database port
`${database}`	Database name
`${name}`	Connection name
`${driver}`	Database driver type

Output Format

Text Output

Password only: Command outputs just the password
Username:Password: Command outputs username:password separated by colon

JSON Output

Parse structured JSON with configurable field paths
Supports nested paths like data.credentials.password

Credential Caching

Mode	Description
No caching	Execute command every time
Fixed TTL	Cache for specified duration (seconds)
From output	Read the expiry from a field in the JSON output

With From output, set Expiry Field to the JSON path and Expiry Format to match what the field holds:

Expiry Format	Example value
Timestamp (milliseconds)	`1769860800000`
Timestamp (seconds)	`1769860800`
ISO 8601 date	`2026-01-31T12:00:00Z`
Duration (seconds)	`3600`
Duration (minutes)	`600`

Durations count from when the command ran. If the expiry can’t be read or is already in the past, the credentials aren’t cached and the reason is written to the DBCode output panel.

Testing a Command

Click Test at the bottom of the profile editor to run the command with the current settings, before saving. The result shows the username, the password masked, and when the credentials would expire from the cache, plus anything the command wrote to stderr. Connection variables such as ${host} aren’t set during a test, since no connection is involved.

Example Commands

Here are example commands for popular secret managers:

1Password CLI

op read "op://Private/PostgreSQL Production/password"

HashiCorp Vault

vault kv get -format=json secret/databases/production | jq -r '.data.data'

Use JSON output format with username and password fields.

AWS Secrets Manager

aws secretsmanager get-secret-value --secret-id prod/db/credentials --query SecretString --output text

Use JSON output format to parse the returned secret.

Azure Key Vault

az keyvault secret show --vault-name my-vault --name db-password --query value -o tsv

Bitwarden CLI

bw get password database-production

Doppler

doppler secrets get DB_PASSWORD --plain

Custom Script

Your script receives connection details as environment variables named after the connection settings:

#!/bin/bash
# Available: host, port, database, name, driver
echo "{\"user\": \"app_${database}\", \"pass\": \"$(fetch_password $host)\"}"

JSON Output Format

When using JSON output, your command should return a JSON object:

{
  "username": "db_user",
  "password": "secret123",
  "expiresAt": 1699900000000
}

Nested Fields

Use dot notation for nested JSON paths. For example, if your command returns:

{
  "data": {
    "credentials": {
      "user": "admin",
      "pass": "secret"
    }
  }
}

Set the username field to data.credentials.user and password field to data.credentials.pass.

Advanced Options

Timeout: Maximum time to wait for command to complete (default: 30 seconds)
Working Directory: Directory where the command runs (defaults to workspace root)

Supported Databases

Command authentication profiles can be used with any database that supports username/password authentication:

PostgreSQL, MySQL, MariaDB
SQL Server, Oracle
MongoDB
And all other databases with password auth

Troubleshooting

”Command timed out”

Cause: Command took longer than the timeout setting.

Solutions:

Increase the timeout value in advanced settings
Ensure the secret manager CLI is responsive
Check network connectivity to the secret manager

”Command failed with exit code X”

Cause: The command returned a non-zero exit code.

Solutions:

Test the command manually in your terminal
Check that the CLI tool is installed and authenticated
Verify the secret path/name is correct

Warnings on stderr

A command that exits successfully but writes to stderr (for example, a CLI update notice) still works. The stderr text is shown in the Test result and written to the DBCode output panel. A command that exits with a non-zero code fails, and its stderr is included in the error.

”Failed to parse JSON output”

Cause: Command output is not valid JSON.

Solutions:

Test the command manually and verify JSON output
Ensure no extra text is output before/after the JSON
Use jq or similar tools to extract clean JSON

”Username/password field not found”

Cause: The specified JSON field path doesn’t exist in the output.

Solutions:

Check the top-level keys listed in the error message
Verify the JSON structure of your command output
Check the field path for typos
Use the correct dot notation for nested fields