{"id":34134518,"url":"https://github.com/bborbe/badgerkv","last_synced_at":"2026-03-11T02:01:53.268Z","repository":{"id":216599573,"uuid":"741350096","full_name":"bborbe/badgerkv","owner":"bborbe","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-07T02:31:11.000Z","size":9123,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-07T13:36:03.912Z","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-01-10T08:03:05.000Z","updated_at":"2026-02-07T02:31:15.000Z","dependencies_parsed_at":"2025-12-06T10:00:58.231Z","dependency_job_id":null,"html_url":"https://github.com/bborbe/badgerkv","commit_stats":null,"previous_names":["bborbe/badgerkv"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/bborbe/badgerkv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bborbe%2Fbadgerkv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bborbe%2Fbadgerkv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bborbe%2Fbadgerkv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bborbe%2Fbadgerkv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bborbe","download_url":"https://codeload.github.com/bborbe/badgerkv/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bborbe%2Fbadgerkv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30367799,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T21:41:54.280Z","status":"online","status_checked_at":"2026-03-11T02:00:07.027Z","response_time":84,"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":"2025-12-15T01:25:09.482Z","updated_at":"2026-03-11T02:01:53.260Z","avatar_url":"https://github.com/bborbe.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BadgerKV\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/bborbe/badgerkv.svg)](https://pkg.go.dev/github.com/bborbe/badgerkv)\n[![Go Report Card](https://goreportcard.com/badge/github.com/bborbe/badgerkv)](https://goreportcard.com/report/github.com/bborbe/badgerkv)\n\nBadgerKV is a Go library that provides a standardized key-value store interface built on top of [BadgerDB](https://github.com/dgraph-io/badger). It implements the `github.com/bborbe/kv` interface, offering a clean and consistent API for database operations including transactions, buckets, and key-value operations.\n\n## Features\n\n- **Standardized Interface**: Implements the `github.com/bborbe/kv` interface for consistent database operations\n- **Transaction Support**: Full ACID transaction support with automatic rollback on errors\n- **Bucket-based Organization**: Organize data into logical buckets within transactions\n- **Memory \u0026 Disk Storage**: Support for both file-based and in-memory databases\n- **Iterator Support**: Forward and reverse iteration over bucket contents\n- **Context-aware**: Full context support for cancellation and deadlines\n- **Thread-safe**: Safe for concurrent use across multiple goroutines\n\n## Installation\n\n```bash\ngo get github.com/bborbe/badgerkv\n```\n\n## Quick Start\n\n### Basic Usage\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n    \n    \"github.com/bborbe/badgerkv\"\n)\n\nfunc main() {\n    ctx := context.Background()\n    \n    // Open a file-based database\n    db, err := badgerkv.OpenPath(ctx, \"/tmp/mydb\")\n    if err != nil {\n        log.Fatal(err)\n    }\n    defer db.Close()\n    \n    // Start a transaction\n    err = db.Update(ctx, func(ctx context.Context, tx badgerkv.Tx) error {\n        // Get or create a bucket\n        bucket, err := tx.CreateBucketIfNotExists([]byte(\"users\"))\n        if err != nil {\n            return err\n        }\n        \n        // Store a key-value pair\n        return bucket.Put([]byte(\"user:1\"), []byte(`{\"name\": \"John\", \"age\": 30}`))\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    \n    // Read data\n    err = db.View(ctx, func(ctx context.Context, tx badgerkv.Tx) error {\n        bucket := tx.Bucket([]byte(\"users\"))\n        if bucket == nil {\n            return nil // bucket doesn't exist\n        }\n        \n        value, err := bucket.Get([]byte(\"user:1\"))\n        if err != nil {\n            return err\n        }\n        \n        log.Printf(\"User data: %s\", value)\n        return nil\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\n### In-Memory Database\n\n```go\n// Create an in-memory database (useful for testing)\ndb, err := badgerkv.OpenMemory(ctx)\nif err != nil {\n    log.Fatal(err)\n}\ndefer db.Close()\n```\n\n### Memory Optimization\n\n```go\n// Use minimal memory settings for resource-constrained environments\ndb, err := badgerkv.OpenPath(ctx, \"/tmp/mydb\", badgerkv.MinMemoryUsageOptions)\nif err != nil {\n    log.Fatal(err)\n}\ndefer db.Close()\n```\n\n### Iteration\n\n```go\nerr = db.View(ctx, func(ctx context.Context, tx badgerkv.Tx) error {\n    bucket := tx.Bucket([]byte(\"users\"))\n    if bucket == nil {\n        return nil\n    }\n    \n    // Forward iteration\n    iter := bucket.Iterator()\n    defer iter.Close()\n    \n    for iter.First(); iter.Valid(); iter.Next() {\n        key := iter.Key().Data()\n        value := iter.Item().Value()\n        log.Printf(\"Key: %s, Value: %s\", key, value)\n    }\n    \n    return nil\n})\n```\n\n### Custom BadgerDB Options\n\n```go\nimport \"github.com/dgraph-io/badger/v4\"\n\n// Define custom options\ncustomOptions := func(opts *badger.Options) {\n    opts.Logger = nil // Disable logging\n    opts.SyncWrites = true // Force sync on writes\n}\n\ndb, err := badgerkv.OpenPath(ctx, \"/tmp/mydb\", customOptions)\n```\n\n## API Overview\n\n### Database Operations\n\n- `OpenPath(ctx, path, ...options)` - Open file-based database\n- `OpenMemory(ctx, ...options)` - Open in-memory database\n- `DB.View(ctx, fn)` - Read-only transaction\n- `DB.Update(ctx, fn)` - Read-write transaction\n- `DB.Close()` - Close database\n\n### Transaction Operations\n\n- `Tx.Bucket(name)` - Get existing bucket\n- `Tx.CreateBucket(name)` - Create new bucket (fails if exists)\n- `Tx.CreateBucketIfNotExists(name)` - Get or create bucket\n- `Tx.DeleteBucket(name)` - Delete bucket and all contents\n\n### Bucket Operations\n\n- `Bucket.Get(key)` - Retrieve value by key\n- `Bucket.Put(key, value)` - Store key-value pair\n- `Bucket.Delete(key)` - Delete key\n- `Bucket.Iterator()` - Create iterator for bucket contents\n\n### Iterator Operations\n\n- `Iterator.First()` - Move to first item\n- `Iterator.Last()` - Move to last item\n- `Iterator.Next()` - Move to next item\n- `Iterator.Prev()` - Move to previous item\n- `Iterator.Valid()` - Check if iterator position is valid\n- `Iterator.Key()` - Get current key\n- `Iterator.Item()` - Get current item\n\n## Transaction Context\n\nBadgerKV prevents nested transactions by tracking transaction state in the context. Use `IsTransactionOpen(ctx)` to check if a transaction is already active.\n\n```go\nif badgerkv.IsTransactionOpen(ctx) {\n    // Already in a transaction, cannot start nested transaction\n    return errors.New(\"nested transactions not supported\")\n}\n```\n\n## Error Handling\n\nBadgerKV uses the `github.com/bborbe/errors` package for enhanced error handling with context preservation:\n\n```go\nerr = db.Update(ctx, func(ctx context.Context, tx badgerkv.Tx) error {\n    bucket, err := tx.CreateBucket([]byte(\"test\"))\n    if err != nil {\n        return errors.Wrapf(ctx, err, \"create bucket failed\")\n    }\n    \n    return bucket.Put([]byte(\"key\"), []byte(\"value\"))\n})\n\nif err != nil {\n    log.Printf(\"Transaction failed: %v\", err)\n}\n```\n\n## Testing\n\nBadgerKV is thoroughly tested using Ginkgo v2 and Gomega:\n\n```bash\n# Run all tests\ngo test ./...\n\n# Run tests with coverage\ngo test -cover ./...\n\n# Run specific test\ngo test -run TestSpecificFunction ./...\n```\n\n## Dependencies\n\n- **BadgerDB v4**: High-performance key-value database\n- **github.com/bborbe/kv**: Common key-value interface\n- **github.com/bborbe/errors**: Enhanced error handling\n- **github.com/bborbe/collection**: Utility functions\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Run `make precommit` to ensure code quality\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the BSD-style license. See the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbborbe%2Fbadgerkv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbborbe%2Fbadgerkv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbborbe%2Fbadgerkv/lists"}