Skip to main content

​
DB Proxy Routes

DB proxy routes are wire-protocol tunnels that let agents connect to a migrated database through KnoxCall using a localhost:<port> listener. They can be created for any migration the reviewer owns — the committed_secret_id must reference an existing tenant secret, but no particular migration status is required. Routes are removed only via DELETE /admin/migrations/:id/db-proxy-routes/:routeId; cancelling the migration does not delete them. The write endpoints (POST and DELETE) require migration_reviewer permission + 5-minute step-up. The GET (list) endpoint requires only tenant access to the migration — no migration_reviewer role or step-up.

​
POST /admin/migrations/:id/db-proxy-routes

Create a new wire-protocol proxy route for a migration. Auth: migration_reviewer + 5-minute step-up

​
Request body

FieldRequiredDescription
protocol✅Wire protocol: postgres, mysql, mongodb, redis, sqlserver
upstream_host✅Hostname or IP of the real database
upstream_port✅Port of the real database
committed_secret_id✅ID of the committed KnoxCall secret holding the database credentials
credential_username✅Database username to authenticate with. Required for every protocol except redis
local_portconditionalAgent-local port the tunnel listens on (must be unique per agent). Required when bind_mode is tcp; must be 1024–65535 (privileged ports under 1024 are not supported)
bind_mode—How the agent listener is exposed: tcp (default), unix, or pipe
unix_socket_pathconditionalAbsolute path (must start with /) for the listener. Required when bind_mode is unix
pipe_nameconditionalSimple named-pipe name (no backslashes) for the listener. Required when bind_mode is pipe
upstream_database—Database name to connect to
upstream_username—Stored upstream username for display/reference
tls_mode—prefer (default), require, disable
agent_id—Scope the tunnel to a specific agent UUID; omit for any agent
allowed_uids—Array of Unix UIDs allowed to use the tunnel
secret_migration_item_id—Associate the route with a specific migration item
Returns 409 if local_port is already in use for the same agent.

​
Response

{ "id": "route-uuid" }
Status 201 Created.

​
GET /admin/migrations/:id/db-proxy-routes

List all proxy routes for a migration. Auth: tenant access to the migration (no migration_reviewer role or step-up required)

​
Response

{
  "routes": [
    {
      "id": "route-uuid",
      "protocol": "postgres",
      "upstream_host": "prod-db.internal",
      "upstream_port": 5432,
      "upstream_database": "myapp",
      "upstream_username": "readonly",
      "tls_mode": "prefer",
      "local_port": 15432,
      "agent_id": null,
      "allowed_uids": [],
      "committed_secret_id": "secret-uuid",
      "secret_migration_item_id": "item-uuid",
      "enabled": true,
      "created_at": "2026-05-25T10:00:00Z",
      "updated_at": "2026-05-25T10:00:00Z"
    }
  ]
}

​
DELETE /admin/migrations/:id/db-proxy-routes/:routeId

Remove a proxy route. The agent tunnel is torn down immediately. Auth: migration_reviewer + 5-minute step-up

​
Response

{ "id": "route-uuid", "deleted": true }
Returns 404 if the route is not found for this migration and tenant.