Repository navigation
Conversation
WalkthroughThis PR corrects Bun's SQL TLS/SSL configuration documentation and adds validation tests. The docs were showing an incorrect ChangesSQL TLS/SSL Configuration
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
Comment |
|
Updated 1:21 AM PT - Jul 9th, 2026
❌ @robobun, your commit 278ffb4 has 5 failures in
🧪 To try this PR locally: bunx bun-pr 31016That installs a local version of the PR into your bun-31016 --bun |
There was a problem hiding this comment.
LGTM — thanks for wrapping the cert paths in Bun.file(); the docs now match the actual sslmode/tls parsing in shared.ts and the new tests pin it.
Extended reasoning...
Overview
This PR touches two files: docs/runtime/sql.mdx (corrects misleading SSL/TLS examples — sslmode goes on the URL query string, tls takes boolean | TLSOptions | BunFile, default mode is disable not prefer) and test/js/sql/adapter-env-var-precedence.test.ts (adds a new describe block with 7 tests pinning the documented behavior). No runtime/production code is modified.
I verified the docs claims against src/js/internal/sql/shared.ts: the SSLMode enum values (0–4) match the test's local mirror, normalizeSSLMode throws on unknown values, the default is SSLMode.disable (line 587), ?sslmode= is the query-param key parsed (line 624), and truthy tls with sslMode === disable bumps to prefer (line 849). All new prose is accurate.
Prior feedback addressed
My earlier inline comment flagged that ca: "path/to/ca.pem" would be treated as inline PEM content rather than a file path. Commit 3ff1117 addressed this fully — the new "Customizing The TLS Configuration" example and both pre-existing commented-out blocks now use Bun.file("path/to/..."). The current bug-hunting run found no issues.
Security risks
None. This is documentation + additive tests. If anything, it reduces a security footgun by removing an example that silently downgraded ssl: "verify-full" to prefer mode.
Level of scrutiny
Low-to-medium. Docs-only changes plus additive option-parsing tests (no network I/O, no DB connections — they only inspect new SQL(...).options). No CODEOWNERS apply to these paths. The test file already had the sslMode?: number module augmentation and existing sslMode assertions, so the new tests follow established patterns.
Other factors
Tests are purely additive (new describe block at the end), 49 pass / 0 fail per the PR description, and the serverName: "localhost" assertion in the combined-mode test correctly reflects the tls = { ...tls, serverName: hostname } injection at shared.ts:843.
There was a problem hiding this comment.
LGTM — the Bun.file(...) fix in 3ff1117 addresses my earlier comment, and the new docs + tests now line up exactly with the parsing logic in shared.ts.
Extended reasoning...
Overview
This PR corrects misleading TLS/SSL documentation in docs/runtime/sql.mdx (the old example showed ssl: "prefer" as a mode-string option, which the runtime never supported) and adds a test block to test/js/sql/adapter-env-var-precedence.test.ts pinning the actual option-parsing behavior. No runtime code is touched.
Verification against implementation
I cross-checked every documented claim against src/js/internal/sql/shared.ts:
SSLModeconst enum at L106-112 matches the test's mirrored values (disable=0 … verify_full=4).sslmodeURL query param is parsed vianormalizeSSLModeat L624-625; invalid values throw at L140.- Default
sslModeisdisableat L587 (docs previously saidprefer, now corrected). tls ||= options.tls || options.sslat L762 confirmssslis a deprecated alias with the same shape.- Truthy
tlswithsslMode === disablecoerces topreferat L849-850. serverNameis injected into thetlsobject only whensslMode !== disablebefore the prefer-coercion (L841), which is exactly what the twotlstests assert (object stays untouched fortls-only, gainsserverName: "localhost"when combined with?sslmode=verify-full).
My prior inline comment about ca/key/cert strings being PEM content rather than file paths was addressed in 3ff1117 — all three example blocks (the new active one and the two pre-existing commented ones) now use Bun.file(...).
Security risks
None. This is a documentation correction plus read-only assertions on option parsing. If anything, it reduces a security footgun by removing an example that silently downgraded verify-full requests to prefer.
Level of scrutiny
Low. Docs-only change with additive tests; no runtime/native code modified. Neither file falls under a CODEOWNERS rule.
Other factors
The new tests follow the existing patterns in the file (inspecting new SQL(...).options), reuse the existing env-scrubbing beforeEach, and the PR description reports 49 pass / 0 fail. CodeRabbit found nothing actionable. The bug-hunting system found no issues on this revision.
|
Docs-only diff. Tests pass 49/49 locally ( CI has been red on unrelated lanes across three runs, each a different fingerprint my diff cannot plausibly affect:
The diff between 6c4b3ff ↔ 3ff1117 ↔ d78fcec is three doc lines and a retrigger — no test or src change — yet each run failed on a completely different set of lanes. That's infra, not this PR. Used my one re-roll on d78fcec. Needs a maintainer to merge. |
d78fcec to
951b467
Compare
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Rebased onto One conflict in While rebasing I also found the runtime TLS coercion changed on main (#31495): an explicit Tests: 51 pass / 0 fail ( |
There was a problem hiding this comment.
LGTM — verified the rebased docs and tests match the current shared.ts TLS coercion (require-by-default, ca/rejectUnauthorized → verify-full); the only finding is a comment-length nit.
Extended reasoning...
Overview
This PR corrects docs/runtime/sql.mdx to stop documenting the unsupported ssl: "<mode>" string syntax and instead point users at the ?sslmode= URL parameter for mode selection and tls: boolean | TLSOptions | BunFile for transport configuration. It also adds an SSL mode and TLS option parsing describe block to test/js/sql/adapter-env-var-precedence.test.ts that pins the option-parsing behavior. No runtime/source code is touched.
Verification against runtime
I cross-checked every claim in the new prose against src/js/internal/sql/shared.ts at HEAD:
sslmodeis read from the URL query at L1795-1796 and normalized vianormalizeSSLMode(throws on unknown values, L147).- Default with no URL mode and no
tlsisSSLMode.disable(L1758, L886). - A truthy
tlswithsslMode === disableis bumped torequireat L2038-2039. - An object
tlswithrejectUnauthorized: true, or aca(absent an explicitrejectUnauthorized: false), escalates toverify_fullat L2020-2023. sslis read as a fallback fortlsat L1941.
Each new test case lines up with that logic, including the serverName injection at L2026-2029 (only applied once sslMode !== disable, which is why the { rejectUnauthorized: false } case correctly expects no serverName). The post-rebase update for #31495 (prefer → require, plus the verify-full escalation) is reflected in both the prose and the assertions.
Security risks
None introduced. This is documentation plus read-only option-parsing assertions; it tightens user guidance toward stronger TLS modes (the old docs silently degraded "verify-full" to a weaker mode). No auth, crypto, or permission code paths are modified.
Level of scrutiny
Low. Docs + tests only, no src/ changes, no CODEOWNERS on these paths. My earlier review caught the ca: "path/to/ca.pem" string-vs-PEM issue and the author fixed all three occurrences (now Bun.file(...)). The single remaining finding is a CLAUDE.md style nit about an 8-line explanatory comment above the test block — non-blocking and posted inline.
Other factors
The author reports 51/51 pass locally after the rebase; prior CI redness was unrelated infra flake across disjoint lanes. Nothing outstanding from human reviewers.
951b467 to
2310f8b
Compare
There was a problem hiding this comment.
LGTM — docs now match the actual shared.ts TLS coercion, and the new option-parsing tests pin it.
Extended reasoning...
Overview
This PR touches two files: docs/runtime/sql.mdx (corrects the SSL/TLS configuration examples and prose) and test/js/sql/adapter-env-var-precedence.test.ts (adds a new describe block with ~10 option-parsing tests). No runtime/source code is modified. I traced every documented claim and every new test assertion against src/js/internal/sql/shared.ts — the SSLMode enum values, the ?sslmode= URL parsing at L1795-1796, the disable default at L1758, the tls → require coercion at L2038-2040, the ca/rejectUnauthorized: true → verify_full escalation at L2020-2023, the serverName injection at L2026-2029, the ssl → tls alias at L1941, and the invalid-mode throw at L147 — and all of them line up exactly with what the docs and tests now state.
Security risks
None introduced. The change is a net security improvement: the previous docs told users to pass ssl: "verify-full" as a string, which silently degraded to a weaker mode. The corrected docs steer users to ?sslmode= (which actually works) and Bun.file() for cert material (so PEM paths aren't misparsed as inline content). No auth, crypto, or permission code paths are touched.
Level of scrutiny
Low. This is a documentation correction plus additive, non-network test cases that only exercise the synchronous option parser (new SQL(...).options) — they don't open connections. Neither file is covered by CODEOWNERS.
Other factors
Both of my prior inline comments (the Bun.file() wrapping and the 8-line comment-block nit) were addressed in 30be0dd / 2310f8b and are marked resolved. The bug-hunting pass on the current revision found nothing. CodeRabbit had no actionable findings. The author already noted CI flakes on unrelated lanes are infra noise; the relevant test file passes 51/0 locally per their report, and the assertions match the source as I read it.
|
CI (build #67124, rebased
This PR changes only Across this PR's life the red lanes have been disjoint each run (x64-musl build, ubuntu-25/debian-asan, darwin timeouts, now Windows install/spawn), which is the signature of infra flake rather than a regression here. The SQL option-parsing suite passes 51/0 locally ( Re-roll already spent earlier in this PR, so not pushing another. Ready for a maintainer to merge. |
…ptions
The MySQL and Postgres `Connection Options` examples showed
`ssl: "prefer"` with a string literal, implying that the options object
accepts an SSL mode string. It doesn't: the `ssl`/`tls` keys only take
`boolean | TLSOptions | BunFile`, and the mode selector is the `sslmode`
query parameter on the connection URL.
Passing `ssl: "verify-full"` as a string silently coerces to `prefer`
mode (because any truthy `tls` bumps the default `disable` up to
`prefer`), so a user following the old docs would get a weaker mode than
requested with no error.
- Rewrite the MySQL options example to use `tls: true` and point at the
SSL Modes section for mode selection.
- Rewrite the "SSL Modes Overview" to show `sslmode=` on the URL as the
single supported way to pick a mode, add a "Customizing The TLS
Configuration" subsection for `tls: {...}`, and correct the default
(it's `disable`, not `prefer`).
- Fix the URL-form example that used `?ssl=true` (which isn't parsed as
a TLS toggle) to use `?sslmode=require`.
- Pin the runtime behavior the new docs promise with unit tests in
test/js/sql/adapter-env-var-precedence.test.ts: sslmode values parse to
the expected enum, default is disable, `tls: true`/object coerces to
prefer, and URL sslmode + tls object compose correctly.
Fixes #31015
In Bun.TLSOptions, string values for ca/key/cert are interpreted as inline PEM content, not file paths — only Bun.file() triggers a file read. Update the new verify-full example (and the pre-existing commented-out blocks it sits next to) to use Bun.file() so a user copying the example actually loads the cert from disk instead of handing BoringSSL the literal string 'path/to/ca.pem' as PEM.
After rebasing onto main, the TLS mode coercion changed (#31495): an explicit tls/ssl option now requires an encrypted connection (`require`) instead of `prefer`, and supplying a `ca` or `rejectUnauthorized: true` escalates to `verify-full`. Update the docs that claimed `tls: true` enables `prefer` mode, and update the option-parsing tests to assert the new require/verify-full behavior (plus two new cases covering the verify-full escalation).
2310f8b to
25ba803
Compare
|
Rebased onto main again (25ba803). Same single conflict as last time in the SSL Modes section (main still had the |
There was a problem hiding this comment.
LGTM — docs now match runtime behavior, prior feedback addressed; the two remaining inline comments are test-quality nits, not blockers.
Extended reasoning...
Overview
This PR touches two files: docs/runtime/sql.mdx (rewrites the SSL/TLS configuration guidance for Bun.SQL to correctly show that sslmode= goes on the URL and tls takes boolean | TLSOptions | BunFile, not a mode string) and test/js/sql/adapter-env-var-precedence.test.ts (adds a synchronous option-parsing test suite pinning the documented behavior). No runtime source is modified.
Security risks
None introduced. This is documentation about TLS configuration, not code implementing it. The change is a strict security improvement: the old docs told users ssl: "verify-full" selected verify-full mode when it actually fell through to a weaker mode. The new prose correctly describes the require/verify-full escalation semantics, and the added tests pin those semantics against shared.ts. My earlier review caught one security-misleading example (ca: "path/to/ca.pem" as a string vs Bun.file(...)) and it was fixed; I re-verified all three affected blocks now use Bun.file().
Level of scrutiny
Low-to-moderate. Docs + test-only with no compiled-code surface, so no runtime regression risk. The prose is security-adjacent, which normally raises the bar, but the tests added in this PR mechanically verify every claim the new prose makes (each sslmode= value, the disable default, tls: true → require, ca/rejectUnauthorized: true → verify-full, ssl alias, invalid mode throws), so the docs are demonstrably aligned with runtime behavior rather than asserted by hand.
Other factors
I've reviewed this PR twice before; both prior comments (the Bun.file() wrapping and the 8-line comment block) were addressed and resolved. The only change since my last review is a mechanical rebase re-resolving the same docs conflict. The two findings from this run — a vacuous "sslmode wins" test name and a bare .toThrow() — are explicitly nits about test assertion strength, not correctness, and don't block. No CODEOWNERS on the touched paths.
Replace the combine test (whose inputs both independently produced verify-full, so neither path's regression could fail it) with two conflicting-input cases: a verify-ca URL mode survives a verifying tls object, and a require URL mode is escalated by one. Pin the invalid sslmode error message instead of a bare toThrow().
There was a problem hiding this comment.
LGTM — both remaining nits addressed in 278ffb4.
Extended reasoning...
Overview
This PR corrects the SQL SSL/TLS documentation in docs/runtime/sql.mdx and adds a test suite in test/js/sql/adapter-env-var-precedence.test.ts pinning the documented behavior. No runtime code is modified — only docs and tests.
The docs previously showed ssl: "prefer" (a mode string on the options object), which the runtime does not support; the fix documents the actual API: sslmode= on the connection URL selects the mode, and tls on the options object takes boolean | TLSOptions | BunFile. Three pre-existing commented-out examples were also corrected to wrap cert paths in Bun.file().
Security risks
None. No runtime, auth, crypto, or TLS handshake code is touched — this is documentation describing existing behavior plus synchronous option-parsing tests that never open a connection. The docs change is a net security improvement (the old example silently degraded verify-full to a weaker mode).
Level of scrutiny
Low. Docs + additive tests only. I verified every claim in the new prose and every test assertion against src/js/internal/sql/shared.ts (lines 113-147, 1947, 2026-2045): the SSLMode enum values, the ssl → tls alias, the tls: true → require coercion, the ca/rejectUnauthorized: true → verify_full escalation, the sslMode < verify_ca guard, the serverName injection, and the ERR_INVALID_ARG_VALUE message — all match.
Other factors
This is my fourth pass on this PR. All prior feedback has been addressed: the Bun.file() wrapping (3ff1117), the comment-length nit (2310f8b), and both nits from my last review — the vacuous "sslmode wins" test was replaced with two conflicting-input cases, and the bare .toThrow() now asserts the specific error message (278ffb4). The bug-hunting system found nothing on this revision. Tests are hermetic (no network, no subprocess) and follow existing patterns in the file.
|
Build #70858: the |
|
Closing as superseded: the runtime was changed in #37669 instead ( |
Problem
The
Connection Optionsexamples at https://bun.sh/docs/runtime/sql#mysql-options show:But the
ssl/tlsoption keys only acceptboolean | TLSOptions | Bun.BunFile— the SSL mode string is selected via the?sslmode=query parameter on the connection URL, not via an options key.Passing
ssl: "verify-full"as a string silently falls through toprefermode (any truthytlsbumps the defaultdisableup topreferat shared.ts:849). A user following the old docs would get a weaker mode than they asked for, with no error.Fix
Connection Optionsexample to usetls: trueand point at the SSL Modes section for mode selection.sslmode=on the URL as the single supported way to pick a mode. Correct the default (disable, notprefer). Replace the "Using With Connection Strings" subsection with "Customizing The TLS Configuration" that demonstratestls: {...}+ URLsslmode=composed together.?ssl=true(which isn't parsed as a TLS toggle and becomes a no-op connection parameter) to?sslmode=require.Tests
Added an
SSL mode and TLS option parsingdescribe block totest/js/sql/adapter-env-var-precedence.test.tspinning the runtime behavior the new docs promise:?sslmode=<mode>on the URL resolves to the correctSSLModeenum value.sslModedefaults todisablewhen nothing is set.tls: trueandtls: { ... }both coercesslModetoprefer.sslmode=verify-fullon the URL combined withtls: { rejectUnauthorized: true }produces the combined shape withsslMode = verify_full.ssloption is an exact alias fortls.?sslmode=bogusthrows.Fixes #31015
no test proof · iteration 4 · Platform-specific test-only change; deferring to CI.