TEST CREDENTIAL STORAGE

Runs the reachability probe on a credential-storage backend (the same probe executed by the GUI 'Test' button).

Category: configurationPrivilege: adminDeltaForge extension

Syntax

TEST CREDENTIAL STORAGE [IF EXISTS] <name>

Description

## Overview TEST CREDENTIAL STORAGE exercises the live credentials of a backend and returns a success or failure message together with a per-step trace log. The probe is non-destructive: the backend is left in the state it started in. ## Behavior ### OS Keychain Performs a write-read-delete cycle on a scratch key name (profile test::probe). Any step that fails yields a FAILED result with the backend's error message in the entries log. ### Azure Key Vault Performs a live token acquisition followed by a vault endpoint probe (listSecrets with page size 1). Validates that the auth_method configured at CREATE time still works and that the target key vault is reachable from the Control Plane host. ### AWS Secrets Manager Attempts a ListSecrets call with MaxResults = 1 scoped to the configured secrets_manager_prefix. Validates both IAM authorization and network reachability to the Secrets Manager endpoint in the configured region. ### GCP Secret Manager Attempts a SecretManagerService.ListSecrets call scoped to the configured project_id. Validates auth (ADC or service-account JSON) and network reachability. ## Output The result is a status message followed by a trace log. Each log entry has a level (info, success, warning, error) and a short message. The GUI Test button renders this as a table; the SQL path returns it as a multi-line text block. ## Access Control Requires the admin role. The Control Plane enforces vault:read on POST /vault/backends/{id}/test. ## Compatibility DeltaForge extension. No standard SQL equivalent.

Parameters

Name	Type	Description
`name`		Specifies the display_name of the backend to probe.
`if_exists`		When true, returns successfully without running the probe if the backend is missing. Without IF EXISTS, a missing backend raises an error.

Examples

-- Probe the default OS Keychain (write/read/delete round-trip)
TEST CREDENTIAL STORAGE 'OS Keychain';

-- Probe a cloud backend after ALTER changes
TEST CREDENTIAL STORAGE prod_azure_kv;

-- Safe to include in CI bootstrap scripts
TEST CREDENTIAL STORAGE IF EXISTS optional_backend;

Pitfalls

Test probes consume a small quota of backend-specific rate limit budget. Do not loop TEST CREDENTIAL STORAGE in tight loops against managed cloud backends; rate limits can trip and cause false negatives.
A successful TEST only proves reachability at probe time. Subsequent calls during query execution can still fail if cloud credentials expire, IAM policies change, or network routing breaks.
TEST does not verify that the authenticated principal has write access to the backend's namespace. It only checks list-style read operations. CREATE VAULT attempts that store material can still fail with permission errors even when TEST passes.
The probe runs synchronously in the executor and can block for up to the backend's timeout (default 30 seconds). Do not embed TEST in latency-sensitive scripts.