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

Protocol	Default port range	Notes
PostgreSQL	5432–5440	Full wire protocol; ScramSHA-256 upstream auth
MySQL	3306–3316	Full wire protocol; CLIENT_PLUGIN_AUTH
MongoDB	27017–27027	OP_MSG with SCRAM auth
Redis	6379–6389	RESP 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

Go to Infrastructure → Secret Store Migrations
Open the migration → click the DB Proxy Routes tab
Click Add route
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:

The migration verification dashboard tracks probe results showing the old-provider endpoint becoming unreachable
When all probes pass and consumers are confirmed, click Confirm migration complete
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

Bucket A: HTTPS API migration

Agent database proxy protocols

​Bucket B: Database migration

​How it works

​Supported protocols

​Application change required

​Setting up a DB proxy route

​Via admin UI

​Via API

​Security model

​Peer attestation

​TLS to upstream

​mTLS

​Verification and cutover

​Cancelling a Bucket B migration

Agent database proxy protocols

Migration verification

Bucket A: HTTPS API migration

Migrations API reference

Bucket B: Database migration

How it works

Supported protocols

Application change required

Setting up a DB proxy route

Via admin UI

Via API

Security model

Peer attestation

TLS to upstream

mTLS

Verification and cutover

Cancelling a Bucket B migration