go.etcd.io/bbolt v1.3.9: 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.3.9
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.etcd.io/bbolt@v1.3.9
Demonstrate these symbols/APIs:
  - go.etcd.io/bbolt.Options
Required runtime conditions:
  - ecosystem: golang
  - language: go
  - packageManager: go@1.26.6
  - runtime: go@1.26.6

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:15a9ca164f14ab086697774a2d13c00cd0f39b31db9742eadb21d72bd6505f1d","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.3.9","kind":"HOW","packages":["pkg:golang/go.etcd.io/bbolt@v1.3.9"],"schemaVersion":1,"symbols":["go.etcd.io/bbolt.Options"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/go.etcd.io/bbolt@v1.3.9"],"schemaVersion":1,"subject":"pkg:golang/go.etcd.io/bbolt@v1.3.9","symbols":["go.etcd.io/bbolt.Options"],"verifierAdapter":"golang@1"}

module example.com/bbolt-options

go 1.22

require go.etcd.io/bbolt v1.3.9

require golang.org/x/sys v0.4.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.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
go.etcd.io/bbolt v1.3.9 h1:8x7aARPEXiXbHmtUwAIv7eV2fQFHrLLavdiJ3uzJXoI=
go.etcd.io/bbolt v1.3.9/go.mod h1:zaO32+Ti0PK1ivdPtgMESzuzL2VPoIG1PCQNvOdo/dE=
golang.org/x/sync v0.5.0 h1:60k92dhOjHxJkrqnwsfl8KuaHbn/5dl0lUPUklKo3qE=
golang.org/x/sync v0.5.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
golang.org/x/sys v0.4.0 h1:Zr2JFtRQNX3BCZ8YtxRE9hNJYC8J6I1MVbMg6owUp18=
golang.org/x/sys v0.4.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package options

import (
	"time"

	"go.etcd.io/bbolt"
)

// OpenWithTimeout opens a database at the given path with a specified timeout.
func OpenWithTimeout(path string, timeout time.Duration) (*bbolt.DB, error) {
	opts := &bbolt.Options{
		Timeout: timeout,
	}
	return bbolt.Open(path, 0600, opts)
}

// OpenReadOnly opens a database at the given path in read-only mode.
func OpenReadOnly(path string, timeout time.Duration) (*bbolt.DB, error) {
	opts := &bbolt.Options{
		Timeout:  timeout,
		ReadOnly: true,
	}
	return bbolt.Open(path, 0600, opts)
}

{
  "schemaVersion": 1,
  "goal": "verify go.etcd.io/bbolt.Options in pkg:golang/go.etcd.io/bbolt@v1.3.9",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.etcd.io/bbolt@v1.3.9"
  ],
  "symbols": [
    "go.etcd.io/bbolt.Options"
  ],
  "runtimeConditions": {
    "ecosystem": "golang",
    "language": "go",
    "packageManager": "go@1.26.6",
    "runtime": "go@1.26.6"
  }
}

package main

import (
	"errors"
	"fmt"
	"os"
	"path/filepath"
	"time"

	"go.etcd.io/bbolt"
)

func main() {
	if err := testDefaultOptions(); err != nil {
		fmt.Fprintf(os.Stderr, "testDefaultOptions failed: %v\n", err)
		os.Exit(1)
	}
	if err := testCustomOptionsReadWrite(); err != nil {
		fmt.Fprintf(os.Stderr, "testCustomOptionsReadWrite failed: %v\n", err)
		os.Exit(1)
	}
	if err := testReadOnlyOptions(); err != nil {
		fmt.Fprintf(os.Stderr, "testReadOnlyOptions failed: %v\n", err)
		os.Exit(1)
	}
	if err := testTimeoutOnLockedDB(); err != nil {
		fmt.Fprintf(os.Stderr, "testTimeoutOnLockedDB failed: %v\n", err)
		os.Exit(1)
	}
}

func testDefaultOptions() error {
	if bbolt.DefaultOptions == nil {
		return errors.New("bbolt.DefaultOptions is nil")
	}
	if bbolt.DefaultOptions.ReadOnly != false {
		return fmt.Errorf("expected DefaultOptions.ReadOnly=false, got %v", bbolt.DefaultOptions.ReadOnly)
	}
	if bbolt.DefaultOptions.Timeout != 0 {
		return fmt.Errorf("expected DefaultOptions.Timeout=0, got %v", bbolt.DefaultOptions.Timeout)
	}
	return nil
}

func testCustomOptionsReadWrite() error {
	dir, err := os.MkdirTemp("", "bbolt-contract-*")
	if err != nil {
		return err
	}
	defer os.RemoveAll(dir)

	dbPath := filepath.Join(dir, "test.db")
	opts := &bbolt.Options{
		Timeout:    2 * time.Second,
		NoGrowSync: true,
		ReadOnly:   false,
	}

	db, err := bbolt.Open(dbPath, 0600, opts)
	if err != nil {
		return fmt.Errorf("bbolt.Open failed: %w", err)
	}
	defer db.Close()

	return db.Update(func(tx *bbolt.Tx) error {
		b, err := tx.CreateBucketIfNotExists([]byte("data"))
		if err != nil {
			return err
		}
		return b.Put([]byte("key"), []byte("value"))
	})
}

func testReadOnlyOptions() error {
	dir, err := os.MkdirTemp("", "bbolt-contract-*")
	if err != nil {
		return err
	}
	defer os.RemoveAll(dir)

	dbPath := filepath.Join(dir, "test.db")

	initDB, err := bbolt.Open(dbPath, 0600, nil)
	if err != nil {
		return fmt.Errorf("init db open failed: %w", err)
	}
	err = initDB.Update(func(tx *bbolt.Tx) error {
		b, err := tx.CreateBucketIfNotExists([]byte("data"))
		if err != nil {
			return err
		}
		return b.Put([]byte("key"), []byte("value"))
	})
	initDB.Close()
	if err != nil {
		return fmt.Errorf("init db update failed: %w", err)
	}

	roOpts := &bbolt.Options{
		ReadOnly: true,
		Timeout:  2 * time.Second,
	}
	roDB, err := bbolt.Open(dbPath, 0600, roOpts)
	if err != nil {
		return fmt.Errorf("read-only bbolt.Open failed: %w", err)
	}
	defer roDB.Close()

	if !roDB.IsReadOnly() {
		return errors.New("expected roDB.IsReadOnly() to be true")
	}

	err = roDB.Update(func(tx *bbolt.Tx) error {
		return nil
	})
	if !errors.Is(err, bbolt.ErrDatabaseReadOnly) {
		return fmt.Errorf("expected ErrDatabaseReadOnly, got %v", err)
	}

	return roDB.View(func(tx *bbolt.Tx) error {
		b := tx.Bucket([]byte("data"))
		if b == nil {
			return errors.New("bucket 'data' not found")
		}
		val := b.Get([]byte("key"))
		if string(val) != "value" {
			return fmt.Errorf("expected value 'value', got %q", string(val))
		}
		return nil
	})
}

func testTimeoutOnLockedDB() error {
	dir, err := os.MkdirTemp("", "bbolt-contract-*")
	if err != nil {
		return err
	}
	defer os.RemoveAll(dir)

	dbPath := filepath.Join(dir, "test.db")

	primaryDB, err := bbolt.Open(dbPath, 0600, &bbolt.Options{Timeout: 2 * time.Second})
	if err != nil {
		return fmt.Errorf("primary bbolt.Open failed: %w", err)
	}
	defer primaryDB.Close()

	secondOpts := &bbolt.Options{
		Timeout: 100 * time.Millisecond,
	}
	_, err = bbolt.Open(dbPath, 0600, secondOpts)
	if !errors.Is(err, bbolt.ErrTimeout) {
		return fmt.Errorf("expected ErrTimeout, got %v", err)
	}
	return nil
}