ALTER CREDENTIAL STORAGE

Modifies one or more attributes of an existing credential-storage backend: description, config options, active state, or name.

Category: configurationPrivilege: adminDeltaForge extension

Syntax

ALTER CREDENTIAL STORAGE [IF EXISTS] <name>
  { SET OPTIONS (<key> = '<value>', ...)
  | SET DESCRIPTION '<text>'
  | ACTIVE
  | INACTIVE
  | RENAME TO <new_name>
  } ...

Description

## Overview ALTER CREDENTIAL STORAGE applies one or more updates to an existing backend row in vault_backends. Actions are applied in the order written and the update is atomic from the caller's perspective: either all actions succeed or the row is unchanged. ## Behavior - SET OPTIONS replaces the config_json map entirely rather than merging. To change a single key, re-supply the complete OPTIONS list so the other keys are preserved. - SET DESCRIPTION updates a pure metadata field; no backend probe is triggered. - ACTIVE and INACTIVE toggle vault_backends.is_active. INACTIVE prevents new CREATE VAULT statements from selecting this backend as their IN CREDENTIAL STORAGE target but does not break existing vault entries whose material is already resolved through it. - RENAME TO updates display_name. The backend id is immutable, so vault entries referencing this backend via storage_backend_id continue to resolve correctly. - The OS Keychain singleton (display_name 'OS Keychain') can be altered for metadata fields (SET DESCRIPTION) but RENAME TO and INACTIVE are strongly discouraged because the default keychain is a load-bearing fixture referenced by many subsystems. - IF EXISTS converts a missing-backend error into a clean no-op so ALTER statements are safe to include in migration or cleanup scripts. ## Access Control Requires the admin role. The Control Plane enforces vault:write on the underlying PUT /vault/backends/{id} route. ## Compatibility ALTER CREDENTIAL STORAGE is a DeltaForge extension. No standard SQL equivalent exists.

Parameters

Name	Type	Description
`name`		Specifies the current display_name of the backend to modify. Resolved server-side to the backend id before the update is applied.
`if_exists`		When true, returns successfully with a 'does not exist' message if the backend is not found. Without IF EXISTS, a missing backend raises an error.
`actions`		Specifies one or more actions to apply. Multiple actions are applied in order within a single transactional update: SET OPTIONS (full map replacement), SET DESCRIPTION (metadata), ACTIVE/INACTIVE (state toggle), RENAME TO (display_name change).

Examples

-- Change the description
ALTER CREDENTIAL STORAGE prod_azure_kv SET DESCRIPTION 'Primary production Azure Key Vault';

-- Rotate to a new region (replaces the entire OPTIONS map)
ALTER CREDENTIAL STORAGE prod_aws_sm
  SET OPTIONS (auth_method = 'iam_role', region = 'eu-west-1', secrets_manager_prefix = 'delta-forge');

-- Soft-disable a backend so new vault entries cannot target it
ALTER CREDENTIAL STORAGE staging_azure INACTIVE;

-- Re-enable an INACTIVE backend
ALTER CREDENTIAL STORAGE staging_azure ACTIVE;

-- Rename a backend (catalog graph edges follow the id, not the name, so dependent VAULT entries are unaffected)
ALTER CREDENTIAL STORAGE prod_azure_kv RENAME TO prod_azure_kv_v2;

-- Chain multiple actions in a single statement
ALTER CREDENTIAL STORAGE IF EXISTS prod_aws_sm
  SET DESCRIPTION 'Rotated to eu-west-1 on 2026-05-01'
  SET OPTIONS (auth_method = 'iam_role', region = 'eu-west-1')
  RENAME TO prod_aws_sm_eu;

Pitfalls

SET OPTIONS replaces the config map entirely. Omitting a previously-configured key removes it, which can break authentication. Always re-supply the complete intended OPTIONS when changing one value.
Renaming a backend also updates the display_name the IN CREDENTIAL STORAGE clause must use in any new CREATE VAULT statements. Existing vault entries are unaffected because they reference the immutable backend id, but SQL scripts that hard-code the old name need updating.
Setting the OS Keychain singleton to INACTIVE soft-disables the default destination for new encryption keys. Vault entries created without an explicit IN CREDENTIAL STORAGE clause default to the OS Keychain; if it is INACTIVE those CREATE VAULT statements fail. Avoid altering the OS Keychain backend state.
The HTTP adapter resolves the name to an id by calling GET /vault/backends and scanning display_name. If two backends somehow share a name (enforced unique by DB constraint, but bypassable via direct catalog writes) the first match wins.