go.etcd.io/bbolt v1.5.0: Options

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify go.etcd.io/bbolt.Options in pkg:golang/go.etcd.io/bbolt@v1.5.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.etcd.io/bbolt@v1.5.0
Demonstrate these symbols/APIs:
  - go.etcd.io/bbolt.Options
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:955b551a8437b3a14affa8aeda756633fbb46ad9049ec8437777532aa44c273d","contract":["bbolt.DefaultOptions provides non-nil default options with ReadOnly set to false and Timeout set to 0","bbolt.Open with custom Options (Timeout, NoGrowSync, ReadOnly: false) opens database for read-write operations","bbolt.Open with ReadOnly set to true opens database where IsReadOnly returns true, Update returns ErrDatabaseReadOnly, and View reads existing data","bbolt.Open on an already locked database with Timeout option fails after timeout duration"],"goal":"verify go.etcd.io/bbolt.Options in pkg:golang/go.etcd.io/bbolt@v1.5.0","kind":"HOW","packages":["pkg:golang/go.etcd.io/bbolt@v1.5.0"],"schemaVersion":1,"symbols":["go.etcd.io/bbolt.Options"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","executionContext":"go","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","runtime":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/go.etcd.io/bbolt@v1.5.0"],"schemaVersion":1,"subject":"pkg:golang/go.etcd.io/bbolt@v1.5.0","symbols":["go.etcd.io/bbolt.Options"],"verifierAdapter":"golang@1"}

module example.com/bboltoptions

go 1.25.0

require go.etcd.io/bbolt v1.5.0

require golang.org/x/sys v0.45.0 // indirect

github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
go.etcd.io/bbolt v1.5.0 h1:S7GAl7Fxv12yohbwFfIbQCGDWbQbtDGPET4P/bD4lxU=
go.etcd.io/bbolt v1.5.0/go.mod h1:mkltfYE5aUHQxUct9N9V+Kp7aSjFqjgrhcXIS70Lrdk=
golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package bboltoptions_test

import (
	"errors"
	"path/filepath"
	"testing"
	"time"

	bolt "go.etcd.io/bbolt"
)

func TestDefaultOptions(t *testing.T) {
	opts := bolt.DefaultOptions
	if opts == nil {
		t.Fatal("expected DefaultOptions to be non-nil")
	}
	if opts.ReadOnly {
		t.Errorf("expected DefaultOptions.ReadOnly to be false, got true")
	}
	if opts.Timeout != 0 {
		t.Errorf("expected DefaultOptions.Timeout to be 0, got %v", opts.Timeout)
	}
}

func TestOpenWithCustomOptionsReadWrite(t *testing.T) {
	dir := t.TempDir()
	dbPath := filepath.Join(dir, "rw_test.db")

	opts := &bolt.Options{
		Timeout:    1 * time.Second,
		NoGrowSync: false,
		ReadOnly:   false,
	}

	db, err := bolt.Open(dbPath, 0600, opts)
	if err != nil {
		t.Fatalf("failed to open database with custom options: %v", err)
	}
	defer db.Close()

	if db.IsReadOnly() {
		t.Error("expected database to not be read-only")
	}

	bucketName := []byte("settings")
	key := []byte("config_key")
	value := []byte("config_value")

	err = db.Update(func(tx *bolt.Tx) error {
		b, err := tx.CreateBucketIfNotExists(bucketName)
		if err != nil {
			return err
		}
		return b.Put(key, value)
	})
	if err != nil {
		t.Fatalf("Update failed: %v", err)
	}

	err = db.View(func(tx *bolt.Tx) error {
		b := tx.Bucket(bucketName)
		if b == nil {
			t.Fatal("expected bucket to exist")
		}
		got := b.Get(key)
		if string(got) != string(value) {
			t.Fatalf("expected value %q, got %q", value, got)
		}
		return nil
	})
	if err != nil {
		t.Fatalf("View failed: %v", err)
	}
}

func TestOpenWithReadOnlyOption(t *testing.T) {
	dir := t.TempDir()
	dbPath := filepath.Join(dir, "readonly_test.db")

	// Pre-populate database
	dbInit, err := bolt.Open(dbPath, 0600, nil)
	if err != nil {
		t.Fatalf("failed to create database: %v", err)
	}
	bucketName := []byte("records")
	key := []byte("item1")
	val := []byte("data1")
	err = dbInit.Update(func(tx *bolt.Tx) error {
		b, err := tx.CreateBucketIfNotExists(bucketName)
		if err != nil {
			return err
		}
		return b.Put(key, val)
	})
	if err != nil {
		t.Fatalf("initial write failed: %v", err)
	}
	dbInit.Close()

	// Open with ReadOnly: true
	readOnlyOpts := &bolt.Options{
		ReadOnly: true,
		Timeout:  1 * time.Second,
	}

	db, err := bolt.Open(dbPath, 0600, readOnlyOpts)
	if err != nil {
		t.Fatalf("failed to open database in read-only mode: %v", err)
	}
	defer db.Close()

	if !db.IsReadOnly() {
		t.Error("expected db.IsReadOnly() to return true")
	}

	// Update should return ErrDatabaseReadOnly
	err = db.Update(func(tx *bolt.Tx) error {
		b := tx.Bucket(bucketName)
		return b.Put([]byte("item2"), []byte("data2"))
	})
	if !errors.Is(err, bolt.ErrDatabaseReadOnly) {
		t.Fatalf("expected ErrDatabaseReadOnly on Update, got: %v", err)
	}

	// View should still succeed
	err = db.View(func(tx *bolt.Tx) error {
		b := tx.Bucket(bucketName)
		if b == nil {
			t.Fatal("expected bucket to exist")
		}
		got := b.Get(key)
		if string(got) != string(val) {
			t.Fatalf("expected %q, got %q", val, got)
		}
		return nil
	})
	if err != nil {
		t.Fatalf("View in read-only mode failed: %v", err)
	}
}

func TestOpenWithTimeoutOption(t *testing.T) {
	dir := t.TempDir()
	dbPath := filepath.Join(dir, "timeout_test.db")

	// Open first database instance holding exclusive lock
	db1, err := bolt.Open(dbPath, 0600, nil)
	if err != nil {
		t.Fatalf("failed to open initial database: %v", err)
	}
	defer db1.Close()

	// Attempt second open with a short timeout
	timeoutOpts := &bolt.Options{
		Timeout: 50 * time.Millisecond,
	}
	_, err = bolt.Open(dbPath, 0600, timeoutOpts)
	if err == nil {
		t.Fatal("expected error opening already-locked database with timeout, got nil")
	}
	if !errors.Is(err, bolt.ErrTimeout) {
		t.Logf("got timeout error (expected ErrTimeout or timeout related error): %v", err)
	}
}

{
  "schemaVersion": 1,
  "goal": "verify go.etcd.io/bbolt.Options in pkg:golang/go.etcd.io/bbolt@v1.5.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.etcd.io/bbolt@v1.5.0"
  ],
  "symbols": [
    "go.etcd.io/bbolt.Options"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}