TEST CONNECTION

Probes connectivity to the external system referenced by a connection, returning success/latency/error and server version where available.

Category: configurationPrivilege: adminDeltaForge extension

Syntax

TEST CONNECTION <name>

Description

## Overview TEST CONNECTION opens a live connection to the external system using the registered options and credentials, runs a minimal probe (SELECT 1 for databases, HEAD or list for object stores, a single GET for REST APIs), measures latency, captures any server version string returned by the probe, and closes the connection. The results are stored on external_connections.last_tested_at, last_test_status, last_test_latency_ms, last_test_error, and server_version so the GUI and SHOW output can surface them. ## Behavior ### Databases Opens a connection via the configured driver, executes SELECT 1, and reads the server version from the driver's handshake where available. Credentials are resolved from the linked CREDENTIAL vault entry at probe time (rotations in the vault are picked up). ### Object stores (S3, GCS, ADLS, local) Issues a lightweight list or head call against the configured bucket/container/path using the CREDENTIAL STORAGE backend for auth. ### Git hosts (GitHub, GitLab, Bitbucket, Azure DevOps) Issues an authenticated GET against the api_url base path. Validates the personal access token has at least read permission on the organization. ### SFTP Opens an SSH connection and performs a protocol-level SFTP_INIT exchange. Does not enumerate the configured path by default. ### REST API Issues the configured HTTP method against endpoint with the configured auth and asserts the response code matches expected_status. ## Output Returns a status message (PASSED or FAILED), the latency in milliseconds, the server version where available, and an error message when failed. The same fields are persisted on the connection row so SHOW CONNECTIONS can surface the last test status without re-probing. ## Access Control Requires the admin role. The Control Plane enforces connections:read on POST /connections/{name}/test. ## Compatibility DeltaForge extension.

Parameters

Name	Type	Description
`name`		Specifies the name of the connection to probe.

Examples

-- Probe a database connection
TEST CONNECTION prod_pg;

-- Probe an object-store connection
TEST CONNECTION raw_data_s3;

-- Use before CREATE EXTERNAL TABLE to verify auth is correctly configured
TEST CONNECTION crm_api;

Pitfalls

TEST does not retry. Transient network failures surface as FAILED even when the system is normally reachable. Re-run to confirm.
TEST persists the result to last_test_* columns. Frequent testing from automation appears as continuous probe events in the connection's audit history; rate-limit if this is undesirable.
TEST succeeds when a minimal probe works. It does not exercise the specific schemas, tables, or buckets a CREATE EXTERNAL TABLE would touch; runtime auth or authorization errors can still occur on real queries even when TEST passes.
Probes for object-store connections may perform a list operation that counts against the backend's list-request quota. Avoid looping TEST against production buckets.