---
title: "Rename and/or re-configure a connection."
method: PATCH
path: "/v1/connections/{id}"
tags: ["connections"]
---

# Rename and/or re-configure a connection.

`PATCH /v1/connections/{id}`

## Request

- Base URL: `http://localhost:8080`
- URL: `http://localhost:8080/v1/connections/{id}`
- Auth: one of:
  - API key in cookie `dvt_session`
  - HTTP bearer

Updates the connection's name and/or non-secret `config` under optimistic
concurrency (pass the current `version`). `type` and `authMethod` are immutable —
changing them would orphan stored credentials or grants, so delete and recreate
instead. Credentials are never accepted here. Admin or above.

## Request body

- object
  - `version` integer, required
  - `name` string
  - `config` object: Replaces the stored non-secret config. Omit to leave it unchanged.
  - `catalogSyncEnabled` boolean: Opt this connection in/out of the synced warehouse catalog (A3, DVT-1810). Omit to leave unchanged. Setting false synchronously wipes any persisted catalog for this connection in the same transaction as the version bump.
  - `linkedBaseOptIn` boolean: Opt this connection in/out as an eligible base for `kind='linked'` sheets (DVT-2932, ADR-0078 D1). Omit to leave unchanged. `true` stamps `linkedBaseOptInAt`/`linkedBaseOptInBy` (now / the acting admin), making this connection usable as a linked sheet's `baseConnectionId`. `false` clears both back to null, revoking eligibility for future creates — it does not retroactively affect an already-created linked sheet's base binding. Admin or above, same as every other field on this endpoint.

## Response `200`

The updated connection (version incremented).

- ConnectionEnvelope
  - `data` Connection, required: A warehouse connection's non-secret metadata (ADR-0012). Secret material — credential ciphertext, the SecretRef pointer, per-user OAuth grants — is never part of this object; `secretConfigured` reports only *whether* a service credential has been stored, never anything about it.
    - `id` string, required: The connection's UUID — except for a built-in read-only connection (`readOnly: true`), which uses a reserved slug instead: today only `demo-postgres`, the shared sample database injected into the list for sandbox and gallery-plan orgs. Built-in connections are never persisted, so the `/v1/connections/{id}` paths (which take a UUID) do not address them.
    - `name` string, required: Connection slug — unique within the org; the `sourceId` alias used in specs.
    - `type` 'snowflake' | 'bigquery' | 'databricks_sql' | 'redshift' | 'postgres' | 'mysql' | 'sqlite' | 'parquet_s3' | 'csv' | 'google_sheets', required
    - `authMethod` 'service_secret' | 'service_keypair' | 'oauth_passthrough' | 'cloud_iam' | 'spcs_token', required: Authentication method for this connection. This enum is a deliberate **subset** of the internal `auth_method` column: `platform_managed` (used internally for CSV-uploaded Parquet sources, DVT-753) is intentionally absent. Internal upload sources are created via `POST /v1/uploads` and are never returned by the connections API. `spcs_token` (secretless SPCS-injected OAuth token, DVT-1300) only appears on deployments running as a Snowflake Native App (`DVT_MODE=snowflake`); it is rejected as an unsupported `authMethod` on create in any other mode.
    - `kind` 'pushdown' | 'writeback': Connection kind (ADR-0031 D2). `pushdown` (default) is the read-only data plane (ADR-0011). `writeback` opts the connection into the write path — its credential must carry a role scoped to the `dvt_writeback` namespace only (least-privilege). Immutable after creation; delete and recreate to change kind.
    - `config` object, required: Non-secret connection parameters (account, warehouse, database, schema, project, region). Always an object, never null: returned as an empty object (`{}`) for a caller who lacks `connection:manage` (see `GET /v1/connections`).
    - `secretConfigured` boolean, required: Whether a service credential has been stored (service_* only). Always false for oauth_passthrough/cloud_iam, whose secrets are per-user or workload-derived.
    - `ready` boolean, required: Server-computed readiness (DVT-1748): true when the connection can be queried as-is, with no further credential setup. Secretless auth methods (`spcs_token`, `platform_managed`, `cloud_iam`) are always ready — they have nothing to configure, so deriving readiness client-side from `secretConfigured`/`lastTestedAt` misreports them as unconfigured. Credential-bearing methods (`service_*`, `oauth_passthrough`) are ready exactly when their secret is stored. Clients should key connected/needs-setup UI on this field, never re-derive it.
    - `lastTestedAt` string, date-time, nullable: Timestamp of the most recent successful connection test.
    - `lastTestError` string, nullable: Error from the most recent failed test; null when the last test succeeded. Replaced by a generic message for a caller who lacks `connection:manage` (see `GET /v1/connections`).
    - `version` integer, required: Optimistic-concurrency version. Pass this back on PATCH.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `readOnly` boolean: Synthetic read-only sample card (sandbox demo-postgres, DVT-802). Omitted on real connections (omitempty). When true, all mutating controls must be hidden; write paths remain 403 (ADR-0042 D6).
    - `catalogSyncEnabled` boolean: Whether this connection's warehouse catalog (databases/schemas/tables/ columns) is synced into dvt and searchable via `GET /v1/connections/{id}/catalog` (A3, DVT-1810). Opt-in, default false. Toggling this false→true via `PATCH` enrolls the connection in the next background sync pass; true→false synchronously wipes any persisted catalog for this connection.
    - `catalogSyncedAt` string, date-time, nullable: Timestamp of the most recent successful catalog sync; null if never synced.
    - `catalogSyncRequestedAt` string, date-time, nullable: Set by `POST /v1/connections/{id}/catalog/sync` to request an out-of-cycle sync; cleared implicitly once `catalogSyncedAt` passes it.
    - `catalogSyncError` string, nullable: Sanitized error from the most recent failed sync attempt; null when the last sync succeeded (or none has run). Replaced by a generic message for a caller who lacks `connection:manage` (see `GET /v1/connections`).
    - `roleMapped` boolean: True when the connection has a role-mapping policy configured (DVT-145); survives config redaction, so a caller who lacks `connection:manage` can still see that queries against this connection run as a per-user mapped warehouse role even though `config.roleMapping` itself is not visible to them.
  - `meta` Meta, required: Response metadata.
    - `requestId` string, required: Correlates with the X-Request-Id header.
    - `total` integer: Item count, present on collection responses.
    - `nextCursor` string, nullable: Opaque keyset-pagination cursor, present on paginated responses (e.g. GET /v1/dashboards) when more rows exist beyond this page. Pass it back as the `cursor` query param to fetch the next page; absent or null on the last page.
    - `roleResolveDegraded` boolean: Snowflake mode only (DVT-2260), on GET /v1/dashboards: present and true when the caller's live Snowflake role resolution failed or was unavailable — role-shared dashboards may be missing from this page. Omitted (not merely false) whenever resolution succeeded or the role-share arm does not apply (off snowflake mode, an org admin/owner, or off the ingress listener).

## Other responses

- `400`: Malformed request.
- `401`: Missing, invalid, or expired session.
- `403`: The caller's role does not permit this action.
- `404`: Resource does not exist.
- `409`: Stale version (version-conflict) or a name collision (name-conflict).

---

[API](https://skmtc.dev/dvt/apis/dvt-rest-api.md) · [All operations](https://skmtc.dev/dvt/apis/dvt-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dvt/apis/dvt-rest-api/revisions/00016f504165?raw)