08003

At a glance

SQLSTATE 08003 is connection_does_not_exist in Class 08. 08003 identifies a missing named connection handle in the current dblink backend session. It is a handle-lifecycle error, not evidence that the remote server is down (08001) or that an established socket failed (08006). The selected path first disconnects missing_remote, then proves a real handle can be opened, queried, and disconnected.

Meaning

This condition comes from the dblink handle lookup, before any remote SQL is run: the current backend has no named connection matching the request. The primary is assembled as connection "%s" not available, so the name identifies the local handle lifecycle, not remote reachability. A missing handle is therefore distinct from 08001 establishment failure and 08006 loss of an established connection.

The lookup is local to one PostgreSQL backend. A pool may give two clients the same application-level connection name while their dblink handle maps are different; creating working_remote on one backend does not repair missing_remote on another. The fixed branch has no DETAIL or HINT, so the quoted handle name and the session that issued the call are the first facts to preserve.

Diagnosis

Check the exact dblink name and the session or pool connection that owns it. The primary is dynamically assembled as connection "missing_remote" not available; in the selected autocommit run the failed lookup stays IDLE, and the repaired handle returns remote 1 before dblink_disconnect returns OK.

Separate a lookup failure from a lost socket. If the name was never opened on this backend, inspect the handle-creation path and pool checkout; if it was opened and a later remote call fails, collect that call's diagnostics before deciding whether to disconnect and recreate it. In an explicit local transaction, this dblink ERROR follows the normal transaction-abort boundary and requires rollback or a deliberately established savepoint before unrelated statements. The selected IDLE result is specifically the autocommit case.

Response

Create the named handle on the same session that will use it, or make an absent-handle disconnect explicitly idempotent. After a real remote operation, reconcile its result before closing or recreating a handle; do not reconnect every pool member merely because one session forgot a dblink name.

For autocommit, opening, probing, and disconnecting on the same backend is a complete lifecycle. For an explicit transaction, recover the local transaction first, then recreate the handle on that same backend; a successful new handle does not tell you whether an earlier remote operation committed. Keep handle names and ownership visible in pool diagnostics so a reconnect does not silently move work to another session.

Observed diagnostics

The fixed handle-lookup branch emits ERROR with primary connection "%s" not available; the requested handle name is dynamic and there is no fixed DETAIL or HINT. A client exception without this server diagnostic does not establish 08003.

The selected primary connection "missing_remote" not available is therefore a concrete name lookup, not a server reachability test. The fixed ERROR severity can leave an explicit transaction in INERROR; it left the selected autocommit owner IDLE because no surrounding transaction was open.

Representative case

The SQL block asks dblink to disconnect a handle that was never opened, then probes the same session.

The runner_host, runner_port, runner_db, and runner_user values are runner placeholders. Replace them with a target and login role for which the owner has dblink and remote-connection privileges. The handle is session-local: run the missing lookup, open/probe, and disconnect on the same backend; the selected case uses autocommit.

CREATE EXTENSION IF NOT EXISTS dblink;
SELECT dblink_disconnect('missing_remote');
SELECT dblink_connect('working_remote', 'host=runner_host port=runner_port dbname=runner_db user=runner_user connect_timeout=5');
SELECT * FROM dblink('working_remote', 'SELECT 1') AS result(value integer);
SELECT dblink_disconnect('working_remote');
SELECT 1;

The selected 18.6 run reports SQLSTATE 08003, primary connection "missing_remote" not available, and leaves the owner session IDLE after the failed operation. The controlled repair opened the named handle with OK, returned remote 1, and disconnected it with OK; the final owner probe returned 1 and IDLE. The 10.21 selected run passed the same assertions.

The downloadable case and evidence projections are 08003 case JSON and authored evidence. The runner manifest is verify/cases/08003/cases.json; the page SQL is checked against its shared registry before publication.

Versions

The generated facts table records the locked catalogue snapshots and earliest observed definition. The selected natural runtime scope is PostgreSQL 18.6 and 10.21; this does not infer behavior for every intermediate release.

Related

• 08001 — sqlclient_unable_to_establish_sqlconnection
• 08006 — connection_failure

Sources

• src.dblink-not-available.18.6 — contrib/dblink/dblink.c at REL_18_6 commit 724edf9bde9d356724ad384a2e196edc3c9f80f7; fixed blob SHA-256 e4cfaec3a0a1e5d23fded584725e0f6cf7a17321ad99e5fe046e8b7f97416f15 (source).
• src.dblink-not-available.10.23 — contrib/dblink/dblink.c at REL_10_23 commit 02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4; fixed blob SHA-256 2d542cc722ba361bd59990aaed7fe7c0f8e147155df5e5fcd56ee03b4dd27c61 (source).
• src.calls.REL_18_6 / src.calls.REL_10_23 — fixed local call scans, SHA-256 9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf / 00d16d3eb01b71ccf1b245c8f3102f9d0ec9f36fb02777b8dd1b99fcb263040c; these scans preserve the resolved call context used by the claims.

Source evidence

Evidence belongs to the frozen source and runtime versions listed here. It is not a runtime verification of the selected manual version.

• src/backend/utils/errcodes.txt · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• raw/calls/REL_18_6.jsonl · REL_18_6 ·
• raw/calls/REL_10_23.jsonl · REL_10_23 ·
• contrib/dblink/dblink.c · REL_18_6 ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• contrib/dblink/dblink.c · REL_10_23 ·
  02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4
• doc/src/sgml/xact.sgml · PG18-docs ·
  724edf9bde9d356724ad384a2e196edc3c9f80f7
• verify/cases/08003/cases.json · workspace ·
• verify/cases/08003/snippets.json · workspace ·

Message templates

connection "%s" not available

Reproduction & repair cases

Recorded runtime evidence

{
  "probe": 1,
  "statuses": {
    "final": "IDLE",
    "after_error": "IDLE"
  },
  "diagnostic": {
    "text": "connection \"missing_remote\" not available",
    "context": null,
    "severity": "ERROR",
    "sqlstate": "08003",
    "table_name": null,
    "column_name": null,
    "schema_name": null,
    "source_file": "dblink.c",
    "source_line": "195",
    "message_hint": null,
    "datatype_name": null,
    "exception_type": "ConnectionDoesNotExist",
    "internal_query": null,
    "message_detail": null,
    "constraint_name": null,
    "message_primary": "connection \"missing_remote\" not available",
    "source_function": "dblink_conn_not_avail",
    "internal_position": null,
    "statement_position": null,
    "severity_nonlocalized": "ERROR"
  },
  "dblink_repair": {
    "opened": "OK",
    "disconnected": "OK",
    "remote_probe": 1
  },
  "connection_scope": "server-side dblink name lookup followed by a real runner-owned dblink handle",
  "connection_autocommit": true
}

{
  "probe": 1,
  "statuses": {
    "final": "IDLE",
    "after_error": "IDLE"
  },
  "diagnostic": {
    "text": "connection \"missing_remote\" not available",
    "context": null,
    "severity": "ERROR",
    "sqlstate": "08003",
    "table_name": null,
    "column_name": null,
    "schema_name": null,
    "source_file": "dblink.c",
    "source_line": "173",
    "message_hint": null,
    "datatype_name": null,
    "exception_type": "ConnectionDoesNotExist",
    "internal_query": null,
    "message_detail": null,
    "constraint_name": null,
    "message_primary": "connection \"missing_remote\" not available",
    "source_function": "dblink_conn_not_avail",
    "internal_position": null,
    "statement_position": null,
    "severity_nonlocalized": "ERROR"
  },
  "dblink_repair": {
    "opened": "OK",
    "disconnected": "OK",
    "remote_probe": 1
  },
  "connection_scope": "server-side dblink name lookup followed by a real runner-owned dblink handle",
  "connection_autocommit": true
}