Run the local index in WAL mode with a busy timeout (closes #217)

The connection settings were passed as `_journal_mode=`-style
parameters, which the SQLite driver drops without an error, so the
index ran in rollback-journal mode with no busy timeout. `snapshot
list` or `info` reading during a backup could make the backup's next
write fail with "database is locked". Both open paths now pass
`_pragma=` parameters; foreign keys moved there too.

With WAL on, rows committed to the open index can still be in the
-wal file, which a copy of the main file misses. The metadata export
now copies the index with VACUUM INTO, into an empty 0600 file.

The retry after a failed open no longer claims a TRUNCATE recovery; it
retries with the same settings.

Model: opus-5-5

internal/database/database.go

@@ -42,6 +42,10 @@ var schemaFS embed.FS
 // table itself. It is applied before the normal migration loop.
 const bootstrapVersion = 0
 
+// busyTimeoutMsec is how long a connection to the index waits for another
+// connection's lock before failing with "database is locked".
+const busyTimeoutMsec = 10000
+
 // DB represents the Vaultik local index database connection.
 // It uses SQLite to track file metadata, content-defined chunks, and blob associations.
 // The database enables incremental backups by detecting changed files and
@@ -94,10 +98,27 @@ func ParseMigrationVersion(filename string) (int, error) {
 	return version, nil
 }
 
+// indexDSN returns the driver DSN that opens the database at path. The
+// driver runs each _pragma parameter on every connection it opens and drops
+// any parameter it does not know without an error, so a setting written in
+// another form silently does nothing. In WAL mode one connection can write
+// while others read; the busy timeout makes a connection wait for a lock
+// instead of failing at once.
+func indexDSN(path string) string {
+	return fmt.Sprintf(
+		"%s?_pragma=busy_timeout(%d)&_pragma=journal_mode(WAL)"+
+			"&_pragma=synchronous(NORMAL)&_pragma=foreign_keys(1)",
+		path, busyTimeoutMsec)
+}
+
 // New creates a new database connection at the specified path.
-// It creates the schema if needed and configures SQLite with WAL mode for
-// better concurrency. SQLite handles crash recovery automatically when
-// opening a database with journal/WAL files present.
+// It creates the schema if needed. Every connection runs in WAL mode with
+// a busy timeout and foreign keys on (see indexDSN), so a read-only command
+// can read the index while a backup writes to it. Committed rows can sit in
+// the -wal file beside the database until a checkpoint, so a copy of the
+// database file alone may miss them.
+// SQLite handles crash recovery automatically when opening a database with
+// journal/WAL files present.
 // The path parameter can be a file path for persistent storage or ":memory:"
 // for an in-memory database (useful for testing).
 func New(ctx context.Context, path string) (*DB, error) {
@@ -110,11 +131,7 @@ func New(ctx context.Context, path string) (*DB, error) {
 	// First attempt with standard WAL mode
 	log.Debug("Attempting to open database with WAL mode", "path", path)
 
-	conn, err := sql.Open(
-		"sqlite",
-		path+"?_journal_mode=WAL&_synchronous=NORMAL&_busy_timeout=10000"+
-			"&_locking_mode=NORMAL&_foreign_keys=ON",
-	)
+	conn, err := sql.Open("sqlite", indexDSN(path))
 	if err == nil {
 		configureConnPool(conn)
 
@@ -134,7 +151,7 @@ func New(ctx context.Context, path string) (*DB, error) {
 		_ = conn.Close()
 	}
 
-	// If first attempt failed, try with TRUNCATE mode to clear any locks
+	// If the first attempt failed, try once more
 	return openWithRecovery(ctx, path)
 }
 
@@ -147,18 +164,12 @@ func configureConnPool(conn *sql.DB) {
 	conn.SetMaxIdleConns(1)
 }
 
-// finishOpen enables foreign keys, wraps the connection, and applies any
-// pending migrations. On migration failure the connection is closed.
+// finishOpen wraps the connection and applies any pending migrations. On
+// migration failure the connection is closed.
 func finishOpen(ctx context.Context, conn *sql.DB, path string) (*DB, error) {
-	// Enable foreign keys explicitly
-	_, err := conn.ExecContext(ctx, "PRAGMA foreign_keys = ON")
-	if err != nil {
-		log.Warn("Failed to enable foreign keys", "path", path, "error", err)
-	}
-
 	db := &DB{conn: conn, path: path}
 
-	err = applyMigrations(ctx, conn)
+	err := applyMigrations(ctx, conn)
 	if err != nil {
 		_ = conn.Close()
 
@@ -168,21 +179,15 @@ func finishOpen(ctx context.Context, conn *sql.DB, path string) (*DB, error) {
 	return db, nil
 }
 
-// openWithRecovery retries opening the database in TRUNCATE journal mode to
-// clear stale locks, then switches back to WAL mode.
+// openWithRecovery makes a second attempt to open the database, with the
+// same settings, after the first attempt failed, for example because
+// another process held a lock for longer than the busy timeout.
 func openWithRecovery(ctx context.Context, path string) (*DB, error) {
-	log.Info(
-		"Database appears locked, attempting recovery with TRUNCATE mode",
-		"path", path,
-	)
+	log.Info("Database appears locked, retrying open", "path", path)
 
-	conn, err := sql.Open(
-		"sqlite",
-		path+"?_journal_mode=TRUNCATE&_synchronous=NORMAL&_busy_timeout=10000"+
-			"&_foreign_keys=ON",
-	)
+	conn, err := sql.Open("sqlite", indexDSN(path))
 	if err != nil {
-		return nil, fmt.Errorf("opening database in recovery mode: %w", err)
+		return nil, fmt.Errorf("opening database on retry: %w", err)
 	}
 
 	configureConnPool(conn)
@@ -190,7 +195,7 @@ func openWithRecovery(ctx context.Context, path string) (*DB, error) {
 	err = conn.PingContext(ctx)
 	if err != nil {
 		log.Debug(
-			"Failed to ping database in recovery mode, closing",
+			"Failed to ping database on retry, closing",
 			"path", path, "error", err,
 		)
 
@@ -202,16 +207,6 @@ func openWithRecovery(ctx context.Context, path string) (*DB, error) {
 		)
 	}
 
-	log.Debug("Database opened in TRUNCATE mode", "path", path)
-
-	// Switch back to WAL mode
-	log.Debug("Switching database back to WAL mode", "path", path)
-
-	_, err = conn.ExecContext(ctx, "PRAGMA journal_mode=WAL")
-	if err != nil {
-		log.Warn("Failed to switch back to WAL mode", "path", path, "error", err)
-	}
-
 	db, err := finishOpen(ctx, conn, path)
 	if err != nil {
 		return nil, err

internal/database/database_test.go

@@ -120,6 +120,89 @@ func TestDatabaseConcurrentAccess(t *testing.T) {
 	}
 }
 
+// TestNewSetsJournalModeAndBusyTimeout checks that the connection settings
+// New passes reach SQLite. The driver drops a setting it does not recognise
+// without an error, so only reading the value back shows it took effect.
+func TestNewSetsJournalModeAndBusyTimeout(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+
+	db, err := New(ctx, filepath.Join(t.TempDir(), "index.db"))
+	if err != nil {
+		t.Fatalf("failed to create database: %v", err)
+	}
+
+	defer func() { _ = db.Close() }()
+
+	var journalMode string
+
+	err = db.conn.QueryRowContext(ctx, "PRAGMA journal_mode").Scan(&journalMode)
+	if err != nil {
+		t.Fatalf("reading journal_mode: %v", err)
+	}
+
+	if journalMode != "wal" {
+		t.Errorf("journal_mode = %q, want %q", journalMode, "wal")
+	}
+
+	var busyTimeout int
+
+	err = db.conn.QueryRowContext(ctx, "PRAGMA busy_timeout").Scan(&busyTimeout)
+	if err != nil {
+		t.Fatalf("reading busy_timeout: %v", err)
+	}
+
+	if busyTimeout != busyTimeoutMsec {
+		t.Errorf("busy_timeout = %d, want %d", busyTimeout, busyTimeoutMsec)
+	}
+}
+
+// TestNewWriteSucceedsWhileAnotherHandleReads opens the same index twice,
+// as a read-only command does while a backup runs, and checks that a write
+// on one handle commits while the other is in the middle of a read.
+func TestNewWriteSucceedsWhileAnotherHandleReads(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	dbPath := filepath.Join(t.TempDir(), "index.db")
+
+	reader, err := New(ctx, dbPath)
+	if err != nil {
+		t.Fatalf("failed to open reading handle: %v", err)
+	}
+
+	defer func() { _ = reader.Close() }()
+
+	writer, err := New(ctx, dbPath)
+	if err != nil {
+		t.Fatalf("failed to open writing handle: %v", err)
+	}
+
+	defer func() { _ = writer.Close() }()
+
+	// The read lock taken by the SELECT is held until the transaction ends.
+	readTx, err := reader.BeginTx(ctx, nil)
+	if err != nil {
+		t.Fatalf("beginning read transaction: %v", err)
+	}
+
+	defer func() { _ = readTx.Rollback() }()
+
+	var count int
+
+	err = readTx.QueryRowContext(ctx, "SELECT COUNT(*) FROM chunks").Scan(&count)
+	if err != nil {
+		t.Fatalf("reading chunks: %v", err)
+	}
+
+	_, err = writer.ExecWithLog(ctx,
+		"INSERT INTO chunks (chunk_hash, size) VALUES (?, ?)", "hash", 1024)
+	if err != nil {
+		t.Fatalf("write while another handle reads: %v", err)
+	}
+}
+
 func TestParseMigrationVersion(t *testing.T) {
 	t.Parallel()