drivermysql

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

README

contrib/driver-mysql

Opens MySQL databases for github.com/ubgo/sqlb, and proves the core on a real MySQL 8.

go get github.com/ubgo/sqlb/contrib/driver-mysql
db, err := drivermysql.Open("user:pass@tcp(127.0.0.1:3306)/app")
q, err := sqlb.NewSelect(sqlb.MySQLDialect{}).Columns(sqlb.Bind(UserEmail, &email)).From(Users).Build()
err = sqlb.One(ctx, db, q)

Open parses the DSN with github.com/go-sql-driver/mysql and forces three settings whatever it says, because each is a silent wrong answer without it: parseTime, so a DATETIME scans into a time.Time; the UTC location, because the MySQL dialect writes times in UTC; and clientFoundRows, so an UPDATE reports the rows it matched, as Postgres and SQLite do. Without the third, an UPDATE setting a row to the value it already has reports 0 affected on MySQL and 1 elsewhere, and code reading 0 as "not found" says so about a row that exists; sqlbtest's crud_transcript case found it. WithChangedRows restores MySQL's own changed-rows count for a caller that wants it and knows it is on MySQL. WithMaxOpenConns and WithConnMaxLifetime override the pool defaults, DefaultMaxOpenConns and DefaultConnMaxLifetime. DriverName is the name the driver registers.

The proof

The module's tests run the shared conformance suite, sqlbtest.Run, against the database SQLB_MYSQL_DSN names (EnvDSN, read by DSNFromEnv), and skip loudly when it is unset. A scratch server:

docker run -d --rm --name sqlb-mysql -e MYSQL_ROOT_PASSWORD=sqlb -e MYSQL_DATABASE=sqlb -p 127.0.0.1:33069:3306 mysql:8.4
SQLB_MYSQL_DSN='root:sqlb@tcp(127.0.0.1:33069)/sqlb' go test ./...

Its first run found that the core's LIKE escape clause, ESCAPE '\', was an unterminated string in MySQL's default sql_mode; the core escapes with ! now, and every engine's conformance run checks it. The crud_transcript case, added 2026-09-28, found two more: the changed-rows count above, and that COALESCE(sum(x), ?) or sum(x) + ? comes back as DECIMAL(65,30), so an Expr[int64] could not be scanned; the MySQL dialect now types a bare integer parameter there through render.NumericParameters.

The suite runs twice here: TestConformance on utf8mb4_bin text columns, which compare by their bytes as Postgres and SQLite do, and TestConformance_DefaultCollation on the server default, utf8mb4_0900_ai_ci, where a plain = ignores case and accents and case_sensitive_eq is skipped with that reason.

Documentation

Overview

Package drivermysql opens MySQL databases for github.com/ubgo/sqlb.

It is a separate Go module for the reason every contrib module is: the core depends on nothing but the standard library, so a library that embeds it inherits no driver.

The module's real work is its tests. MySQL was, until this module, the one engine the core's universality rule named and nothing here had ever run against, so a quarter of every "universal" claim was checked by reading MySQL's documentation. The first run found the core's LIKE escape clause, ESCAPE '\', was an unterminated string on MySQL's default sql_mode.

The driver is github.com/go-sql-driver/mysql, so exec.DBTX is satisfied by *sql.DB and *sql.Tx exactly as for the other engines.

Index

Constants

View Source
const (
	// DefaultMaxOpenConns caps the pool; a MySQL connection is a server
	// thread, and max_connections is the limit an uncapped pool reaches.
	DefaultMaxOpenConns = 8
	// DefaultConnMaxLifetime recycles connections before MySQL's wait_timeout
	// closes them from the server side.
	DefaultConnMaxLifetime = 5 * time.Minute
)

Defaults applied to every pool Open creates.

View Source
const DriverName = "mysql"

DriverName is the database/sql name go-sql-driver/mysql registers.

View Source
const EnvDSN = "SQLB_MYSQL_DSN"

EnvDSN is the environment variable the tests read the connection string from. Absence is a loud skip, never a silent pass.

Variables

This section is empty.

Functions

func DSNFromEnv

func DSNFromEnv() (string, bool)

DSNFromEnv reads EnvDSN, reporting whether it was set.

func Open

func Open(dsn string, opts ...Option) (*sql.DB, error)

Open opens a MySQL database at dsn and pings it. It forces three settings whatever the DSN says, because each is a silent wrong answer without it: parseTime, so a DATETIME scans into a time.Time rather than bytes; a UTC location, because the dialect writes times in UTC and a DATETIME read back in another zone would shift by the offset; and clientFoundRows, so an UPDATE reports the rows it matched, as Postgres and SQLite do. Without it an UPDATE that sets a row to the value it already has reports 0 affected on MySQL and 1 elsewhere, and code that reads 0 as "not found" says so about a row that exists; measured on 8.4.11 by sqlbtest's crud_transcript case. WithChangedRows restores MySQL's count.

Types

type Option

type Option func(*config)

Option adjusts what Open does.

func WithChangedRows

func WithChangedRows() Option

WithChangedRows restores MySQL's own rows-affected count, which counts only the rows an UPDATE changed, instead of the rows it matched. It is the one way out of the clientFoundRows default Open sets, for a caller that wants "did anything change" and knows it is on MySQL; a library that runs on more than one engine should not use it, because no other engine can answer that question the same way.

func WithConnMaxLifetime

func WithConnMaxLifetime(d time.Duration) Option

WithConnMaxLifetime sets how long a connection may be reused.

func WithMaxOpenConns

func WithMaxOpenConns(n int) Option

WithMaxOpenConns caps the pool at n connections.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL