> ## 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
> Migrate database credentials from cloud secret stores via the KnoxCall agent's localhost TCP proxy. Change one connection string, nothing else.
# 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
```text theme={"dark"}
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:
```diff theme={"dark"}
- 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
```bash theme={"dark"}
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](/essentials/migrations/verification) 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.
```bash theme={"dark"}
curl -X POST https://api.knoxcall.com/admin/migrations/mgr_01abc.../cancel \
-H "Authorization: Bearer $KC_ADMIN_JWT"
```
Wire-level details: ScramSHA-256, SCRAM, AUTH injection
Probe results and safe-to-delete confirmation
For HTTP-based secret store consumers
DB proxy route endpoints