README
¶
sqlcipher
A database/sql driver for SQLCipher —
SQLite with transparent at-rest encryption — shipped as a single Go package with
the C amalgamation vendored in. No submodules, no external sqlite install.
import sqlcipher "github.com/aquaticcalf/sqlcipher"
db, err := sqlcipher.Open(sqlcipher.Options{
Path: "app.db",
Key: "passphrase", // omit for plain SQLite behavior
})
Or through plain database/sql:
db, err := sql.Open("sqlcipher", "file:app.db?_cipher_key=secret&_pragma=busy_timeout(5000)")
Features
- Full
database/sqlsupport: queries, parameters, transactions, named args - Multi-statement scripts when executing without parameters
- Encryption is policy, not a different stack — same driver with or without a key
PRAGMApassthrough via DSN (_pragma=busy_timeout(5000)) orOptions.Pragmas- FTS5 and math functions compiled in
Requirements
- A C toolchain (gcc/clang)
- OpenSSL development headers at build time;
libcryptoas a dynamic runtime dependency
Upgrading the C sources
The amalgamation is generated from pinned SQLCipher releases:
./gen.sh # maintainers only; clones upstream/ and regenerates sqlite3.{c,h}
License
SQLCipher is BSD-licensed (see LICENSE.md); the SQLite amalgamation it builds from is public domain.
Documentation
¶
Overview ¶
Package sqlcipher is a database/sql driver for SQLCipher — SQLite with transparent at-rest encryption — built on a vendored SQLCipher amalgamation compiled into the final application via cgo.
Quick start:
import sqlcipher "github.com/aquaticcalf/sqlcipher"
db, err := sqlcipher.Open(sqlcipher.Options{
Path: "app.db",
Key: "passphrase-or-raw-hex-key",
})
Or through database/sql directly:
db, err := sql.Open("sqlcipher", "file:app.db?_cipher_key=secret&_pragma=busy_timeout(5000)")
Encryption is policy, not a different stack: with no key configured the driver behaves exactly like plain SQLite running inside SQLCipher.
Provenance of the vendored C sources (regenerate with gen.sh): the amalgamation is generated from SQLCipher v4.18.0 community (SQLite baseline 3.53.4, upstream commit 63697beb0fafcb61faa7a3e6fd267036548ab11b) and committed here, so consumers need no submodules. Build requirements: a C toolchain and OpenSSL development headers; libcrypto remains a dynamic runtime dependency.
Index ¶
Constants ¶
const DriverName = "sqlcipher"
DriverName is the database/sql registration name.
Variables ¶
This section is empty.
Functions ¶
func ApplyKey ¶
ApplyKey returns the PRAGMA statement applying an encryption passphrase. The passphrase is single-quote escaped; raw hex keys may be supplied by the caller using SQLCipher blob syntax x'<64 hex chars>' verbatim.
func BuildDSN ¶
BuildDSN resolves the connection target and attaches the internal _cipher_key and _pragma parameters.
func CipherAvailable ¶
CipherAvailable reports whether the opened database is running SQLCipher (codec present) rather than plain SQLite.
Types ¶
type Error ¶
Error is a SQLite error. Message text matches upstream SQLite exactly (e.g. "database is locked").
type Options ¶
type Options struct {
// Path is the database file path (or :memory:, file: URI, etc).
Path string
// ConnString overrides Path when set; passed through verbatim apart
// from the internal _cipher_key and _pragma parameters.
ConnString string
// Key enables SQLCipher at-rest encryption when non-empty. Accepts
// a passphrase, or raw hex keys in SQLCipher blob syntax
// x'<64 hex chars>' verbatim. Applied as the first statement on
// every physical connection.
Key string
// Pragmas are applied after the key, in order. Entries use the form
// "name(value)" or "name", e.g. "busy_timeout(5000)".
Pragmas []string
}
Options configures a SQLCipher connection.
Source Files