tidesdb_go

README

tidesdb-go

tidesdb-go is the official GO binding for TidesDB.

Getting started

You must make sure you have the TidesDB shared C library installed on your system. Be sure to also compile with TIDESDB_WITH_SANITIZER and TIDESDB_BUILD_TESTS OFF.

Installation

go get github.com/tidesdb/tidesdb-go

Usage

Opening and closing a database

db, err := tidesdb_go.Open("/path/to/db") // will reopen the database if it already exists
if err != nil {
...
}
defer db.Close()

Creating and dropping a column family

Column families are used to store data in TidesDB. You can create a column family using the CreateColumnFamily method.

err := db.CreateColumnFamily("example_cf", 1024*1024*64, 12, 0.24, true, int(tidesdb_go.TDB_COMPRESS_SNAPPY), true)
if err != nil {
...
}

// You can also drop a column family using the `DropColumnFamily` method.
err = db.DropColumnFamily("example_cf")
if err != nil {
...
}

CRUD operations

Writing data

err := db.Put("example_cf", []byte("key"), []byte("value"), -1)
if err != nil {
...
}

With TTL

err := db.Put("example_cf", []byte("key"), []byte("value"), time.Now().Add(10*time.Second).Unix())
if err != nil {
...
}

Reading data

value, err := db.Get("example_cf", []byte("key"))
if err != nil {
...
}
fmt.Println(string(value))

Deleting data

err := db.Delete("example_cf", []byte("key"))
if err != nil {
...
}

Deleting by range

// Delete all key-value pairs between "start_key" and "end_key" atomically
err := db.DeleteByRange("example_cf", []byte("start_key"), []byte("end_key"))
if err != nil {
...
}

Iterating over data

cursor, err := db.CursorInit("example_cf")
if err != nil {
...
}
defer cursor.Free()

for {
key, value, err := cursor.Get()
if err != nil {
    break
}
fmt.Printf("Key: %s, Value: %s\n", key, value)

cursor.Next() // or cursor.Prev()
}

Transactions

txn, err := db.BeginTxn("example_cf")
if err != nil {
...
}
defer txn.Free()

err = txn.Put([]byte("key"), []byte("value"), 0)
if err != nil {
...
}

// You can also use txn.Delete(), txn.Get()

err = txn.Commit()
if err != nil {
...
}

Range queries

// Get all key-value pairs between "start_key" and "end_key"
pairs, err := db.Range("example_cf", []byte("start_key"), []byte("end_key"))
if err != nil {
...
}

for _, pair := range pairs {
    key := pair[0]
    value := pair[1]
    fmt.Printf("Key: %s, Value: %s\n", key, value)
}

Getting Column Family Statistics

You can retrieve detailed statistics about a column family using the GetColumnFamilyStat method.

stat, err := db.GetColumnFamilyStat("example_cf")
if err != nil {
    ...
}

// Access various statistics about the column family
fmt.Printf("Column Family: %s\n", stat.Name)
fmt.Printf("Memtable Size: %d bytes\n", stat.MemtableSize)
fmt.Printf("Memtable Entries: %d\n", stat.MemtableEntryCount)
fmt.Printf("Number of SSTables: %d\n", stat.NumSSTables)
fmt.Printf("Incremental Merging: %t\n", stat.IncrementalMerging)

// Access configuration details
fmt.Printf("Flush Threshold: %d\n", stat.Config.FlushThreshold)
fmt.Printf("Max Level: %d\n", stat.Config.MaxLevel)
fmt.Printf("Probability: %f\n", stat.Config.Probability)
fmt.Printf("Compressed: %t\n", stat.Config.Compressed)
fmt.Printf("Bloom Filter: %t\n", stat.Config.BloomFilter)

// Access SSTable statistics
for i, sstStat := range stat.SSTableStats {
    fmt.Printf("SSTable %d - Path: %s, Size: %d bytes, Blocks: %d\n",
    i, sstStat.Path, sstStat.Size, sstStat.NumBlocks)
}

Listing Column Families

You can retrieve a list of all column families.

cfList, err := db.ListColumnFamilies()
if err != nil {
...
}

fmt.Println("Available column families:", cfList)

Compaction

Compaction is done manually or in background incrementally.

Merging operations, pair and merge sstables, removing expired keys if TTL set and tombstoned data.

Manual

err := db.CompactSSTables("example_cf", 4) // 4 is the number of threads to use for compaction. Each thread will compact a pair of sstables.
if err != nil {
    ...
}

Background

err := db.StartIncrementalMerge("example_cf", 60, 1000) // merge a pair of sstables starting at oldest pair every 60 seconds only when we have a minimum of 1000 sstables
if err != nil {
...
}

Documentation

Overview

Package tidesdb_go Copyright (C) TidesDB

Original Author: Alex Gaetano Padula

Licensed under the Mozilla Public License, v. 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.mozilla.org/en-US/MPL/2.0/

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• type ColumnFamilyConfig
• type ColumnFamilySSTableStat
• type ColumnFamilyStat
• type Cursor
  • func (c *Cursor) Free() error
  • func (c *Cursor) Get() ([]byte, []byte, error)
  • func (c *Cursor) Next() error
  • func (c *Cursor) Prev() error
• type TidesDB
  • func Open(directory string) (*TidesDB, error)
  • func (db *TidesDB) BeginTxn(columnFamily string) (*Transaction, error)
  • func (db *TidesDB) Close() error
  • func (db *TidesDB) CompactSSTables(columnFamilyName string, maxThreads int) error
  • func (db *TidesDB) CreateColumnFamily(name string, flushThreshold, maxLevel int, probability float32, ...) error
  • func (db *TidesDB) CursorInit(columnFamily string) (*Cursor, error)
  • func (db *TidesDB) Delete(columnFamilyName string, key []byte) error
  • func (db *TidesDB) DeleteByRange(columnFamilyName string, startKey, endKey []byte) error
  • func (db *TidesDB) DropColumnFamily(name string) error
  • func (db *TidesDB) Get(columnFamilyName string, key []byte) ([]byte, error)
  • func (db *TidesDB) GetColumnFamilyStat(columnFamilyName string) (*ColumnFamilyStat, error)
  • func (db *TidesDB) ListColumnFamilies() (string, error)
  • func (db *TidesDB) Put(columnFamilyName string, key, value []byte, ttl int64) error
  • func (db *TidesDB) Range(columnFamilyName string, startKey, endKey []byte) ([][2][]byte, error)
  • func (db *TidesDB) StartIncrementalMerge(columnFamilyName string, seconds, minSSTables int) error
• type TidesDBCompressionAlgo
• type Transaction
  • func (txn *Transaction) Commit() error
  • func (txn *Transaction) Delete(key []byte) error
  • func (txn *Transaction) Free() error
  • func (txn *Transaction) Get(key []byte) ([]byte, error)
  • func (txn *Transaction) Put(key, value []byte, ttl int64) error
  • func (txn *Transaction) Rollback() error

Types

type ColumnFamilyConfig

type ColumnFamilyConfig struct {
	Name           string
	FlushThreshold int32
	MaxLevel       int32
	Probability    float32
	Compressed     bool
	CompressAlgo   TidesDBCompressionAlgo
	BloomFilter    bool
}

ColumnFamilyConfig represents the configuration for a column family.

type ColumnFamilySSTableStat

type ColumnFamilySSTableStat struct {
	Path      string
	Size      int64
	NumBlocks int64
}

ColumnFamilySSTableStat represents statistics about an SSTable in a column family.

type ColumnFamilyStat

type ColumnFamilyStat struct {
	Config             ColumnFamilyConfig
	Name               string
	NumSSTables        int
	MemtableSize       int64
	MemtableEntryCount int64
	IncrementalMerging bool
	SSTableStats       []*ColumnFamilySSTableStat
}

ColumnFamilyStat represents statistics about a column family.

type Cursor

type Cursor struct {
	// contains filtered or unexported fields
}

Cursor represents a TidesDB cursor.

func (*Cursor) Free

func (c *Cursor) Free() error

Free frees the memory for the cursor.

func (*Cursor) Get

func (c *Cursor) Get() ([]byte, []byte, error)

Get gets the current key-value pair from the cursor.

func (*Cursor) Next

func (c *Cursor) Next() error

Next moves the cursor to the next key-value pair.

func (*Cursor) Prev

func (c *Cursor) Prev() error

Prev moves the cursor to the previous key-value pair.

type TidesDB

type TidesDB struct {
	// contains filtered or unexported fields
}

TidesDB represents a TidesDB instance.

func Open

func Open(directory string) (*TidesDB, error)

Open opens a TidesDB instance.

func (*TidesDB) BeginTxn

func (db *TidesDB) BeginTxn(columnFamily string) (*Transaction, error)

BeginTxn begins a transaction.

func (*TidesDB) Close

func (db *TidesDB) Close() error

Close closes a TidesDB instance.

func (*TidesDB) CompactSSTables

func (db *TidesDB) CompactSSTables(columnFamilyName string, maxThreads int) error

CompactSSTables pairs and merges SSTables in a column family.

func (*TidesDB) CreateColumnFamily

func (db *TidesDB) CreateColumnFamily(name string, flushThreshold, maxLevel int, probability float32, compressed bool, compressAlgo int, bloomFilter bool) error

CreateColumnFamily creates a new column family.

func (*TidesDB) CursorInit

func (db *TidesDB) CursorInit(columnFamily string) (*Cursor, error)

CursorInit initializes a new TidesDB cursor.

func (*TidesDB) Delete

func (db *TidesDB) Delete(columnFamilyName string, key []byte) error

Delete deletes a key-value pair from TidesDB.

func (*TidesDB) DeleteByRange

func (db *TidesDB) DeleteByRange(columnFamilyName string, startKey, endKey []byte) error

DeleteByRange deletes all key-value pairs within a specified range atomically.

func (*TidesDB) DropColumnFamily

func (db *TidesDB) DropColumnFamily(name string) error

DropColumnFamily drops a column family and all associated data.

func (*TidesDB) Get

func (db *TidesDB) Get(columnFamilyName string, key []byte) ([]byte, error)

Get gets a value from TidesDB.

func (*TidesDB) GetColumnFamilyStat

func (db *TidesDB) GetColumnFamilyStat(columnFamilyName string) (*ColumnFamilyStat, error)

GetColumnFamilyStat retrieves statistics about a column family.

func (*TidesDB) ListColumnFamilies

func (db *TidesDB) ListColumnFamilies() (string, error)

ListColumnFamilies lists the column families in TidesDB.

func (*TidesDB) Put

func (db *TidesDB) Put(columnFamilyName string, key, value []byte, ttl int64) error

Put puts a key-value pair into TidesDB.

func (*TidesDB) Range

func (db *TidesDB) Range(columnFamilyName string, startKey, endKey []byte) ([][2][]byte, error)

Range retrieves all key-value pairs within a specified range.

func (*TidesDB) StartIncrementalMerge

func (db *TidesDB) StartIncrementalMerge(columnFamilyName string, seconds, minSSTables int) error

StartIncrementalMerge starts a background incremental merges for a column family. Will run in background until db closure. Will merge pairs incrementally and only once min sstables are has been reached.

type TidesDBCompressionAlgo

type TidesDBCompressionAlgo int

TidesDBCompressionAlgo represents the compression algorithm type.

const (
	TDB_NO_COMPRESSION TidesDBCompressionAlgo = iota
	TDB_COMPRESS_SNAPPY
	TDB_COMPRESS_LZ4
	TDB_COMPRESS_ZSTD
)

type Transaction

type Transaction struct {
	// contains filtered or unexported fields
}

Transaction represents a TidesDB transaction.

func (*Transaction) Commit

func (txn *Transaction) Commit() error

Commit commits the transaction.

func (*Transaction) Delete

func (txn *Transaction) Delete(key []byte) error

Delete removes a key-value pair from the transaction.

func (*Transaction) Free

func (txn *Transaction) Free() error

Free frees the transaction and its operations.

func (*Transaction) Get

func (txn *Transaction) Get(key []byte) ([]byte, error)

Get gets a value in the transaction.

func (*Transaction) Put

func (txn *Transaction) Put(key, value []byte, ttl int64) error

Put adds a key-value pair to the transaction.

func (*Transaction) Rollback

func (txn *Transaction) Rollback() error

Rollback rolls back the transaction.