Skip to content
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,22 @@ Pass the key in the DSN, `sql.Open("sqlite3", "file:test.db?_crypto_key=secret")
- With a shared cache (`cache=shared`), a connection with a wrong key or no key can read a database that another connection of the process has opened with the right key.
- Backups between an encrypted and a plain database fail; use `sqlcipher_export` to copy between them.

## Deterministic date and time

For results that do not depend on when or where a query runs, as when several replicas execute the same statements:

- `vfs=nocurrenttime` in the DSN uses a copy of the default VFS without the current time, so `'now'`, date and time functions called without a time value, and the `CURRENT_*` keywords give NULL.
- The `sqlite_omit_localtime` build tag removes the `localtime` and `utc` modifiers, which depend on the time zone of the host; they give NULL as well. The tag only changes the bundled SQLite, so with the `libsqlite3` tag, opening a database fails unless the system SQLite is built with `SQLITE_OMIT_LOCALTIME`.

Without a current time, a column declared `NOT NULL DEFAULT CURRENT_TIMESTAMP` cannot get its default, and inserts that rely on it fail. SQLite also skips the profile callbacks of statements, so `sqlite_trace` profile events and SQLCipher's `PRAGMA cipher_profile` report nothing.

## Changes from go-sqlite3

- `sqlite3-binding.c`, `sqlite3-binding.h` and `sqlite3ext.h` are generated from the SQLCipher sources. The `upgrade` tool, which replaces them with the official SQLite amalgamation, is removed.
- The LibTomCrypt sources SQLCipher needs: the `tomcrypt*.h` headers and the `.c` files whose names do not start with `sqlite3`.
- `sqlite3.go` defines the SQLCipher compile options, turns off the default logging of SQLCipher to stderr, and adds the `_crypto_key` DSN parameter.
- `Exec` without arguments reports missing arguments again, which go-sqlite3 v1.14.52 does not.
- `sqlite3_nocurrenttime.go` adds the `nocurrenttime` VFS, and `sqlite3_opt_omit_localtime.go` the `sqlite_omit_localtime` tag.
- `sqlite3_opt_icu.go` adds the libraries that a static link of ICU needs.
- The CIFuzz workflow, which builds the OSS-Fuzz project of go-sqlite3, is removed.

Expand Down
33 changes: 29 additions & 4 deletions sqlite3.go
Original file line number Diff line number Diff line change
Expand Up @@ -381,6 +381,14 @@ func Version() (libVersion string, libVersionNumber int, sourceID string) {
return libVersion, libVersionNumber, sourceID
}

// compileOptionUsed reports whether SQLite was built with the option, named
// without the SQLITE_ prefix.
func compileOptionUsed(name string) bool {
cname := C.CString(name)
defer C.free(unsafe.Pointer(cname))
return C.sqlite3_compileoption_used(cname) != 0
}

const (
// used by authorizer and pre_update_hook
SQLITE_DELETE = C.SQLITE_DELETE
Expand Down Expand Up @@ -1182,6 +1190,11 @@ func (c *SQLiteConn) begin(ctx context.Context) (driver.Tx, error) {
// _crypto_key=XXX
// Specify the SQLCipher encryption key, as text without quotes.
//
// vfs=nocurrenttime
// Use a copy of the default VFS without the current time: 'now', date and
// time functions without a time value and the CURRENT_* keywords give NULL,
// so results do not depend on when a query runs.
//
// _auto_vacuum=X | _vacuum=X
// 0 | none - Auto Vacuum disabled
// 1 | full - Auto Vacuum FULL
Expand Down Expand Up @@ -1236,6 +1249,11 @@ func (d *SQLiteDriver) Open(dsn string) (driver.Conn, error) {
if C.sqlite3_threadsafe() == 0 {
return nil, errors.New("sqlite library was not compiled for thread-safe operation")
}
// The tag only changes the bundled SQLite: a system SQLite linked with the
// libsqlite3 tag may still have the localtime and utc modifiers.
if omitLocaltime && !compileOptionUsed("OMIT_LOCALTIME") {
return nil, errors.New("sqlite3: the sqlite_omit_localtime tag needs SQLite built with SQLITE_OMIT_LOCALTIME")
}

var pkey string

Expand Down Expand Up @@ -1322,10 +1340,7 @@ func (d *SQLiteDriver) Open(dsn string) (driver.Conn, error) {
if cryptoKey != "" {
// Without SQLCipher, as with the libsqlite3 tag and a plain system SQLite,
// PRAGMA key does nothing and the database would be written in plain text.
hasCodec := C.CString("HAS_CODEC")
used := C.sqlite3_compileoption_used(hasCodec)
C.free(unsafe.Pointer(hasCodec))
if used == 0 {
if !compileOptionUsed("HAS_CODEC") {
return nil, errors.New("sqlite3: _crypto_key needs SQLite built with SQLCipher")
}
// A NUL would cut the PRAGMA key statement short, and the syntax error
Expand Down Expand Up @@ -1634,9 +1649,19 @@ func (d *SQLiteDriver) Open(dsn string) (driver.Conn, error) {
stmtCacheSize = iv
}

// SQLite uses the last vfs parameter of a file: URI, while vfsName
// would be the first one.
if len(params["vfs"]) > 1 {
return nil, errors.New("sqlite3: more than one vfs parameter")
}
if val := params.Get("vfs"); val != "" {
vfsName = val
}
if vfsName == noCurrentTimeVFS {
if err := registerNoCurrentTimeVFS(); err != nil {
return nil, err
}
}

if !strings.HasPrefix(dsn, "file:") {
dsn = dsn[:pos]
Expand Down
69 changes: 69 additions & 0 deletions sqlite3_nocurrenttime.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
//go:build cgo

package sqlite3

/*
#ifndef USE_LIBSQLITE3
#include "sqlite3-binding.h"
#else
#include <sqlite3.h>
#endif
static sqlite3_vfs noCurrentTimeVfs;
static int noCurrentTime(sqlite3_vfs *vfs, double *now) {
*now = 0;
return SQLITE_ERROR;
}
static int noCurrentTimeInt64(sqlite3_vfs *vfs, sqlite3_int64 *now) {
*now = 0;
return SQLITE_ERROR;
}
// Register a copy of the default VFS named "nocurrenttime" whose current time
// is unavailable. The copy shares the methods and pAppData of the default VFS,
// which suits the unix and win32 VFSes, but not a default VFS that checks its
// own name or extends sqlite3_vfs.
static int _sqlite3_register_no_current_time_vfs(void) {
sqlite3_vfs *base = sqlite3_vfs_find(0);
if (base == 0) {
return SQLITE_ERROR;
}
noCurrentTimeVfs = *base;
noCurrentTimeVfs.zName = "nocurrenttime";
noCurrentTimeVfs.pNext = 0;
noCurrentTimeVfs.xCurrentTime = noCurrentTime;
if (noCurrentTimeVfs.iVersion >= 2) {
noCurrentTimeVfs.xCurrentTimeInt64 = noCurrentTimeInt64;
}
return sqlite3_vfs_register(&noCurrentTimeVfs, 0);
}
*/
import "C"

import (
"fmt"
"sync"
)

// noCurrentTimeVFS is the VFS that the DSN parameter vfs=nocurrenttime selects.
// Date and time functions get no current time from it, so 'now', date and time
// functions without a time value and the CURRENT_* keywords give NULL, and
// their results do not depend on when a query runs. Without a current time,
// SQLite also skips the profile callbacks of statements.
const noCurrentTimeVFS = "nocurrenttime"

var (
noCurrentTimeOnce sync.Once
noCurrentTimeErr error
)

func registerNoCurrentTimeVFS() error {
noCurrentTimeOnce.Do(func() {
if rv := C._sqlite3_register_no_current_time_vfs(); rv != C.SQLITE_OK {
noCurrentTimeErr = fmt.Errorf("sqlite3: registering the %s VFS failed: %d", noCurrentTimeVFS, rv)
}
})
return noCurrentTimeErr
}
70 changes: 70 additions & 0 deletions sqlite3_nocurrenttime_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
//go:build cgo

package sqlite3

import (
"database/sql"
"path/filepath"
"testing"
)

func TestNoCurrentTimeVFS(t *testing.T) {
path := filepath.Join(t.TempDir(), "nocurrenttime.db")
db, err := sql.Open("sqlite3", "file:"+path+"?vfs=nocurrenttime&_journal_mode=WAL")
if err != nil {
t.Fatal(err)
}
defer db.Close()

// Files are read and written as with the default VFS.
if _, err := db.Exec("CREATE TABLE t (v TEXT); INSERT INTO t VALUES (date('2000-01-02'))"); err != nil {
t.Fatal(err)
}
var v string
if err := db.QueryRow("SELECT v FROM t").Scan(&v); err != nil || v != "2000-01-02" {
t.Fatalf("read back %q, err %v", v, err)
}

for _, q := range []struct {
query string
args []any
}{
{"SELECT date('now')", nil},
{"SELECT date(?)", []any{"now"}},
{"SELECT date('n' || 'ow')", nil},
{"SELECT datetime()", nil},
{"SELECT julianday('now')", nil},
{"SELECT unixepoch()", nil},
{"SELECT strftime('%Y')", nil},
{"SELECT CURRENT_TIMESTAMP", nil},
} {
var got sql.NullString
if err := db.QueryRow(q.query, q.args...).Scan(&got); err != nil {
t.Errorf("%s: %v", q.query, err)
} else if got.Valid {
t.Errorf("%s: got the current time %q, want NULL", q.query, got.String)
}
}

plain, err := sql.Open("sqlite3", ":memory:")
if err != nil {
t.Fatal(err)
}
defer plain.Close()
var now sql.NullString
if err := plain.QueryRow("SELECT date('now')").Scan(&now); err != nil || !now.Valid {
t.Fatalf("the default VFS has no current time: %q, err %v", now.String, err)
}
}

func TestMoreThanOneVFS(t *testing.T) {
// SQLite would open this with the last one, the default VFS.
db, err := sql.Open("sqlite3", "file:"+filepath.Join(t.TempDir(), "two.db")+"?vfs=nocurrenttime&vfs=unix")
if err != nil {
t.Fatal(err)
}
defer db.Close()
if err := db.Ping(); err == nil {
t.Fatal("opened a database with two vfs parameters")
}
}
13 changes: 13 additions & 0 deletions sqlite3_opt_omit_localtime.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
//go:build sqlite_omit_localtime

package sqlite3

// Without the localtime and utc modifiers, date and time functions do not
// depend on the time zone of the host.

/*
#cgo CFLAGS: -DSQLITE_OMIT_LOCALTIME
*/
import "C"

const omitLocaltime = true
22 changes: 22 additions & 0 deletions sqlite3_opt_omit_localtime_libsqlite3_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
//go:build cgo && sqlite_omit_localtime && libsqlite3

package sqlite3

import (
"database/sql"
"testing"
)

func TestOmitLocaltimeWithoutTheOption(t *testing.T) {
if compileOptionUsed("OMIT_LOCALTIME") {
t.Skip("the system SQLite is built with SQLITE_OMIT_LOCALTIME")
}
db, err := sql.Open("sqlite3", ":memory:")
if err != nil {
t.Fatal(err)
}
defer db.Close()
if err := db.Ping(); err == nil {
t.Fatal("opened a database with the sqlite_omit_localtime tag and a SQLite that has localtime")
}
}
5 changes: 5 additions & 0 deletions sqlite3_opt_omit_localtime_omit.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
//go:build !sqlite_omit_localtime

package sqlite3

const omitLocaltime = false
24 changes: 24 additions & 0 deletions sqlite3_opt_omit_localtime_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
//go:build cgo && sqlite_omit_localtime && !libsqlite3

package sqlite3

import (
"database/sql"
"testing"
)

func TestOmitLocaltime(t *testing.T) {
db, err := sql.Open("sqlite3", ":memory:")
if err != nil {
t.Fatal(err)
}
defer db.Close()
for _, modifier := range []string{"localtime", "utc"} {
var got sql.NullString
if err := db.QueryRow("SELECT datetime('2000-01-01 12:00:00', ?)", modifier).Scan(&got); err != nil {
t.Errorf("%s: %v", modifier, err)
} else if got.Valid {
t.Errorf("%s: got %q, want NULL", modifier, got.String)
}
}
}
Loading