Skip to content
Clonit

Database Credentials

Clonit connects to your databases with a connection URL, and the password in that URL can be handled five different ways. This page maps the full spectrum so you can pick the right posture for your team.

At a glance

Section titled “At a glance”
Mode Where the password lives Sent to the cloud? Best for
Password in the URL On the agent, encrypted at rest No (with the default sync mode) Single machine, simplest setup
--secret-mode runtime Each agent’s environment (PGPASSWORD / MYSQL_PWD) No — a password-less URL skeleton Teams sharing targets via the cloud (the default)
--secret-mode templated Each agent’s environment, referenced explicitly No — an environment placeholder Same as runtime, but the URL documents its own requirement
--secret-mode encrypted Clonit Cloud, encrypted at rest Yes, over TLS Agents that cannot carry the password in their environment
db_auth_mode: rds_iam Nowhere — a short-lived token is minted per connection No (only the non-secret auth posture) RDS / Aurora, strongest posture

Password in the URL

Section titled “Password in the URL”

The default for a local target: the connection URL carries the password (postgres://user:pass@host:5432/dbname). The URL is encrypted at rest on the agent and masked (****) everywhere it is displayed. It never leaves the machine unless you explicitly choose the encrypted sync mode below.

Use it when one machine owns the target and you want zero extra moving parts.

Sharing targets: the cloud sync secret modes

Section titled “Sharing targets: the cloud sync secret modes”

clonit cloud sync uploads target definitions so other agents can resolve them. The non-secret configuration always syncs; how the database password is handled is controlled by --secret-mode:

runtime (default)

Section titled “runtime (default)”

The cloud stores password-less URL skeletons (postgres://user@host:5432/dbname). Each agent that runs the target supplies the password from its own environment — PGPASSWORD for PostgreSQL, MYSQL_PWD for MySQL/MariaDB — at run time. No database password ever leaves the host that ran the sync.

Terminal window
clonit cloud sync                      # runtime is the default

templated

Section titled “templated”

Like runtime, but the requirement is spelled out in the URL itself: the sync replaces the password with an environment placeholder — {{ env "PGPASSWORD" }} (PostgreSQL) or {{ env "MYSQL_PWD" }} (MySQL/MariaDB) — and the retrieving agent expands it from its environment. Again, no password leaves the syncing host.

Terminal window
clonit cloud sync --secret-mode templated

Template expansion is deliberately narrow, so a synced target can never be used to read secrets off the agent that retrieves it:

  • The placeholder is honored only in the password position of the URL — host, port, user, and database name must be literal.
  • Only the password-class variables (PGPASSWORD, MYSQL_PWD) may be referenced — a closed allowlist, not arbitrary environment access.
  • Expansion errors never echo the URL or the secret.

Local target URLs accept the same {{ env "VAR" }} placeholder syntax: it is expanded from the agent’s environment each time the target is used, and the stored URL keeps the placeholder. Because you author these URLs yourself, any environment variable may be referenced. A URL without {{ }} is always used exactly as written.

encrypted

Section titled “encrypted”

The full URL including the password is uploaded over TLS. The cloud encrypts it at rest and returns it (decrypted) only through an audited, access-gated per-target retrieve. Use this only when the retrieving agents cannot carry the password in their environment and you accept the cloud custodying a server-decryptable database password.

Terminal window
clonit cloud sync --secret-mode encrypted

Keyless: RDS IAM authentication

Section titled “Keyless: RDS IAM authentication”

For AWS RDS / Aurora (PostgreSQL, MySQL, MariaDB), db_auth_mode: rds_iam removes the password entirely. The target’s URLs carry no password; the agent uses its own AWS credential chain to mint a short-lived (~15-minute) IAM auth token for each connection, over certificate-verifying TLS pinned to the RDS CA bundle (rds_ca_bundle_path — fail-closed: with no bundle, the connection is refused rather than downgraded).

Terminal window
clonit target add --name prod \
  --src-url 'postgres://appuser@db.abc123.us-east-1.rds.amazonaws.com:5432/app' \
  --db-auth-mode rds_iam

One-time setup: a database-side grant (GRANT rds_iam on PostgreSQL, the AWSAuthenticationPlugin on MySQL/MariaDB) and an rds-db:connect IAM policy on the agent’s role. The full walkthrough lives in Keyless Credentials. The web UI offers a guided setup wizard for these steps — open the target’s page and click Set up keyless access.

New to the idea? Start with the plain-English explainer: How keyless database access works. The Settings → AWS page shows which AWS identity the agent currently resolves to — the identity that mints the tokens — and lets you save the agent-wide AWS profile; the target form shows the same check live for the profile you enter, prefilled from that saved value on new keyless targets.

Because no secret is involved, an rds_iam target syncs to the cloud completely: the auth posture travels with the target, and any connected agent with the right IAM role can run it.

Choosing a mode

Section titled “Choosing a mode”
  • One machine, plain database → password in the URL. Done.
  • Team on Clonit Cloud, agents can hold env vars → runtime (or templated if you want the URL to document the requirement).
  • Agents cannot hold the password → encrypted, accepting cloud custody.
  • Database is RDS / Aurora → rds_iam. No password exists to manage, rotate, or leak — the strongest posture on this page.

Whichever mode you pick, clonit targets verify (or the Verify button on the target’s web UI pages) confirms the credentials actually connect.

See also

Section titled “See also”