Skip to content

driver/postgres: a DSN without connect_timeout gets a 10 s default (v1.6.0, Refs #1212) - #1223

Merged
FumingPower3925 merged 5 commits into
mainfrom
fix/postgres-default-connect-timeout-1212
Nov 2, 2026
Merged

FumingPower3925 merged 5 commits into
mainfrom
fix/postgres-default-connect-timeout-1212

Conversation

@FumingPower3925

@FumingPower3925 FumingPower3925 commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

driver/postgres: a DSN without connect_timeout gets a 10 s default; connect_timeout=0 keeps no timeout. Refs #1212 (finishes it; maintainer decision 2026-11-01, review r1 of #1216 section 4).

The problem

#1216 made connect_timeout bound the dial and the startup together, but kept the documented "zero means no client-side timeout" for the unset case. So with context.Background() and no connect_timeout in the DSN, a server that accepts the connection and never answers still held Open/acquire for ever. Redis and memcached default to 5 s. The maintainer decided on a 10 s default when connect_timeout is absent (a backend fork plus SCRAM, and serverless databases that resume from pause, take seconds; 10 s still turns a forever-hang into a clear error), and an explicit connect_timeout=0 keeps the libpq meaning, no timeout. A negative value stays rejected at DSN parse (#1216).

The change

  • Options.connectTimeoutExplicit (precedent: autoCacheStatementsExplicit) records that the DSN parser saw a connect_timeout, in both the key=value and the URL form (they share setOption). Absent and 0 both gave ConnectTimeout == 0 before; now they differ.
  • Options.effectiveConnectTimeout() is the budget: ConnectTimeout if > 0; none for an explicit 0; the default (10 s, defaultConnectTimeout) if the key was absent. In a DSN built in code (no parser), zero is "not set" (the default applies) and a negative value is "no timeout"; that is documented on Options.ConnectTimeout. beginDial, connectDeadline and the startup bound all use it, so the three dial paths (direct, unix event loop, net.Conn loop), Pool, Open and Connector get it the same way (nothing else reads ConnectTimeout).
  • The error says where the bound came from: startup timed out (default connect_timeout 10s; set connect_timeout=0 for none) for the default, (connect_timeout 3s) for a set one. Both match errors.Is(err, context.DeadlineExceeded).
  • Docs: Options.ConnectTimeout describes the default, the explicit 0, the negative value, the code-built DSN, and still says the DNS lookup is not bounded.
  • Test hook testHookDefaultConnectTimeout (nil in production, like driver/redis: bound the connection handshake by DialTimeout (v1.6.0, Refs #1205) #1209's) lowers the default so the tests do not wait 10 s.

Commits: d7db3d6 the tests (RED on main; the hook is declared there, inert, so the tests compile on main), 0f08aa7 the fix (and 319f2d8, the r2 follow-up).

RED / GREEN

RED, d7db3d6 alone (macOS arm64, go test ./driver/postgres -run 'Default|Explicit' -v; the failures are the 2 s watchdog message, not a test timeout):

--- FAIL: TestStartupIsBoundedByTheDefaultConnectTimeout1212          direct|eventloop|netconn x keyvalue|url: 6/6 "still blocked after 2s: the startup is not bounded"
--- FAIL: TestPoolAcquireIsBoundedByTheDefaultConnectTimeout1212      "Ping is still blocked after 2s: a DSN without connect_timeout has no default bound"
--- PASS: TestExplicitConnectTimeoutOverridesTheDefault1212           (guard, passes on main by design: connect_timeout=0 is unbounded by the driver; connect_timeout=1 wins over the default)

GREEN, dc6ad43: all pass. No connect_timeout, context.Background(), silent server, default lowered to 300 ms: the dial fails after 300 ms on all three paths and both DSN forms, and through Open + Ping. connect_timeout=0 with a caller deadline of 900 ms: ends at the caller's 900 ms, the error is the caller's (not "startup timed out"). connect_timeout=1 with the default lowered to 300 ms: ends at 1 s with the driver's error. TestEffectiveConnectTimeout1212 pins the table (absent = 10 s default, 0 = none, N = N s, in both forms; code-built DSN zero = default, negative = none).

Mutants (each alone, go test -run 'Default|Explicit|Effective|1212' -count=1)

mutant tests that fail
M1 no default (absent = no timeout) TestEffectiveConnectTimeout, TestStartupIsBoundedByTheDefault..., TestPoolAcquireIsBoundedByTheDefault...
M2 an explicit connect_timeout=0 is not remembered TestEffectiveConnectTimeout, TestExplicitConnectTimeoutOverridesTheDefault
M3 a set connect_timeout loses to the default TestEffectiveConnectTimeout, TestExplicitConnectTimeoutOverridesTheDefault, TestPoolAcquireIsBoundedByConnectTimeout, TestSlowConnectEatsTheConnectTimeoutBudget, TestStartupIsBoundedByConnectTimeout
M4 default of 5 s TestEffectiveConnectTimeout
M5 a negative code-built value is "not set" TestEffectiveConnectTimeout, TestStartupHasWhatTheDialLeftOfConnectTimeout

Checks

  • -race -run 'Default|Explicit|Effective|1212|ParseDSN' -count=20 Linux docker golang:1.27.3 --cpus 2: ok; whole driver/postgres -race -count=1: ok (68 s). macOS -race -count=20 of the new tests: ok.
  • GOOS=windows go vet ./driver/postgres: clean. golangci-lint v2.15.0 GOOS=linux: only the two pre-existing errcheck findings in untouched test files.
  • The new tests take 0.3 s to 1 s each (parallel subtests); one uses a 300 ms lowered default and a 2 s watchdog, no sleep decides a result.
  • Not run locally: the windows-latest and macos-latest Portable fallback jobs.

Release note

driver/postgres: when the DSN has no connect_timeout, the dial and the startup are now bounded by a default of 10 s (before: no bound other than the caller's context, so a server that accepted the connection and never answered held Open/acquire for ever under context.Background()). Set connect_timeout=0 to keep the old behaviour (wait indefinitely, as in libpq), or a larger value for servers that are slow to accept or authenticate (for example serverless databases resuming from pause (Aurora Serverless v2 with auto-pause resumes in up to about 15 s, longer than the default: set connect_timeout=30, or 0, for it)). A negative connect_timeout is rejected, as before.

Review r2 follow-up (commit 319f2d8)

  • MINOR, stale text: the negative-value error now reads connect_timeout = -1: must be >= 0 (0: no timeout; absent: the 10s default); the test checks it.
  • MINOR, test gap: TestDialerTimeoutIsTheBudget1212 asserts beginDial's net.Dialer.Timeout is the budget (absent: 10 s, or the hook's value; 0: none; N: N seconds; both DSN forms). The mutant that keeps the raw ConnectTimeout for the dialer, which survived (a host that drops connection attempts would hold a dial with no connect_timeout for the OS connect timeout, one to two minutes), now fails it.
  • NIT: the error text is pinned: TestStartupIsBoundedByTheDefaultConnectTimeout1212 requires default connect_timeout 300ms; set connect_timeout=0 for none, and the explicit-timeout cases require its absence (the mutant "the label never says default" now fails).
  • NIT: the ConnectTimeout doc says the PG* environment variables (PGCONNECT_TIMEOUT ...) are not read. The fix commit cited above is corrected (dc6ad43 was amended into 0f08aa7).
  • Release note, Aurora: named above. If the maintainer weighs that population high, 30 s is the conservative default; 10 s stays defensible (pgjdbc's connect default). The decision is the maintainer's.
  • Checks on 319f2d8: plain TESTING_STRICT_ALLOC_BUDGETS=1 go test ./driver/postgres -run '^TestAllocBudgets$' ok (macOS, Linux docker); -race -run 'Default|Explicit|Effective|Dialer|1212|ParseDSN' -count=20 Linux docker --cpus 2 ok (231 s); whole driver/postgres -race -count=1 Linux ok (66 s); GOOS=windows go vet clean; golangci-lint only the two pre-existing errcheck findings.

@FumingPower3925 FumingPower3925 added this to the v1.6.0 milestone Nov 1, 2026
@coderabbitai

coderabbitai Bot commented Nov 1, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Caution

Review failed

The pull request is closed.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@codecov

codecov Bot commented Nov 1, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@FumingPower3925
FumingPower3925 marked this pull request as ready for review November 2, 2026 21:03
@FumingPower3925
FumingPower3925 merged commit 4d9d8a2 into main Nov 2, 2026
56 checks passed
@FumingPower3925
FumingPower3925 deleted the fix/postgres-default-connect-timeout-1212 branch November 2, 2026 21:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant