08001

At a glance

SQLSTATE 08001 is sqlclient_unable_to_establish_sqlconnection in Class 08. 08001 is the server-side SQLSTATE for a client connection that could not be established. In the selected dblink_connect path the ERROR primary is could not establish connection and the refused-port reason is dynamic DETAIL; this differs from 08003 (an absent dblink handle) and startup failures such as 28000, 28P01, and 3D000.

Meaning

The server-side dblink_connect branch emits this code after libpq cannot open the requested remote endpoint. Its fixed diagnostic is an ERROR with primary could not establish connection; the endpoint and operating-system reason are dynamic DETAIL text. The condition concerns establishing a named remote handle, so it is different from an absent handle (08003) and from startup rejection before a session exists (28000 or 3D000).

The source does not format the DETAIL itself: dblink.c passes the libpq error string through errdetail_internal("%s", msg). That distinction matters when comparing versions or clients. The 18.6 refusal observed below includes the host, port, and Connection refused text, while the 10.21 refusal uses a different libpq wording; neither wording is a fixed 08001 template.

Diagnosis

Record the target host, port, authentication parameters, and complete DETAIL. The selected 18.6/10.21 runs leave the local autocommit session IDLE after the refused attempt; a real dblink handle then connects to the runner-owned target, runs remote SELECT 1, and is explicitly disconnected. That proves local recovery and handle cleanup, not completion of any remote business transaction.

Read the failure stage before retrying. A refused TCP endpoint, DNS or TLS failure, and authentication rejection can all be returned by libpq through this dblink branch, so inspect the dynamic DETAIL rather than classifying from the code alone. If the call runs inside an explicit local transaction, the ERROR can leave that transaction unusable until ROLLBACK (or ROLLBACK TO SAVEPOINT); the autocommit IDLE result in the selected case does not imply that an explicit transaction is still usable. The dblink handle belongs to the backend that created it, so check and repair it on that same session or pool member.

Response

Correct the endpoint or connection parameters, open a new handle, and verify a harmless remote probe before sending business work. If the failed request could have crossed a remote boundary, reconcile it before retrying; 08001 alone does not justify replaying a non-idempotent operation.

In autocommit, retrying the connection attempt after correcting the endpoint is a new statement and the owner session can remain usable. In an explicit transaction, first recover the local transaction, then establish and probe a fresh handle; a savepoint is useful only when the surrounding work is deliberately designed to continue. If the remote operation may have reached the target before the local error was reported, reconcile its result before replaying it.

Observed diagnostics

The fixed dblink_connect branch emits ERROR with primary could not establish connection and passes a dynamic libpq string as DETAIL (errdetail_internal("%s", msg)). In the selected 18.6 run that value was connection to server at "127.0.0.1", port 1 failed: Connection refused followed by libpq's hint; in the selected 10.21 run it began could not connect to server: Connection refused. Those are run-specific values, not a fixed SQLSTATE message template. Other producers may choose different text; a client-side exception without the server diagnostic is not evidence for this SQLSTATE.

The severity is fixed at ERROR for this dblink path. The selected local session stayed IDLE because the case used autocommit; do not transfer that status to a surrounding explicit transaction or to a remote transaction whose outcome was not observed.

Representative case

The SQL block creates dblink, attempts a refused runner-local port, then probes the owner session.

runner_host, runner_port, runner_db, and runner_user are runner placeholders, not literal values for a manual copy. Replace them with a reachable target and a login role that may connect to it; installing/using dblink and the remote login require the corresponding privileges. Keep the statements on the same owner backend and use the case's autocommit boundary if you want the selected recovery observation. The trigger is a server-side dblink attempt; it does not execute work on a remote transaction.

CREATE EXTENSION IF NOT EXISTS dblink;
SELECT dblink_connect('missing_remote', 'host=127.0.0.1 port=1 dbname=postgres connect_timeout=1');
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 08001, primary could not establish connection, 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 08001 case JSON and authored evidence. The runner manifest is verify/cases/08001/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

• 08000 — connection_exception
• 08003 — connection_does_not_exist
• 28000 — invalid_authorization_specification
• 3D000 — invalid_catalog_name

Sources

• src.dblink-connect.18.6 — contrib/dblink/dblink.c at REL_18_6 commit 724edf9bde9d356724ad384a2e196edc3c9f80f7; fixed blob SHA-256 e4cfaec3a0a1e5d23fded584725e0f6cf7a17321ad99e5fe046e8b7f97416f15 (source).
• src.dblink-connect.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/08001/cases.json · workspace ·
• verify/cases/08001/snippets.json · workspace ·

Message templates

could not establish connection

%s

Reproduction & repair cases

Recorded runtime evidence

{
  "probe": 1,
  "statuses": {
    "final": "IDLE",
    "after_error": "IDLE"
  },
  "diagnostic": {
    "text": "could not establish connection\nDETAIL:  connection to server at \"127.0.0.1\", port 1 failed: Connection refused\n\tIs the server running on that host and accepting TCP/IP connections?",
    "context": null,
    "severity": "ERROR",
    "sqlstate": "08001",
    "table_name": null,
    "column_name": null,
    "schema_name": null,
    "source_file": "dblink.c",
    "source_line": "338",
    "message_hint": null,
    "datatype_name": null,
    "exception_type": "SqlclientUnableToEstablishSqlconnection",
    "internal_query": null,
    "message_detail": "connection to server at \"127.0.0.1\", port 1 failed: Connection refused\n\tIs the server running on that host and accepting TCP/IP connections?",
    "constraint_name": null,
    "message_primary": "could not establish connection",
    "source_function": "dblink_connect",
    "internal_position": null,
    "statement_position": null,
    "severity_nonlocalized": "ERROR"
  },
  "dblink_repair": {
    "opened": "OK",
    "disconnected": "OK",
    "remote_probe": 1
  },
  "connection_scope": "server-side dblink connection to the same runner-owned target and a refused runner-local port",
  "connection_autocommit": true
}

{
  "probe": 1,
  "statuses": {
    "final": "IDLE",
    "after_error": "IDLE"
  },
  "diagnostic": {
    "text": "could not establish connection\nDETAIL:  could not connect to server: Connection refused\n\tIs the server running on host \"127.0.0.1\" and accepting\n\tTCP/IP connections on port 1?",
    "context": null,
    "severity": "ERROR",
    "sqlstate": "08001",
    "table_name": null,
    "column_name": null,
    "schema_name": null,
    "source_file": "dblink.c",
    "source_line": "302",
    "message_hint": null,
    "datatype_name": null,
    "exception_type": "SqlclientUnableToEstablishSqlconnection",
    "internal_query": null,
    "message_detail": "could not connect to server: Connection refused\n\tIs the server running on host \"127.0.0.1\" and accepting\n\tTCP/IP connections on port 1?",
    "constraint_name": null,
    "message_primary": "could not establish connection",
    "source_function": "dblink_connect",
    "internal_position": null,
    "statement_position": null,
    "severity_nonlocalized": "ERROR"
  },
  "dblink_repair": {
    "opened": "OK",
    "disconnected": "OK",
    "remote_probe": 1
  },
  "connection_scope": "server-side dblink connection to the same runner-owned target and a refused runner-local port",
  "connection_autocommit": true
}