Make this a real fork: module path github.com/block/mysql, driver name block-mysql

[morgo]

Why

This fork's two capabilities — QueryResultContext (#1) and Warnings() (#2) — are consumed through (*sql.Conn).Raw and a structural interface assertion. That's good for decoupling, but it has a sharp consequence: a consumer that builds without the replace directive compiles clean and then fails at runtime on every statement.

And replace cannot fix that for consumers, because it isn't inherited across module boundaries. Any downstream module that imports a library built on this fork silently links upstream go-sql-driver instead. A distinct module path is the only mechanism Go has for expressing a dependency that is not substitutable.

We rely on both features today, so we need a tracking fork to carry them until such a time as they are merged upstream. QueryResultContext is raised as go-sql-driver/mysql#1793 and remains open; if upstream adopts these, the fork can be retired and consumers move back to the upstream path.

What changes

• module github.com/block/mysql in go.mod. Consumers drop the replace.
• The driver registers as block-mysql, not mysql. This is required rather than cosmetic: now that the module path differs, a dependency graph that still reaches upstream go-sql-driver anywhere links both packages into one binary, and two sql.Register calls under the same name panic at init.
• CI matrix narrowed to Linux + MySQL LTS (9.7, 8.4, 8.0), plus Go 1.26/1.25 against the newest MySQL — 5 test jobs instead of 23 (21 matrix combinations become 3, plus the two appended older-Go entries). macOS, Windows and the four MariaDB versions are dropped because Block deploys none of them.
• README covering what the fork adds, what it changes and why, the supported-platform scope, the errors.As hazard when both drivers are linked, and how to merge upstream forward.
• Three sql.Open("mysql", ...) call sites in driver_test.go move to driverNameTest, matching every other site in the file — which is what upstream's own -ldflags override already assumed.

Edits to upstream-owned files are held to exactly two things: the module path / driver name, and the CI matrix. The capabilities themselves live in files upstream doesn't have, so merging upstream/master stays near-mechanical — this branch rebased onto the latest upstream merge (5 commits touching dsn.go, connector.go, connection.go and packets.go) with zero conflicts.

Note for consumers linking both drivers

Because the module path differs, this package's types are distinct from upstream's even though the source is identical. Most importantly, an *mysql.MySQLError from this package will not satisfy an errors.As against upstream's, and the check returns false silently rather than failing loudly. Anyone with error-inspection sites should audit which package each one imports. For strata specifically that means migrating block/vitess's mysqltopo onto block-mysql; block/spirit turns out not to need it, since no strata error-inspection site sees a spirit-originated error.

Verification

• Full test suite green locally against MySQL 8.0.44 (-race -parallel 10, local_infile=1)
• gofmt -l clean, staticcheck ./... clean
• CI green on the narrowed matrix

🤖 Generated with Claude Code

---

Review follow-up (e3ae89d): added fork_test.go, pinning the two lines this PR consists of — the module path (read from the real go.mod via debug.ReadBuildInfo) and the registered driver name (read from sql.Drivers()). Both reverts previously built clean and passed the full suite, and both are what every git merge upstream/master has a conflict on. Also documented the one silent both-linked failure mode (a missed sql.Open("mysql", …) resolves to upstream), repointed the LOAD DATA LOCAL INFILE import and its godoc link, and corrected the job count above.

[coveralls]

Coverage Report for CI Build 34057393127

Warning

Build has drifted: This PR's base is out of sync with its target branch, so coverage data may include unrelated changes.
Quick fix: rebase this PR. Learn more →

Coverage decreased (-0.2%) to 84.439%

Details

• Coverage decreased (-0.2%) from the base build.
• Patch coverage: No coverable lines changed in this PR.
• 9 coverage regressions across 5 files.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

9 previously-covered lines in 5 files lost coverage.

File	Lines Losing Coverage	Coverage
packets.go	4	86.8%
statement.go	2	75.18%
conncheck.go	1	69.23%
connection.go	1	78.64%
utils.go	1	90.94%

---

Coverage Stats

Relevant Lines:	4190
Covered Lines:	3538
Line Coverage:	84.44%
Coverage Strength:	334367.21 hits per line

---

💛 - Coveralls

[Copilot]

🟡 Changes recommended

README.md still contains later sections that reference the upstream import path/godoc URLs (e.g., import "github.com/go-sql-driver/mysql"), which conflicts with the new module path and can misdirect users.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR turns the repository into a distinct Go module fork (github.com/block/mysql) and avoids runtime conflicts by registering the SQL driver under a new name (block-mysql), with accompanying documentation/test/CI updates to match.

Changes:

• Updated the Go module path to github.com/block/mysql and adjusted references accordingly.
• Changed the default registered driver name to block-mysql and updated tests/examples to use the appropriate driver name variable(s).
• Narrowed the GitHub Actions CI matrix to Linux + selected MySQL versions, and expanded the README with fork-specific context.

File summaries

File	Description
utils.go	Updates TLS config example to use block-mysql driver name.
README.md	Adds fork overview and updates install/usage examples for new module path/driver name.
go.mod	Changes module path to github.com/block/mysql and documents rationale.
driver.go	Updates package docs and changes default driver registration name to block-mysql.
driver_test.go	Updates -ldflags path and uses driverNameTest in remaining hardcoded sql.Open call sites.
.github/workflows/test.yml	Narrows CI matrix to Linux and MySQL-only versions.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[aparajon]

🤖 Adversarial correctness review — 6346a1ec (+129/-23, 6 files)

The argument for the module path is the right one and it's worth restating in review terms, because it is the whole justification for the churn: replace is a main-module-only directive, so a library built on this fork hands its own consumers upstream go-sql-driver with no diagnostic, and the failure surfaces at the first statement rather than at compile time. A distinct path is the only thing in Go's model that says "not substitutable." The driver-name change follows from it necessarily rather than by taste — once the paths differ, both packages can be linked, and two sql.Register calls under one name panic in init.

The mechanical side is complete. Every sql.Open site in the repo now goes through driverNameTest (which defaults to driverName), so there is no literal "mysql" left in any call — I checked all 19, including the four in benchmark_test.go that were already converted upstream. The only surviving go-sql-driver/mysql strings in Go files are issue, PR and wiki links, which are provenance and should stay. sql.Register has exactly one call site.

⭐ What I'd want changed before merge is documentation of one silent failure mode, and a test for the two lines this PR is entirely about. Both are cheap, and both are about the thing the fork exists to prevent.

#	Sev	Where	What
1	low-med	README.md:50	"Linking both drivers" documents the errors.As hazard but not the one that mirrors the PR's own thesis: with both linked, a missed sql.Open("mysql", …) keeps working — against upstream — instead of failing loudly
2	low-med	driver.go:99, go.mod:5	Both changes survive mutation against the full suite: nothing pins the driver name or the module path, and these are precisely the two lines the documented git merge upstream/master workflow re-touches
3	low	README.md:655	The LOAD DATA LOCAL INFILE section still says import "github.com/go-sql-driver/mysql" — the one code sample left on the old path, in the section that specifically requires a direct import
4	low	README.md:82, PR body	"5 CI jobs rather than 25" — measured 5 vs 23

---

1 — the silent case in "Linking both drivers" is the one that isn't listed (low-med)

The section names the errors.As mismatch, which is right and is the subtle one. But I went looking for the rest of the both-linked surface, and the interesting result is that almost all of it fails loudly, which makes the one exception worth calling out by name rather than leaving the reader to infer it.

Every registry in this package is a package-level global — fileRegister/readerRegister in infile.go:19, plus the TLS, server-pub-key and dial registries — so a Register* call made against the wrong import path simply doesn't apply to connections from the other. Each of those then errors on use, with a message that points straight at the cause:

local file '%s' is not registered           (infile.go:141)
reader '%s' is not registered               (infile.go:118)
invalid value / unknown config name: ...    (dsn.go:248)
invalid value / unknown server pub key name (dsn.go:263)

Those are migration chores, not traps. The trap is sql.Open. Any transitive dependency that imports upstream go-sql-driver at all runs its init and registers "mysql", so in a both-linked binary a call site you forgot to update:

db, err := sql.Open("mysql", dsn)   // resolves — to upstream

succeeds, connects, and behaves correctly right up until something reaches for QueryResultContext or Warnings() through (*sql.Conn).Raw, where the structural assertion fails against a connection that never had them. That is the exact "clean build, runtime failure" shape the module-path rename exists to eliminate, reintroduced through the driver name. Note the asymmetry that makes it easy to under-rate: with upstream not in the graph, the same mistake is completely benign — sql: unknown driver "mysql" (forgotten import?). So the danger is proportional to the case this section is already about, which is why it belongs in this section. Two sentences.

2 — nothing pins either of the two lines this PR consists of (low-med)

Both mutations survive the full suite:

Mutation	Result
var driverName = "block-mysql" → "mysql"	survives — builds, and the only failing test is the pre-existing one
module github.com/block/mysql → github.com/go-sql-driver/mysql	survives — same

The second is unsurprising (no file imports the module path, so nothing observes it) and the first follows from driverNameTest defaulting to driverName: the tests open whatever the driver registered, which is exactly what makes them portable, and also what makes them blind to a change in the value.

Ordinarily "add a test asserting a constant" is not worth the line. Here it is, because of the workflow this PR documents three sections above:

git merge upstream/master

go.mod's module line and driver.go's driverName are the two places where every future merge has a change on the upstream side to resolve, and reverting either is silent — the module path revert reintroduces the substitutability problem this PR was opened to fix, and the driver-name revert reintroduces the init panic for both-linked consumers. Neither breaks a build or a test, so nothing catches a bad conflict resolution.

One test file covers both, needs no server, and killed both mutations when I tried it:

package mysql

import (
	"database/sql"
	rtdebug "runtime/debug" // aliased: const.go:14 already declares `debug`
	"slices"
	"testing"
)

func TestForkIdentity(t *testing.T) {
	bi, ok := rtdebug.ReadBuildInfo()
	if !ok || bi.Main.Path != "github.com/block/mysql" { ... }
	if !slices.Contains(sql.Drivers(), "block-mysql") { ... }
}

debug.ReadBuildInfo().Main.Path resolves to the module under test, so it reads the real go.mod line rather than a copy of it — measured main_path="github.com/block/mysql", sql.Drivers()=[block-mysql] on this branch. The rtdebug alias is needed because const.go:14 declares a package-level debug.

3 — one code sample still on the upstream path, in the section that can't use a blank import (low)

LOAD DATA LOCAL INFILE support

For this feature you need direct access to the package. Therefore you must change the import path (no _):

import "github.com/go-sql-driver/mysql"

The Installation and Usage blocks were both repointed; this one wasn't, and it is the worst one to miss. Every other remaining mention of the upstream path in the README is a link — godoc, wiki, issues — where pointing at upstream is correct. This is a copy-pasteable import, in the one section whose whole premise is that the reader needs the package, not just the driver. Follow it and you get upstream's RegisterLocalFile writing into upstream's fileRegister, while connections come from block-mysql, and LOAD DATA then fails with local file '...' is not registered — findable, but from a snippet in this repo's own README.

godoc.org/github.com/go-sql-driver/mysql at :662 in the same section is a different case and is fine to leave (the API is upstream's), though pkg.go.dev/github.com/block/mysql would document the fork's additions too.

4 — the job counts (low)

The narrowing is a good call and the shape of it checks out: matrix.go is [go[0]] (1.27) across three MySQL LTS versions, plus two appended include entries pinning 1.26 and 1.25 to the newest MySQL. I ran the workflow's embedded Python at both revisions and expanded the matrix by GitHub's include rules (an entry matching no base combination is appended, not merged):

base (13ecedf):  os×go×mysql = 21, include appended 2  => 23 test jobs
head (6346a1ec): os×go×mysql =  3, include appended 2  =>  5 test jobs

So 5 is right and 25 isn't — it's 23 (26 vs 8 if you count lint, list and finish). Small thing, but it's in the public README and in the PR body, and it's the number a reader would use to sanity-check the change. 21 → 3 matrix combinations, or just dropping the "rather than 25", both fix it.

---

Verified — the local run, and five attacks that dissolved

Local: go build ./... clean, go vet ./... clean, gofmt -l empty. The full suite runs here against a local MySQL 8, and TestLoadData is the only failure — Error 3948: Loading local data is disabled, i.e. the local_infile=1 that CI's my-cnf sets and my server doesn't. I diffed the failing-test sets at head and at the merge base and they are identical, so nothing in this diff moves the suite.

Attack that dissolved: a missed sql.Open("mysql", …) in the repo's own tests. This is the failure the driver rename would cause first, and the PR body's claim that three sites moved "matching every other site in the file" understates the check — the three are in driver_test.go, but benchmark_test.go has four more that upstream had already converted. All 19 sql.Open calls in the repo now pass driverNameTest, and driverNameTest falls back to driverName in init, so a -ldflags override still works as upstream documented.

Attack that dissolved: RegisterTLSConfig's doc comment being the only one updated. utils.go:56 moves to sql.Open("block-mysql", …) while driver.go:82 still points at upstream's #dsn-data-source-name anchor. Both are correct as written: the first is a runnable snippet, the second is a pointer to DSN documentation that this fork doesn't change. Worth knowing they're deliberate rather than half-done.

Attack that dissolved: dangling README links. driver.go:18 now points at github.com/block/mysql#usage, and the merged README does have ## Usage (line 162), so the anchor resolves. The fork section's relative links [QueryResultContext](unified.go) and [Warnings()](warnings.go) both resolve, and both symbols exist (unified.go:53, warnings.go:44). The one wart is a duplicate ## License (the fork's at :86, upstream's at :694, so the latter is #license-1); nothing links to either, so it's cosmetic.

Attack that dissolved: coveralls flag collisions from the narrowed matrix. flag-name: ${{ runner.os }}-Go-${{ matrix.go }}-DB-${{ matrix.mysql }} derived its uniqueness partly from the OS, and dropping macOS/Windows leaves Linux constant — exactly how a matrix reduction creates duplicate parallel-build flags and corrupts the merged report. The five remaining combinations still differ in go or mysql, so all five flags are distinct.

Leak check: clean. No internal identifiers in the diff. The PR body names strata and block/vitess's mysqltopo for consumer-migration context; block/vitess and block/spirit are public, and the name already appears in public Block source, so nothing here is a new disclosure.

The matrix expansion and the fork-identity probe were run with throwaway files that have since been removed, and both mutations were restored from backup; the worktree is clean at 6346a1ec.

This review was generated by Claude Code (claude-opus-5).

[aparajon]

🤖 Approving — the module-path argument is the right one (replace isn't inherited across module boundaries, so a library built on this fork hands its consumers upstream silently), the driver rename follows from it necessarily, and the mechanical side is complete: all 19 sql.Open sites go through driverNameTest, one sql.Register, and the suite's only failure is a pre-existing local_infile one that fails identically on the merge base.

Findings in my review comment — two low-med worth acting on: the one silent both-linked failure mode that "Linking both drivers" doesn't list (a missed sql.Open("mysql", …) resolves to upstream), and the fact that both of this PR's substantive lines survive mutation, which matters given the documented merge-forward workflow. Plus a stale import snippet and a job count.

This stamp was left by Claude Code (claude-opus-5).