sqlcipher

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/sql support: 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
• PRAGMA passthrough via DSN (_pragma=busy_timeout(5000)) or Options.Pragmas
• FTS5 and math functions compiled in

Requirements

• A C toolchain (gcc/clang)
• OpenSSL development headers at build time; libcrypto as 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
• func ApplyKey(key string) string
• func BuildDSN(opts Options) (string, error)
• func CipherAvailable(db *sql.DB) bool
• func Open(ctx context.Context, opts Options) (*sql.DB, error)
• func Version() string
• type Driver
  • func (d *Driver) Open(dsn string) (driver.Conn, error)
• type Error
  • func (e *Error) Error() string
  • func (e *Error) ErrorCode() int
• type Options

Constants

const DriverName = "sqlcipher"

DriverName is the database/sql registration name.

Functions

func ApplyKey

func ApplyKey(key string) string

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

func BuildDSN(opts Options) (string, error)

BuildDSN resolves the connection target and attaches the internal _cipher_key and _pragma parameters.

func CipherAvailable

func CipherAvailable(db *sql.DB) bool

CipherAvailable reports whether the opened database is running SQLCipher (codec present) rather than plain SQLite.

func Open

func Open(ctx context.Context, opts Options) (*sql.DB, error)

Open connects to the database described by opts and pings it.

func Version

func Version() string

Version returns the underlying SQLite library version string.

Types

type Driver

type Driver struct{}

Driver is the SQLCipher-backed database/sql driver.

func (*Driver) Open

func (d *Driver) Open(dsn string) (driver.Conn, error)

Open implements driver.Driver.

type Error

type Error struct {
	Code int
	Msg  string
}

Error is a SQLite error. Message text matches upstream SQLite exactly (e.g. "database is locked").

func (*Error) Error

func (e *Error) Error() string

func (*Error) ErrorCode

func (e *Error) ErrorCode() int

ErrorCode returns the raw SQLite result code.

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.