go-sqlite3 — SQLite3 Driver for Go via cgo

Introduction

go-sqlite3 is a cgo-based SQLite3 driver for Go that conforms to the standard database/sql interface. It lets Go developers work with SQLite databases using the same query API they would use for PostgreSQL or MySQL, keeping SQLite as a lightweight embedded option for applications that do not need a separate server.

What go-sqlite3 Does

• Implements the database/sql/driver interface for SQLite3
• Supports prepared statements, transactions, and context-based cancellation
• Allows registering custom SQL functions, aggregators, and collations in Go
• Provides access to SQLite extensions and compile-time options
• Handles concurrent reads with WAL mode and serialized threading

Architecture Overview

go-sqlite3 wraps the SQLite C library using cgo. When imported, it registers itself with Go's database/sql package under the driver name "sqlite3". All SQL operations pass through cgo to the embedded SQLite engine, which reads and writes directly to a local file. Connections are managed by the sql.DB connection pool, and the driver maps Go types to SQLite storage classes.

Self-Hosting & Configuration

• Requires a C compiler (gcc or clang) on the build machine due to cgo
• Set CGO_ENABLED=1 before building; cross-compilation needs a matching C cross-compiler
• Pass SQLite pragma options via the DSN: "file:app.db?_journal_mode=WAL&_busy_timeout=5000"
• Enable or disable SQLite extensions at compile time using build tags
• Use the _loc parameter to control timezone handling for datetime values

Key Features

• Full database/sql compatibility for idiomatic Go usage
• Custom function registration for domain-specific SQL logic
• Support for SQLite's backup API to copy databases while in use
• FTS5 full-text search and JSON1 extension support via build tags
• Connection hooks for tracing, profiling, and authorization callbacks

Comparison with Similar Tools

• modernc.org/sqlite — pure Go, no cgo; go-sqlite3 is faster but requires a C compiler
• crawshaw.io/sqlite — low-level SQLite bindings; go-sqlite3 integrates with database/sql
• GORM + SQLite — ORM layer on top; go-sqlite3 is the underlying driver GORM uses
• pgx (PostgreSQL) — server-based driver; go-sqlite3 is embedded and file-based
• go-duckdb — analytical queries; go-sqlite3 is for transactional and general-purpose use

FAQ

Q: Why does go-sqlite3 require cgo? A: It links against the C implementation of SQLite for full compatibility and performance. If you cannot use cgo, consider modernc.org/sqlite as a pure-Go alternative.

Q: Is go-sqlite3 safe for concurrent use? A: Yes. With WAL journal mode enabled, multiple goroutines can read concurrently while one writes. The sql.DB pool manages connection reuse.

Q: Can I use go-sqlite3 in a Docker container? A: Yes. Include gcc and the SQLite development headers in your build stage. Alpine-based images need musl-dev and gcc installed.

Q: How do I enable full-text search? A: Build with the tag: go build -tags "fts5". This compiles SQLite with FTS5 support.

Sources

• https://github.com/mattn/go-sqlite3
• https://pkg.go.dev/github.com/mattn/go-sqlite3