ALTER CONNECTION

Modifies an existing connection: replaces options, swaps credential references, or renames.

Category: configurationPrivilege: adminDeltaForge extension

Syntax

ALTER CONNECTION [IF EXISTS] <name>
  { SET OPTIONS (<key> = '<value>', ...)
  | SET CREDENTIAL = <vault_entry_name>
  | SET CREDENTIAL STORAGE = <backend_name>
  | RENAME TO <new_name>
  } ...

Description

## Overview ALTER CONNECTION applies updates to an existing external_connections row. Actions are applied in order and the update is atomic from the caller's perspective. ## Actions ### SET OPTIONS (...) Replaces the entire options map. To change one setting re-supply the complete list; any previously-present key not in the new list is removed. ### SET CREDENTIAL = <vault_entry_name> Resolves the name to a vault_entries.id and stores that id as credential_id on the connection. Runtime resolves the secret fresh from the backing credential store on every connect so rotations take effect without further ALTER calls. ### SET CREDENTIAL STORAGE = <backend_name> Resolves the name to a vault_backends.id and stores that id as credential_storage_id. Used by object-store connections that authenticate via the cloud backend (IAM role, managed identity, ADC) rather than a per-entry vault credential. ### RENAME TO <new_name> Changes display_name. The connection id is immutable; external-table registrations referencing this connection by id continue to resolve. SQL scripts hard-coding the old name need updating. ## Behavior - The HTTP adapter resolves the connection name to the id via GET /connections/{name}, then calls PUT /connections/{name} with the update body. - ALTER does not probe the connection. Use TEST CONNECTION afterward. - IF EXISTS makes a missing connection a clean no-op. ## Access Control Requires the admin role. The Control Plane enforces connections:write on PUT /connections/{name}. ## Compatibility DeltaForge extension.

Parameters

Name	Type	Description
`name`		Specifies the current name of the connection.
`if_exists`		When true, a missing connection is a clean no-op.
`actions`		Specifies one or more actions. SET OPTIONS replaces the options map entirely. SET CREDENTIAL and SET CREDENTIAL STORAGE swap auth references. RENAME TO changes the connection name.

Examples

-- Change host and enable SSL (replaces options map)
ALTER CONNECTION prod_pg
  SET OPTIONS (host = 'new-db.example.com', port = '5432', database = 'app', ssl_enabled = 'true');

-- Swap to a rotated credential
ALTER CONNECTION prod_pg SET CREDENTIAL = prod_pg_password_v2;

-- Swap the cloud-native auth backend
ALTER CONNECTION raw_data_s3 SET CREDENTIAL STORAGE = prod_aws_sm_eu;

-- Rename a connection
ALTER CONNECTION old_name RENAME TO new_name;

-- Chain multiple actions
ALTER CONNECTION IF EXISTS prod_pg
  SET OPTIONS (host = 'new-db.example.com', port = '5432', database = 'app', ssl_enabled = 'true')
  SET CREDENTIAL = prod_pg_password_v2
  RENAME TO prod_pg_v2;

Pitfalls

SET OPTIONS replaces the options map entirely. Omitting a previously-present key removes it. Always re-supply the full intended options when changing one value.
SET CREDENTIAL does not verify that the target vault entry exists at ALTER time; the resolution is done by the Control Plane but a typo in the name can silently bind an invalid reference. Run TEST CONNECTION after the SET CREDENTIAL to confirm the new binding works.
RENAME TO changes display_name but not the connection id. External-table registrations continue to resolve because they reference the id, but SQL scripts that hard-code the old name need updating.
Database connections should use SET CREDENTIAL; object-store connections should use SET CREDENTIAL STORAGE. Mixing (for example SET CREDENTIAL STORAGE on a postgresql connection) is accepted at ALTER time but ignored at runtime.