ALTER VAULT / ALTER CREDENTIAL

Modifies a vault entry: rotates encryption-key material, replaces a credential secret, updates metadata, or renames. VAULT and CREDENTIAL are keyword aliases.

Category: configurationPrivilege: adminDeltaForge extension

Syntax

ALTER { VAULT | CREDENTIAL } [IF EXISTS] <name>
  { ROTATE
  | SET SECRET '<value>'
  | SET DESCRIPTION '<text>'
  | SET EXPIRES '<timestamp>'
  | RENAME TO <new_name>
  } ...

Description

## Overview ALTER VAULT (aliased as ALTER CREDENTIAL) applies updates to a single vault entry. The action list is applied in order and the update is atomic from the caller's perspective. Rotation and secret replacement both increment current_version and stamp rotated_at with the current timestamp. ## Actions ### ROTATE Valid only for TYPE = ENCRYPTION_KEY entries. Generates fresh random material via the OS CSPRNG, writes it to the credential backend under profile vault::<entry_id> (keys 'key' and 'salt'), increments current_version, and stamps rotated_at. The previous material is overwritten and is not recoverable. ### SET SECRET '<value>' Valid only for TYPE = CREDENTIAL entries. Replaces the stored secret_value in the credential backend, increments current_version, and stamps rotated_at. The previous secret is not retained. ### SET DESCRIPTION '<text>' Pure metadata update. Does not touch secret material, version, or rotated_at. ### SET EXPIRES '<timestamp>' Pure metadata update. Stores an ISO 8601 timestamp in vault_entries.expires_at. The runtime does not reject reads based on this value; it is advisory for operators who implement rotation policies. ### RENAME TO <new_name> Changes display_name. The entry id is immutable, so upstream references via storage_backend_id and downstream references via credential_id continue to resolve. Connections whose SQL declarations embed the old name via CREDENTIAL = <old_name> need manual ALTER CONNECTION updates. ## Behavior - The HTTP adapter resolves the name to an entry id via GET /vault/entries, then applies actions. ROTATE uses POST /vault/entries/{id}/rotate; all other actions use PUT /vault/entries/{id}. - The SQL executor moves the new secret value out of its redacting SecretLiteral wrapper exactly once and transmits it over the authenticated HTTPS connection. The value is never written to traces, formatted SQL, or AST-dump output. - ALTER does not validate the replacement value. An empty or short SECRET is accepted; downstream consumers must enforce their own minimum-length and format requirements. ## Access Control Requires the admin role. The Control Plane enforces vault:write on the underlying rotate or update route. ## Compatibility DeltaForge extension. No standard SQL equivalent.

Parameters

Name	Type	Description
`name`		Specifies the current display_name of the vault entry.
`if_exists`		When true, makes a missing entry a clean no-op. Without IF EXISTS, a missing entry raises an error.
`actions`		Specifies one or more actions. ROTATE regenerates the encryption key material and bumps current_version; valid only for ENCRYPTION_KEY entries. SET SECRET '<value>' replaces the stored secret for CREDENTIAL entries and bumps current_version. SET DESCRIPTION and SET EXPIRES are pure metadata updates. RENAME TO changes display_name (the entry id is immutable).

Examples

-- Rotate an encryption key (new random bytes, version bump)
ALTER VAULT pii_key ROTATE;

-- Replace a stored API token
ALTER CREDENTIAL stripe_api_token SET SECRET 'sk_live_NEWVALUE';

-- Update metadata without touching material
ALTER VAULT pii_key SET DESCRIPTION 'Rotated on 2026-05-01 per quarterly policy';

-- Adjust advisory expiry
ALTER VAULT pii_key SET EXPIRES '2027-01-01T00:00:00Z';

-- Rename an entry (dependent CONNECTION credential_ref values need manual update)
ALTER VAULT old_name RENAME TO new_name;

-- Chain multiple actions atomically
ALTER CREDENTIAL IF EXISTS github_pat
  SET SECRET 'ghp_NEWVALUE'
  SET DESCRIPTION 'Rotated after org credential leak'
  SET EXPIRES '2026-08-01T00:00:00Z';

Pitfalls

ROTATE on an encryption key is destructive. The previous material is overwritten and not recoverable. Any data encrypted or pseudonymised with the old key becomes unreadable unless the workflow explicitly preserved the old material elsewhere. Plan key rotation as part of a re-encrypt or re-pseudonymise workflow.
SET SECRET replaces the stored secret with no retention. Callers that want to keep the old value for a rollback window must copy it elsewhere first. There is no SQL path to read the old value because secrets are not retrievable through SQL.
RENAME TO changes display_name but not the entry id. Any CONNECTION declarations that embed the old name via CREDENTIAL = <old_name> still resolve correctly at runtime (because credential_id is stored on external_connections, not the name), but operator-visible SQL scripts need the name updated to remain coherent.
ROTATE on a TYPE = CREDENTIAL entry is rejected server-side: rotation is an encryption-key operation. Use SET SECRET to replace a credential value.
SET SECRET on a TYPE = ENCRYPTION_KEY entry is rejected server-side: encryption keys are rotated, not re-set. Use ROTATE instead.
SET EXPIRES is advisory. The runtime does not enforce expiry on read; expired entries continue to resolve. Build expiry enforcement in your own workflow by querying SHOW VAULTS and rotating or dropping entries whose expires_at has passed.