{"id":35672394,"url":"https://github.com/bborbe/boltkv","last_synced_at":"2026-01-05T19:04:09.886Z","repository":{"id":216443846,"uuid":"741349982","full_name":"bborbe/boltkv","owner":"bborbe","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-23T17:47:00.000Z","size":7397,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-23T20:48:17.536Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bborbe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-01-10T08:02:46.000Z","updated_at":"2025-07-23T17:47:04.000Z","dependencies_parsed_at":"2024-01-18T16:39:41.942Z","dependency_job_id":"80fb006e-8815-4ab5-9ea5-db67bb19fc9a","html_url":"https://github.com/bborbe/boltkv","commit_stats":null,"previous_names":["bborbe/boltkv"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/bborbe/boltkv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bborbe%2Fboltkv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bborbe%2Fboltkv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bborbe%2Fboltkv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bborbe%2Fboltkv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bborbe","download_url":"https://codeload.github.com/bborbe/boltkv/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bborbe%2Fboltkv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28218052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-05T02:00:06.358Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-05T19:02:20.912Z","updated_at":"2026-01-05T19:04:09.877Z","avatar_url":"https://github.com/bborbe.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BoltKV\n\nA Go library that implements the common [`github.com/bborbe/kv`](https://github.com/bborbe/kv) interfaces for BoltDB ([go.etcd.io/bbolt](https://go.etcd.io/bbolt)). This provides a standardized key-value store interface while maintaining access to BoltDB-specific functionality through extended methods.\n\n## Features\n\n- **Standard KV Interface**: Implements `github.com/bborbe/kv` interfaces for consistent usage across different key-value stores\n- **BoltDB Extensions**: Access underlying BoltDB types (`*bolt.DB`, `*bolt.Tx`, `*bolt.Bucket`, `*bolt.Cursor`) through extended interfaces\n- **Multiple Database Creation Options**: Create databases from files, directories, or temporary locations\n- **Transaction State Management**: Built-in transaction nesting prevention and state tracking\n- **Bucket Caching**: Efficient bucket management with caching during transactions\n- **Forward and Reverse Iteration**: Support for both iteration directions\n- **CLI Tools**: Command-line utilities for database management\n\n## Installation\n\n```bash\ngo get github.com/bborbe/boltkv\n```\n\n## Quick Start\n\n### Basic Usage\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n\n    \"github.com/bborbe/boltkv\"\n    \"github.com/bborbe/kv\"\n)\n\nfunc main() {\n    ctx := context.Background()\n    \n    // Open database\n    db, err := boltkv.OpenFile(ctx, \"my-database.db\")\n    if err != nil {\n        log.Fatal(err)\n    }\n    defer db.Close(ctx)\n    \n    // Start transaction\n    err = db.Update(ctx, func(ctx context.Context, tx kv.Tx) error {\n        // Create or open bucket\n        bucket, err := tx.CreateBucketIfNotExists(ctx, []byte(\"my-bucket\"))\n        if err != nil {\n            return err\n        }\n        \n        // Set key-value pair\n        return bucket.Put(ctx, []byte(\"key\"), []byte(\"value\"))\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    \n    // Read value\n    err = db.View(ctx, func(ctx context.Context, tx kv.Tx) error {\n        bucket, err := tx.Bucket(ctx, []byte(\"my-bucket\"))\n        if err != nil {\n            return err\n        }\n        \n        value, err := bucket.Get(ctx, []byte(\"key\"))\n        if err != nil {\n            return err\n        }\n        \n        fmt.Printf(\"Value: %s\\n\", value)\n        return nil\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\n### Database Creation Options\n\n```go\n// Create from file path\ndb, err := boltkv.OpenFile(ctx, \"/path/to/database.db\")\n\n// Create from directory (creates bolt.db inside)\ndb, err := boltkv.OpenDir(ctx, \"/path/to/directory\")\n\n// Create temporary database\ndb, err := boltkv.OpenTemp(ctx)\n\n// With custom options\ndb, err := boltkv.OpenFile(ctx, \"database.db\", func(opts *bolt.Options) {\n    opts.ReadOnly = true\n    opts.Timeout = time.Second * 10\n})\n```\n\n### Accessing BoltDB-Specific Features\n\n```go\n// Access underlying BoltDB types\nerr = db.Update(ctx, func(ctx context.Context, tx kv.Tx) error {\n    // Cast to extended interfaces for BoltDB access\n    boltTx := tx.(boltkv.Tx).Tx()          // Get *bolt.Tx\n    boltDB := db.(boltkv.DB).DB()          // Get *bolt.DB\n    \n    bucket, err := tx.CreateBucketIfNotExists(ctx, []byte(\"bucket\"))\n    if err != nil {\n        return err\n    }\n    \n    boltBucket := bucket.(boltkv.Bucket).Bucket()  // Get *bolt.Bucket\n    \n    // Use BoltDB-specific functionality\n    return boltBucket.ForEach(func(k, v []byte) error {\n        fmt.Printf(\"Key: %s, Value: %s\\n\", k, v)\n        return nil\n    })\n})\n```\n\n### Iteration\n\n```go\nerr = db.View(ctx, func(ctx context.Context, tx kv.Tx) error {\n    bucket, err := tx.Bucket(ctx, []byte(\"my-bucket\"))\n    if err != nil {\n        return err\n    }\n    \n    // Forward iteration\n    return bucket.ForEach(ctx, func(key, value []byte) error {\n        fmt.Printf(\"Key: %s, Value: %s\\n\", key, value)\n        return nil\n    })\n})\n\n// Reverse iteration\nerr = db.View(ctx, func(ctx context.Context, tx kv.Tx) error {\n    bucket, err := tx.Bucket(ctx, []byte(\"my-bucket\"))\n    if err != nil {\n        return err\n    }\n    \n    return bucket.ForEachReverse(ctx, func(key, value []byte) error {\n        fmt.Printf(\"Key: %s, Value: %s\\n\", key, value)\n        return nil\n    })\n})\n```\n\n## CLI Tools\n\nBoltKV includes several command-line utilities for database management:\n\n### Bucket Management\n```bash\n# List all buckets\nbolt-bucket-list -database=/path/to/db.bolt\n\n# Delete a bucket\nbolt-bucket-delete -database=/path/to/db.bolt -bucket=bucket-name\n```\n\n### Key-Value Operations\n```bash\n# Set a value\nbolt-value-set -database=/path/to/db.bolt -bucket=bucket-name -key=mykey -value=myvalue\n\n# Get a value  \nbolt-value-get -database=/path/to/db.bolt -bucket=bucket-name -key=mykey\n\n# List all keys in a bucket\nbolt-value-list -database=/path/to/db.bolt -bucket=bucket-name\n\n# Delete a key\nbolt-value-delete -database=/path/to/db.bolt -bucket=bucket-name -key=mykey\n```\n\n## Architecture\n\n### Core Components\n- **`boltkv_db.go`** - Database connection and lifecycle management\n- **`boltkv_tx.go`** - Transaction handling with bucket caching  \n- **`boltkv_bucket.go`** - Key-value operations within buckets\n- **`boltkv_iterator.go`** - Forward iteration support\n- **`boltkv_iterator-reverse.go`** - Reverse iteration support\n\n### Key Design Patterns\n- **Interface Extension**: Implements `github.com/bborbe/kv` interfaces while adding BoltDB-specific access methods\n- **Transaction State Management**: Uses context keys to track transaction state and prevent nesting\n- **Bucket Caching**: Transactions cache opened buckets with mutex protection for efficiency\n- **Factory Methods**: Multiple database creation options for different use cases\n\n## Dependencies\n\n- **[go.etcd.io/bbolt](https://go.etcd.io/bbolt)** - BoltDB embedded key-value database\n- **[github.com/bborbe/kv](https://github.com/bborbe/kv)** - Common key-value store interfaces\n- **[github.com/bborbe/errors](https://github.com/bborbe/errors)** - Enhanced error handling\n- **[github.com/bborbe/service](https://github.com/bborbe/service)** - Service framework\n\n## Testing\n\nThe library includes comprehensive tests and passes the shared test suites from `github.com/bborbe/kv` to ensure proper interface implementation.\n\n```bash\n# Run all tests\nmake test\n\n# Run tests with coverage\ngo test -race -cover ./...\n\n# Run specific test package\ngo test ./path/to/package\n```\n\n## License\n\nThis project is licensed under the BSD-style license. See the LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please ensure all tests pass and follow the existing code style.\n\n```bash\n# Run the full development workflow\nmake precommit\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbborbe%2Fboltkv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbborbe%2Fboltkv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbborbe%2Fboltkv/lists"}