Database Connection Error Recovery Prompt

This prompt is designed for backend developers, SREs, and automated runbook systems that need to diagnose and recover from database connection failures. The primary job-to-be-done is single-step recovery: you provide the original connection string, the exact client error message, and relevant network context, and the prompt produces a corrected configuration string, a diagnostic checklist, or a specific remediation step. It is not designed for multi-step agentic debugging sessions where the model must iteratively probe the network or interact with a live database server.

Use this prompt when an application logs a connection error and you can capture the full error text, the connection string with sensitive credentials redacted, and any relevant environment details such as the database driver version, network topology (e.g., VPC, proxy, or direct connection), and whether TLS is required. The prompt assumes you can provide these three inputs: [CONNECTION_STRING], [CLIENT_ERROR_MESSAGE], and [NETWORK_CONTEXT]. It works best for common failure modes like timeouts, TLS handshake failures, authentication denials, hostname resolution errors, and connection pool exhaustion. The output is a corrected configuration or a prioritized checklist, not a general troubleshooting guide.

Do not use this prompt for SQL syntax errors, query optimization, schema migration failures, or ORM-level exceptions. Those failures require separate playbooks because the error signatures and recovery strategies are fundamentally different. Also avoid this prompt when the connection failure is intermittent and requires a long-running diagnostic session with packet captures or live server log correlation. In high-security environments, ensure that any connection string you paste into the prompt has credentials replaced with placeholder tokens before submission. The harness should validate the corrected connection string against a test connection before applying it to production.

The prompt below is designed to be pasted directly into your AI harness. It expects a structured set of inputs—the original connection string, the exact client error, and relevant network context—and produces a structured output that your application can parse. Replace every square-bracket placeholder with real data before sending. The prompt instructs the model to reason step-by-step, cross-reference the error against common failure modes, and output either a corrected connection string or a diagnostic checklist when the fix is not a single configuration change.

textCopy
You are a database connectivity diagnostic assistant. Your task is to analyze a connection failure, identify the root cause, and produce a corrected configuration or a prioritized diagnostic checklist.

## INPUT
- Connection String: [CONNECTION_STRING]
- Client Error Message: [ERROR_MESSAGE]
- Network Context: [NETWORK_CONTEXT]
- Database Type: [DB_TYPE]
- Client Library and Version: [CLIENT_LIBRARY]
- Environment: [ENVIRONMENT]

## CONSTRAINTS
- Never output a connection string that includes plaintext credentials. If credentials are required, use placeholder tokens like `<PASSWORD>`.
- If the error indicates a TLS or certificate issue, include a verification step in the checklist.
- If the error indicates an authentication failure, do not guess credentials. Recommend a credential validation step.
- If the error is a timeout, analyze whether it is a network reachability issue, a firewall rule, or a server-side resource problem.
- If the error message is ambiguous or insufficient, output a diagnostic checklist instead of a single fix.
- Prefer solutions that do not require disabling security features.

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "diagnosis": "string summarizing the likely root cause",
  "confidence": "high|medium|low",
  "corrected_connection_string": "string or null if a single fix is not appropriate",
  "diagnostic_checklist": [
    {
      "step": "string describing the diagnostic action",
      "category": "network|authentication|tls|dns|server_config|client_config|timeout|other",
      "expected_result": "string describing what success looks like"
    }
  ],
  "requires_human_review": true or false
}

## INSTRUCTIONS
1. Parse the connection string and identify its components (host, port, database name, parameters).
2. Map the error message to known failure modes for the specified database type.
3. Cross-reference the error with the network context to eliminate or confirm network-layer issues.
4. If a single, high-confidence fix exists, produce the corrected connection string.
5. If multiple causes are possible or the error is ambiguous, produce a prioritized diagnostic checklist.
6. Set `requires_human_review` to true if the fix involves changing authentication mode, disabling TLS, or modifying server-side settings that may have broader impact.

To adapt this prompt for your environment, replace the placeholders with real values from your application's error-handling path. The NETWORK_CONTEXT field should include information like whether the client can resolve the hostname, whether the port is reachable, and any relevant firewall or VPC configuration. The OUTPUT_SCHEMA is designed to be machine-readable; your harness should parse the JSON response and branch on the confidence field and the presence of a corrected_connection_string. For high-risk environments, always honor the requires_human_review flag and route the output to an approval queue before applying any configuration change.

This prompt is designed to be called by an application harness after a database connection attempt fails. The harness is responsible for capturing the original connection string (with secrets redacted), the full client error message, and relevant network context before invoking the model. The prompt should not be exposed directly to end users; it is an internal recovery step in a backend service, a runbook automation, or a developer CLI tool. The primary job of the harness is to ensure the model receives a clean, structured input and that its output is validated before any configuration change is applied.

The implementation flow should follow a strict sequence: Capture → Redact → Prompt → Validate → Apply or Escalate. First, catch the connection exception and extract the error code, message, and stack trace. Redact the password and any secrets from the connection string, replacing them with a [REDACTED] placeholder. Populate the prompt's [CONNECTION_STRING], [CLIENT_ERROR], and [NETWORK_CONTEXT] placeholders. After receiving the model's response, parse the corrected_configuration and diagnostic_checklist fields. Run automated validation checks: does the corrected connection string use a valid URI scheme? Are TLS parameters (sslmode, tls, ssl) explicitly set if the error indicated a TLS failure? Does the hostname resolve? For auth failures, flag the output for human review rather than auto-applying a credential change. Log every recovery attempt with the error signature, the model's suggestion, and the validation result for future analysis.

Model choice matters here. Use a model with strong code and configuration reasoning, such as claude-sonnet-4-20250514 or gpt-4o. Set temperature=0 to minimize variance in diagnostic reasoning. The harness must enforce a retry budget: if the model's corrected configuration fails validation or a subsequent connection attempt still fails, retry once with the new error context appended. After two failed recovery attempts, escalate to a human operator with the full diagnostic trail. Never allow the harness to enter an infinite retry loop. For high-risk environments, require explicit human approval before applying any configuration change that modifies authentication parameters, TLS settings, or network routes. The harness should also support a dry-run mode that returns the diagnostic checklist without applying changes, useful for on-call engineers who want to review the recommendation first.