Spice MySQL starter

Unified documentation: spiceframework.dev/integrations/mysql.

github.com/spice-framework/starter-mysql is the independently versioned, opt-in MySQL integration for Spice. It creates secure, instance-owned database/sql pools with the maintained go-sql-driver/mysql driver. Importing Spice core alone never selects this driver.

database, err := mysql.Open(mysql.Options{
    URL:             configuration.DatabaseURL,
    ApplicationName: "orders-service",
})
if err != nil {
    return nil, err
}

Open validates configuration and creates a caller-owned pool without network I/O or global driver/TLS registration. Ping performs the explicit readiness check with the caller’s context. TLS 1.2 hostname verification is the default; disabled TLS requires both tls=disable in the URL and explicit AllowInsecure, which is intended only for isolated local/container tests. Unknown driver options, incomplete identities, unbounded pool settings, and unsafe application metadata fail before construction without exposing URLs or passwords.

Install

go get github.com/spice-framework/starter-mysql@latest

During preview development, applications should pin the exact compatible commit recorded in support metadata.

Verify

Go 1.26.5 is mandatory:

make check
make compatibility
make release-rehearsal
make verify
make verify-release

The normal verifier checks formatting, module/vendor reproducibility, vet, allowlisted lint and nil safety, gosec, govulncheck, shuffled race tests, at least 85% product coverage, and offline vendor builds.

Core compatibility exercises the distinct minimum and current exact versions in spice-compatibility.json. The minimum must equal the direct Spice requirement in go.mod; temporary alternate module files keep both checks from rewriting go.mod, go.sum, or vendor. make verify runs both compatibility lines before the repository quality gate, and hosted CI runs them independently.

Release rehearsal runs the exact spice-dev tool authorized by go.mod twice from one inert plan, entirely from vendor with network and workspace resolution disabled. It requires byte-identical outputs, canonical checksums, central-renderer SPDX provenance, and no rehearsal signatures on Windows and Linux.

Real-system acceptance uses the immutable official MySQL 8.4.11 image index. It proves two isolated pools, live queries, bounded query cancellation, connection recovery, independent cleanup, and credential-safe authentication failures:

docker run --detach --name spice-mysql --publish 53306:3306 \
  --env MYSQL_DATABASE=spice --env MYSQL_USER=spice \
  --env MYSQL_PASSWORD=spice-test --env MYSQL_ROOT_PASSWORD=spice-root \
  mysql@sha256:b3b90af2a6552ae30c266fdb7d5dd55f3afb72404bb78d37fe8a23eb857fd3fb
SPICE_MYSQL_TEST_URL='mysql://spice:spice-test@127.0.0.1:53306/spice?tls=disable' \
  make integration
docker rm --force spice-mysql

MySQL DDL implicitly commits, so this starter does not claim a transactional migration backend. Applications own explicit resumable migration plans.

See the dependency review and support contract before production adoption.

Releases

The repository builds deterministic source-only releases with an SPDX 2.3 SBOM, SHA-256 checksums, and Ed25519 signatures. See the exact artifact and clean-tag ceremony in the release guide. The reviewed public trust anchor is committed with DER SHA-256 fingerprint 1c3d374cfe4465f6c04ad7afe22acad2bb05d51bc6d249745c92a817265d08a9; release claims are made only by a GitHub Release produced through the protected ceremony. The protected central workflow is the sole release authority.