Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Bucket B: Database migration

Bucket B handles database credentials stored in a cloud secret store. The KnoxCall agent binds a local TCP listener on 127.0.0.1. Your application connects to 127.0.0.1:{agent_port} — the agent authenticates to the real database using KnoxCall-managed credentials, then pipes the connection through bidirectionally. The only application change: update the database connection string. No credential rotation, no SDK changes, no code changes beyond the host and port.

​
How it works

Application
  ↓  TCP connection to 127.0.0.1:5432 (agent listener)
KnoxCall agent
  ↓  Validates connecting process UID (SO_PEERCRED)
  ↓  Fetches DB credentials from KnoxCall
  ↓  Opens TLS connection to upstream DB (db.prod.internal:5432)
  ↓  Performs authentication on behalf of the application
  ↓  Pipes post-auth bytes bidirectionally
Upstream database ← TLS ← Agent ← plaintext ← Application
The application never sees the database password. The agent handles the entire authentication handshake.
The agent only ever binds 127.0.0.1, never 0.0.0.0. If you configure a proxy route with a non-loopback bind address, the agent refuses to start. This is enforced — not advisory.

​
Supported protocols

ProtocolDefault port rangeNotes
PostgreSQL5432–5440Full wire protocol; ScramSHA-256 upstream auth
MySQL3306–3316Full wire protocol; CLIENT_PLUGIN_AUTH
MongoDB27017–27027OP_MSG with SCRAM auth
Redis6379–6389RESP protocol; AUTH command injection
Port ranges are configurable per route. Each database gets its own port on the agent.

​
Application change required

Update the connection string in your application’s configuration: 
- DATABASE_URL=postgresql://db.prod.internal:5432/mydb
+ DATABASE_URL=postgresql://127.0.0.1:5432/mydb
No username or password needed in the connection string — the agent provides them. Most database drivers support passwordless connections when the server doesn’t challenge (the agent handles the challenge upstream).
For connection poolers like PgBouncer or ProxySQL running in front of the database, update the pooler’s upstream to 127.0.0.1:{agent_port} instead. The application points at the pooler as usual.

​
Setting up a DB proxy route

​
Via admin UI

  1. Go to Infrastructure → Secret Store Migrations
  2. Open the migration → click the DB Proxy Routes tab
  3. Click Add route
  4. Configure:
    • Protocol: PostgreSQL / MySQL / MongoDB / Redis
    • Local port: the port the agent will bind on 127.0.0.1
    • Upstream host: your real database hostname
    • Upstream port: real database port
    • Credentials secret: the KnoxCall secret holding the database username/password
    • UID allowlist (optional): Linux UIDs permitted to connect to this proxy port

​
Via API

curl -X POST https://api.knoxcall.com/admin/migrations/mgr_01abc.../db-proxy-routes \
  -H "Authorization: Bearer $KC_ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "postgres",
    "local_port": 5432,
    "upstream_host": "db.prod.internal",
    "upstream_port": 5432,
    "committed_secret_id": "sec_01abc...",
    "allowed_uids": [1000, 1001]
  }'

​
Security model

​
Peer attestation

The agent validates the UID of every connecting process via SO_PEERCRED on Linux (or named-pipe ACL on Windows). If the connecting process UID is not in the allowlist, the connection is refused before any data is exchanged.

​
TLS to upstream

The agent always opens TLS to the upstream database — even when the application connects to the agent over unencrypted localhost. The agent strictly validates the upstream certificate by default. For development environments where the DB has a self-signed cert, TLS verification can be relaxed per route (not recommended for production).

​
mTLS

If the upstream database requires client certificates for mutual TLS, store the client certificate as a KnoxCall certificate secret and reference it in the route config. The agent presents the certificate automatically during the TLS handshake.

​
Verification and cutover

Once your application is routing through the agent proxy:
  1. The migration verification dashboard tracks probe results showing the old-provider endpoint becoming unreachable
  2. When all probes pass and consumers are confirmed, click Confirm migration complete
  3. The “safe to delete cloud secrets” banner appears
At that point, the database credentials in the cloud secret store can be rotated or deleted.

​
Cancelling a Bucket B migration

Cancelling removes all DB proxy routes. Applications that were connecting through the agent will lose database connectivity immediately. Only cancel if you’re reverting the migration entirely. 
curl -X POST https://api.knoxcall.com/admin/migrations/mgr_01abc.../cancel \
  -H "Authorization: Bearer $KC_ADMIN_JWT"

Agent database proxy protocols

Wire-level details: ScramSHA-256, SCRAM, AUTH injection

Migration verification

Probe results and safe-to-delete confirmation

Bucket A: HTTPS API migration

For HTTP-based secret store consumers

Migrations API reference

DB proxy route endpoints