README
¶
Welcome to GoLeveldb 👋
Leveldb is in golang!
Why us?
- We now support Linux and Windows
- We use precompiled binaries
Documentation
¶
Index ¶
- Variables
- func DestroyComparator(cmp *C.leveldb_comparator_t)
- func DestroyDatabase(dbname string, o *Options) error
- func GetLevelDBMajorVersion() int
- func GetLevelDBMinorVersion() int
- func RepairDatabase(dbname string, o *Options) error
- type Cache
- type CompressionOpt
- type DB
- func (db *DB) Close()
- func (db *DB) CompactRange(r Range)
- func (db *DB) Delete(wo *WriteOptions, key []byte) error
- func (db *DB) Get(ro *ReadOptions, key []byte) ([]byte, error)
- func (db *DB) GetApproximateSizes(ranges []Range) []uint64
- func (db *DB) NewIterator(ro *ReadOptions) *Iterator
- func (db *DB) NewSnapshot() *Snapshot
- func (db *DB) PropertyValue(propName string) string
- func (db *DB) Put(wo *WriteOptions, key, value []byte) error
- func (db *DB) ReleaseSnapshot(snap *Snapshot)
- func (db *DB) Write(wo *WriteOptions, w *WriteBatch) error
- type DatabaseError
- type Env
- type FilterPolicy
- type Iterator
- func (it *Iterator) Close()
- func (it *Iterator) GetError() error
- func (it *Iterator) Key() []byte
- func (it *Iterator) Next()
- func (it *Iterator) Prev()
- func (it *Iterator) Seek(key []byte)
- func (it *Iterator) SeekToFirst()
- func (it *Iterator) SeekToLast()
- func (it *Iterator) Valid() bool
- func (it *Iterator) Value() []byte
- type IteratorError
- type Options
- func (o *Options) Close()
- func (o *Options) SetBlockRestartInterval(n int)
- func (o *Options) SetBlockSize(s int)
- func (o *Options) SetCache(cache *Cache)
- func (o *Options) SetComparator(cmp *C.leveldb_comparator_t)
- func (o *Options) SetCompression(t CompressionOpt)
- func (o *Options) SetCreateIfMissing(b bool)
- func (o *Options) SetEnv(env *Env)
- func (o *Options) SetErrorIfExists(errorIfExists bool)
- func (o *Options) SetFilterPolicy(fp *FilterPolicy)
- func (o *Options) SetInfoLog(log *C.leveldb_logger_t)
- func (o *Options) SetMaxOpenFiles(n int)
- func (o *Options) SetParanoidChecks(pc bool)
- func (o *Options) SetWriteBufferSize(s int)
- type Range
- type ReadOptions
- type Snapshot
- type WriteBatch
- type WriteOptions
Constants ¶
This section is empty.
Variables ¶
var ErrDBClosed = errors.New("database is closed")
ErrDBClosed is returned by DB.Close when its been called previously.
Functions ¶
func DestroyComparator ¶
func DestroyComparator(cmp *C.leveldb_comparator_t)
DestroyComparator deallocates a *C.leveldb_comparator_t.
This is provided as a convienience to advanced users that have implemented their own comparators in C in their own code.
func DestroyDatabase ¶
DestroyDatabase removes a database entirely, removing everything from the filesystem.
func GetLevelDBMajorVersion ¶
func GetLevelDBMajorVersion() int
GetLevelDBMajorVersion returns the underlying LevelDB implementation's major version.
func GetLevelDBMinorVersion ¶
func GetLevelDBMinorVersion() int
GetLevelDBMinorVersion returns the underlying LevelDB implementation's minor version.
func RepairDatabase ¶
RepairDatabase attempts to repair a database.
If the database is unrepairable, an error is returned.
Types ¶
type Cache ¶
type Cache struct {
Cache *C.leveldb_cache_t
}
Cache is a cache used to store data read from data in memory.
Typically, NewLRUCache is all you will need, but advanced users may implement their own *C.leveldb_cache_t and create a Cache.
To prevent memory leaks, a Cache must have Close called on it when it is no longer needed by the program. Note: if the process is shutting down, this may not be necessary and could be avoided to shorten shutdown time.
func NewLRUCache ¶
NewLRUCache creates a new Cache object with the capacity given.
To prevent memory leaks, Close should be called on the Cache when the program no longer needs it. Note: if the process is shutting down, this may not be necessary and could be avoided to shorten shutdown time.
type CompressionOpt ¶
type CompressionOpt int
CompressionOpt is a value for Options.SetCompression.
const ( NoCompression CompressionOpt = 0 SnappyCompression CompressionOpt = 1 )
Known compression arguments for Options.SetCompression.
type DB ¶
DB is a reusable handle to a LevelDB database on disk, created by Open.
To avoid memory and file descriptor leaks, call Close when the process no longer needs the handle. Calls to any DB method made after Close will panic.
The DB instance may be shared between goroutines. The usual data race conditions will occur if the same key is written to from more than one, of course.
func Open ¶
Open opens a database.
Creating a new database is done by calling SetCreateIfMissing(true) on the Options passed to Open.
It is usually wise to set a Cache object on the Options with SetCache to keep recently used data from that database in memory.
func (*DB) Close ¶
func (db *DB) Close()
Close closes the database, rendering it unusable for I/O, by deallocating the underlying handle.
Any attempts to use the DB after Close is called will panic.
func (*DB) CompactRange ¶
CompactRange runs a manual compaction on the Range of keys given. This is not likely to be needed for typical usage.
func (*DB) Delete ¶
func (db *DB) Delete(wo *WriteOptions, key []byte) error
Delete removes the data associated with the key from the database.
The key byte slice may be reused safely. Delete takes a copy of them before returning. The WriteOptions passed in can be reused by multiple calls to this and if the WriteOptions is left unchanged.
func (*DB) Get ¶
func (db *DB) Get(ro *ReadOptions, key []byte) ([]byte, error)
Get returns the data associated with the key from the database.
If the key does not exist in the database, a nil []byte is returned. If the key does exist, but the data is zero-length in the database, a zero-length []byte will be returned.
The key byte slice may be reused safely. Get takes a copy of them before returning.
func (*DB) GetApproximateSizes ¶
GetApproximateSizes returns the approximate number of bytes of file system space used by one or more key ranges.
The keys counted will begin at Range.Start and end on the key before Range.Limit.
func (*DB) NewIterator ¶
func (db *DB) NewIterator(ro *ReadOptions) *Iterator
NewIterator returns an Iterator over the the database that uses the ReadOptions given.
Often, this is used for large, offline bulk reads while serving live traffic. In that case, it may be wise to disable caching so that the data processed by the returned Iterator does not displace the already cached data. This can be done by calling SetFillCache(false) on the ReadOptions before passing it here.
Similarly, ReadOptions.SetSnapshot is also useful.
The ReadOptions passed in can be reused by multiple calls to this and other methods if the ReadOptions is left unchanged.
func (*DB) NewSnapshot ¶
NewSnapshot creates a new snapshot of the database.
The Snapshot, when used in a ReadOptions, provides a consistent view of state of the database at the the snapshot was created.
To prevent memory leaks and resource strain in the database, the snapshot returned must be released with DB.ReleaseSnapshot method on the DB that created it.
See the LevelDB documentation for details.
func (*DB) PropertyValue ¶
PropertyValue returns the value of a database property.
Examples of properties include "leveldb.stats", "leveldb.sstables", and "leveldb.num-files-at-level0".
func (*DB) Put ¶
func (db *DB) Put(wo *WriteOptions, key, value []byte) error
Put writes data associated with a key to the database.
If a nil []byte is passed in as value, it will be returned by Get as an zero-length slice. The WriteOptions passed in can be reused by multiple calls to this and if the WriteOptions is left unchanged.
The key and value byte slices may be reused safely. Put takes a copy of them before returning.
func (*DB) ReleaseSnapshot ¶
ReleaseSnapshot removes the snapshot from the database's list of snapshots, and deallocates it.
func (*DB) Write ¶
func (db *DB) Write(wo *WriteOptions, w *WriteBatch) error
Write atomically writes a WriteBatch to disk. The WriteOptions passed in can be reused by multiple calls to this and other methods.
type DatabaseError ¶
type DatabaseError string
DatabaseError wraps general internal LevelDB errors for user consumption.
func (DatabaseError) Error ¶
func (e DatabaseError) Error() string
type Env ¶
type Env struct {
Env *C.leveldb_env_t
}
Env is a system call environment used by a database.
Typically, NewDefaultEnv is all you need. Advanced users may create their own Env with a *C.leveldb_env_t of their own creation.
To prevent memory leaks, an Env must have Close called on it when it is no longer needed by the program.
func NewDefaultEnv ¶
func NewDefaultEnv() *Env
NewDefaultEnv creates a default environment for use in an Options.
To prevent memory leaks, the Env returned should be deallocated with Close.
type FilterPolicy ¶
type FilterPolicy struct {
Policy *C.leveldb_filterpolicy_t
}
FilterPolicy is a factory type that allows the LevelDB database to create a filter, such as a bloom filter, that is stored in the sstables and used by DB.Get to reduce reads.
An instance of this struct may be supplied to Options when opening a DB. Typical usage is to call NewBloomFilter to get an instance.
To prevent memory leaks, a FilterPolicy must have Close called on it when it is no longer needed by the program.
func NewBloomFilter ¶
func NewBloomFilter(bitsPerKey int) *FilterPolicy
NewBloomFilter creates a filter policy that will create a bloom filter when necessary with the given number of bits per key.
See the FilterPolicy documentation for more.
func (*FilterPolicy) Close ¶
func (fp *FilterPolicy) Close()
Close reaps the resources associated with this FilterPolicy.
type Iterator ¶
type Iterator struct {
Iter *C.leveldb_iterator_t
}
Iterator is a read-only iterator through a LevelDB database. It provides a way to seek to specific keys and iterate through the keyspace from that point, as well as access the values of those keys.
Care must be taken when using an Iterator. If the method Valid returns false, calls to Key, Value, Next, and Prev will result in panics. However, Seek, SeekToFirst, SeekToLast, GetError, Valid, and Close will still be safe to call.
GetError will only return an error in the event of a LevelDB error. It will return a nil on iterators that are simply invalid. Given that behavior, GetError is not a replacement for a Valid.
A typical use looks like:
db := GoLeveldb.Open(...)
it := db.NewIterator(readOpts)
defer it.Close()
for it.Seek(mykey); it.Valid(); it.Next() {
useKeyAndValue(it.Key(), it.Value())
}
if err := it.GetError() {
...
}
To prevent memory leaks, an Iterator must have Close called on it when it is no longer needed by the program.
func (*Iterator) Close ¶
func (it *Iterator) Close()
Close deallocates the given Iterator, freeing the underlying C struct.
func (*Iterator) GetError ¶
GetError returns an IteratorError from LevelDB if it had one during iteration.
This method is safe to call when Valid returns false.
func (*Iterator) Key ¶
Key returns a copy the key in the database the iterator currently holds.
If Valid returns false, this method will panic.
func (*Iterator) Next ¶
func (it *Iterator) Next()
Next moves the iterator to the next sequential key in the database, as defined by the Comparator in the ReadOptions used to create this Iterator.
If Valid returns false, this method will panic.
func (*Iterator) Prev ¶
func (it *Iterator) Prev()
Prev moves the iterator to the previous sequential key in the database, as defined by the Comparator in the ReadOptions used to create this Iterator.
If Valid returns false, this method will panic.
func (*Iterator) Seek ¶
Seek moves the iterator the position of the key given or, if the key doesn't exist, the next key that does exist in the database. If the key doesn't exist, and there is no next key, the Iterator becomes invalid.
This method is safe to call when Valid returns false.
func (*Iterator) SeekToFirst ¶
func (it *Iterator) SeekToFirst()
SeekToFirst moves the iterator to the first key in the database, as defined by the Comparator in the ReadOptions used to create this Iterator.
This method is safe to call when Valid returns false.
func (*Iterator) SeekToLast ¶
func (it *Iterator) SeekToLast()
SeekToLast moves the iterator to the last key in the database, as defined by the Comparator in the ReadOptions used to create this Iterator.
This method is safe to call when Valid returns false.
type IteratorError ¶
type IteratorError string
IteratorError wraps general internal LevelDB iterator errors for user consumption.
func (IteratorError) Error ¶
func (e IteratorError) Error() string
type Options ¶
type Options struct {
Opt *C.leveldb_options_t
}
Options represent all of the available options when opening a database with Open. Options should be created with NewOptions.
It is usually with to call SetCache with a cache object. Otherwise, all data will be read off disk.
To prevent memory leaks, Close must be called on an Options when the program no longer needs it.
func (*Options) Close ¶
func (o *Options) Close()
Close deallocates the Options, freeing its underlying C struct.
func (*Options) SetBlockRestartInterval ¶
SetBlockRestartInterval is the number of keys between restarts points for delta encoding keys.
Most clients should leave this parameter alone. See the LevelDB documentation for details.
func (*Options) SetBlockSize ¶
SetBlockSize sets the approximate size of user data packed per block.
The default is roughly 4096 uncompressed bytes. A better setting depends on your use case. See the LevelDB documentation for details.
func (*Options) SetCache ¶
SetCache places a cache object in the database when a database is opened.
This is usually wise to use. See also ReadOptions.SetFillCache.
func (*Options) SetComparator ¶
func (o *Options) SetComparator(cmp *C.leveldb_comparator_t)
SetComparator sets the comparator to be used for all read and write operations.
The comparator that created a database must be the same one (technically, one with the same name string) that is used to perform read and write operations.
The default comparator is usually sufficient.
func (*Options) SetCompression ¶
func (o *Options) SetCompression(t CompressionOpt)
SetCompression sets whether to compress blocks using the specified compresssion algorithm.
The default value is SnappyCompression and it is fast enough that it is unlikely you want to turn it off. The other option is NoCompression.
If the LevelDB library was built without Snappy compression enabled, the SnappyCompression setting will be ignored.
func (*Options) SetCreateIfMissing ¶
SetCreateIfMissing causes Open to create a new database on disk if it does not already exist.
func (*Options) SetErrorIfExists ¶
SetErrorIfExists causes the opening of a database that already exists to throw an error if true.
func (*Options) SetFilterPolicy ¶
func (o *Options) SetFilterPolicy(fp *FilterPolicy)
SetFilterPolicy causes Open to create a new database that will uses filter created from the filter policy passed in.
func (*Options) SetInfoLog ¶
func (o *Options) SetInfoLog(log *C.leveldb_logger_t)
SetInfoLog sets a *C.leveldb_logger_t object as the informational logger for the database.
func (*Options) SetMaxOpenFiles ¶
SetMaxOpenFiles sets the number of files than can be used at once by the database.
See the LevelDB documentation for details.
func (*Options) SetParanoidChecks ¶
SetParanoidChecks causes the database to do aggressive checking of the data it is processing and will stop early if it detects errors if true.
See the LevelDB documentation docs for details.
func (*Options) SetWriteBufferSize ¶
SetWriteBufferSize sets the number of bytes the database will build up in memory (backed by an unsorted log on disk) before converting to a sorted on-disk file.
type Range ¶
Range is a range of keys in the database. GetApproximateSizes calls with it begin at the key Start and end right before the key Limit.
type ReadOptions ¶
type ReadOptions struct {
Opt *C.leveldb_readoptions_t
}
ReadOptions represent all of the available options when reading from a database.
To prevent memory leaks, Close must called on a ReadOptions when the program no longer needs it.
func NewReadOptions ¶
func NewReadOptions() *ReadOptions
NewReadOptions allocates a new ReadOptions object.
func (*ReadOptions) Close ¶
func (ro *ReadOptions) Close()
Close deallocates the ReadOptions, freeing its underlying C struct.
func (*ReadOptions) SetFillCache ¶
func (ro *ReadOptions) SetFillCache(b bool)
SetFillCache controls whether reads performed with this ReadOptions will fill the Cache of the server. It defaults to true.
It is useful to turn this off on ReadOptions for DB.Iterator (and DB.Get) calls used in offline threads to prevent bulk scans from flushing out live user data in the cache.
See also Options.SetCache
func (*ReadOptions) SetSnapshot ¶
func (ro *ReadOptions) SetSnapshot(snap *Snapshot)
SetSnapshot causes reads to provided as they were when the passed in Snapshot was created by DB.NewSnapshot. This is useful for getting consistent reads during a bulk operation.
See the LevelDB documentation for details.
func (*ReadOptions) SetVerifyChecksums ¶
func (ro *ReadOptions) SetVerifyChecksums(b bool)
SetVerifyChecksums controls whether all data read with this ReadOptions will be verified against corresponding checksums.
It defaults to false. See the LevelDB documentation for details.
type Snapshot ¶
type Snapshot struct {
// contains filtered or unexported fields
}
Snapshot provides a consistent view of read operations in a DB.
Snapshot is used in read operations by setting it on a ReadOptions. Snapshots are created by calling DB.NewSnapshot.
To prevent memory leaks and resource strain in the database, the snapshot returned must be released with DB.ReleaseSnapshot method on the DB that created it.
type WriteBatch ¶
type WriteBatch struct {
// contains filtered or unexported fields
}
WriteBatch is a batching of Puts, and Deletes to be written atomically to a database. A WriteBatch is written when passed to DB.Write.
To prevent memory leaks, call Close when the program no longer needs the WriteBatch object.
func NewWriteBatch ¶
func NewWriteBatch() *WriteBatch
NewWriteBatch creates a fully allocated WriteBatch.
func (*WriteBatch) Clear ¶
func (w *WriteBatch) Clear()
Clear removes all the enqueued Put and Deletes in the WriteBatch.
func (*WriteBatch) Close ¶
func (w *WriteBatch) Close()
Close releases the underlying memory of a WriteBatch.
func (*WriteBatch) Delete ¶
func (w *WriteBatch) Delete(key []byte)
Delete queues a deletion of the data at key to be deleted later.
The key byte slice may be reused safely. Delete takes a copy of them before returning.
func (*WriteBatch) Put ¶
func (w *WriteBatch) Put(key, value []byte)
Put places a key-value pair into the WriteBatch for writing later.
Both the key and value byte slices may be reused as WriteBatch takes a copy of them before returning.
type WriteOptions ¶
type WriteOptions struct {
Opt *C.leveldb_writeoptions_t
}
WriteOptions represent all of the available options when writing from a database.
To prevent memory leaks, Close must called on a WriteOptions when the program no longer needs it.
func NewWriteOptions ¶
func NewWriteOptions() *WriteOptions
NewWriteOptions allocates a new WriteOptions object.
func (*WriteOptions) Close ¶
func (wo *WriteOptions) Close()
Close deallocates the WriteOptions, freeing its underlying C struct.
func (*WriteOptions) SetSync ¶
func (wo *WriteOptions) SetSync(b bool)
SetSync controls whether each write performed with this WriteOptions will be flushed from the operating system buffer cache before the write is considered complete.
If called with true, this will significantly slow down writes. If called with false, and the host machine crashes, some recent writes may be lost. The default is false.
See the LevelDB documentation for details.
Source Files