mysql

README

mysql

MySQL driver module for rio, the zero-surprise Go ORM, backed by go-sql-driver/mysql.

The module is deliberately thin: constructors, DSN hygiene, and precise error translation. All SQL generation lives in rio itself — see the rio documentation for queries, writes, relations and everything else.

Install

go get github.com/go-rio/mysql

Usage

import (
	"github.com/go-rio/rio"
	"github.com/go-rio/mysql"
)

db, err := mysql.Open("user:password@tcp(localhost:3306)/app")
if err != nil {
	log.Fatal(err)
}
defer db.Close()

users, err := rio.From[User]().Where("age > ?", 18).All(ctx, db)

Open accepts every rio.Option. If you already manage your own *sql.DB, wrap it instead — but then the parseTime setting is on you:

sqlDB, err := sql.Open("mysql", dsn) // must include parseTime=true
db := mysql.New(sqlDB)

parseTime

rio scans DATETIME and TIMESTAMP columns into time.Time, which requires the driver option parseTime=true. Open keeps that invariant without surprising you:

• DSN does not mention parseTime → Open adds parseTime=true.
• DSN sets parseTime=true → passed through byte for byte.
• DSN sets parseTime=false → Open returns an error instead of silently overriding an option you spelled out.

Open never touches loc, so existing data keeps its meaning. For new applications we recommend storing UTC — the driver's default loc — and converting to local time at the edges; rio already writes time.Time values as UTC truncated to microseconds.

Error translation

Constraint violations come back as rio sentinels with the driver error still in the chain, so both checks work:

MySQL error	Sentinel
1062 ER_DUP_ENTRY	rio.ErrDuplicateKey
1451 / 1452 (foreign key held or missing)	rio.ErrForeignKeyViolated

err := rio.Insert(ctx, db, &user)
if errors.Is(err, rio.ErrDuplicateKey) { ... }

var me *mysql.MySQLError // errors.As still reaches the driver error

Upsert semantics on MySQL

MySQL has no conflict target: rio.Upsert renders ON DUPLICATE KEY UPDATE, which reacts to any unique index on the table, so rio.OnConflict(...) documents intent rather than constraining which index fires — a documented semantic difference rio does not paper over.

License

The MIT License. Copyright (c) 2026-now TreeNewBee.

Documentation

Overview

Package mysql connects rio to MySQL through the github.com/go-sql-driver/mysql driver.

The package is deliberately thin: it constructs handles, keeps the DSN honest about parseTime, and translates the driver's error numbers into rio's sentinel errors. All SQL generation lives in github.com/go-rio/rio.

Index

• func New(db *sql.DB, opts ...rio.Option) *rio.DB
• func Open(dsn string, opts ...rio.Option) (*rio.DB, error)

Functions

func New

func New(db *sql.DB, opts ...rio.Option) *rio.DB

New wraps an existing *sql.DB in a rio handle with the MySQL dialect and this package's error translator installed. The caller's options apply after the translator, so a rio.WithErrorTranslator among them replaces it. New performs no DSN hygiene — the *sql.DB is the caller's; make sure it was opened with parseTime=true, or time.Time columns will fail to scan.

func Open

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

Open opens a MySQL database for rio. The DSN uses the go-sql-driver format: user:password@tcp(host:port)/dbname?param=value.

rio scans DATETIME and TIMESTAMP columns into time.Time, which requires the driver option parseTime=true. Open therefore appends parseTime=true when the DSN does not mention the option, and returns an error when the DSN explicitly sets parseTime=false instead of silently overriding a choice the caller spelled out. Every other option — including loc — passes through untouched, so existing data keeps its meaning; the README explains why new applications should store UTC.

Like database/sql, Open validates its arguments without connecting; ping the handle returned by Unwrap to verify the server is reachable.