README
¶
gophia v0.1.3
Gophia is a Go (golang) binding to the Sophia key-value database (http://sphia.org/)
Installation
Before installing Gophia, you need to install Sophia. Download it from http://sphia.org, and build.
The makefiles don't include an 'install', so you will need to manually install somewhere where Go can find the headers and the libs. Alternatively, you can set your CGO LDFLAGS and CFLAGS like so:
# My Sophia files installed to /usr/local/src/sophia
export CGO_LDFLAGS="-L/usr/local/src/sophia/db"
export CGO_CFLAGS="-I/usr/local/src/sophia/db"
Once Sophia is installed, Gophia can be installed with go get github.com/craigmj/gophia
Very Important
Sophia does not currently appear to support multi-threading. I'm not totally sure what is meant by this, but it seems to be that deep trouble will occur if using Gophia from multiple goroutings where GOMAXPROCS > 1. We're currently investigating, and might introduce some synchronizing into Gophia to handle multi-threading. For now, assume you will need to implement your own synchronization in multi-threaded situations.
Usage
Open the database:
db, err := gophia.Open(gophia.ReadWrite | gophia.Create, "testdb")
// check for errors
defer db.Close()
You're ready to go:
// SetSS sets a string key to a string value.
db.SetSS("one","ichi")
db.SetSS("two","nichi")
fmt.Println("one is ", db.MustGetSS("one"))
fmt.Println("two is ", db.MustGetSS("two"))
You can also use a cursor:
// Without a starting key, every key-value will be returned
cur, err := db.Cursor(gophia.GTE, nil)
for cur.Fetch() {
fmt.Println(cur.KeyS(), "=", cur.ValueS())
}
cur.Close()
Of course it's easy to delete a key-value:
db.DeleteS("one")
See the documentation for more.
Important
When a Cursor is open, no other access to the database is possible: a Cursor locks the entire db, even from other Cursors.
Therefore, you cannot do anything (Set, Delete, etc) while processing a Cursor. Also, you cannot Close the database util the Cursor is itself closed. NOT CLOSING THE DATABASE CORRUPTS THE DATABASE
In Gophia, this is simplified because you can always Close a Cursor (or Database or Environment) even if it has been previously Closed. This means that you can use the form:
cur, _ := db.Cursor(gophia.GTE, nil)
defer cur.Close()
for cur.Fetch() {
// ...
}
cur.Close()
If for some reason you exit during the loop, your cursor will still Close, and hence the Database as well. If you continue, your Cursor is manually closed.
Gophia also offers the Database.Each method, which iterates over the key-value pairs passing each to a given function. Each takes care of closing the Cursor when it returns.
You cannot mutate the database while a Cursor is open. The Delete call in this method will throw an error.
cur, _ := db.Cursor(gophia.GTE, nil)
defer cur.Close()
for cur.Fetch() {
err := db.Delete(cur.Key())
// err will not be nil here - you are trying to change the
// database while a cursor is open
}
cur.Close()
If you don't get this behaviour, please update your Sophia installation (in an old Sophia version, this scenario caused the program to hang).
Documentation
¶
Overview ¶
*
- Gophia is a Golang wrapper around the Sophia key-value database. *
- Sophia is Copyright 2013 Dmitry Simonenko *
- Gophia is Copyright 2013 Craig Mason-Jones. It is released under a BSD license.
Index ¶
- Constants
- Variables
- type Access
- type Comparator
- type Cursor
- func (cur *Cursor) Close() error
- func (cur *Cursor) Fetch() bool
- func (cur *Cursor) Key() []byte
- func (cur *Cursor) KeyLen() int
- func (cur *Cursor) KeyS() string
- func (cur *Cursor) KeySize() int
- func (cur *Cursor) KeyString() string
- func (cur *Cursor) Next() bool
- func (cur *Cursor) Object(out interface{}) error
- func (cur *Cursor) Value() []byte
- func (cur *Cursor) ValueLen() int
- func (cur *Cursor) ValueO(out interface{}) error
- func (cur *Cursor) ValueS() string
- func (cur *Cursor) ValueSize() int
- func (cur *Cursor) ValueString() string
- type Database
- func (db *Database) Begin() error
- func (db *Database) Close() error
- func (db *Database) Commit() error
- func (db *Database) Cursor(order Order, key []byte) (*Cursor, error)
- func (db *Database) CursorS(order Order, key string) (*Cursor, error)
- func (db *Database) CursorString(order Order, key string) (*Cursor, error)
- func (db *Database) Delete(key []byte) error
- func (db *Database) DeleteS(key string) error
- func (db *Database) DeleteString(key string) error
- func (db *Database) Each(order Order, key []byte, each func(key []byte, value []byte)) error
- func (db *Database) Error() error
- func (db *Database) Get(key []byte) ([]byte, error)
- func (db *Database) GetAO(key []byte, out interface{}) error
- func (db *Database) GetObject(key []byte, out interface{}) error
- func (db *Database) GetObjectString(key string, out interface{}) error
- func (db *Database) GetSA(key string) ([]byte, error)
- func (db *Database) GetSO(key string, out interface{}) error
- func (db *Database) GetSS(key string) (string, error)
- func (db *Database) GetString(key string) ([]byte, error)
- func (db *Database) GetStrings(key string) (string, error)
- func (db *Database) Has(key []byte) (bool, error)
- func (db *Database) HasS(key string) (bool, error)
- func (db *Database) HasString(key string) (bool, error)
- func (db *Database) MustGet(key []byte) []byte
- func (db *Database) MustGetSA(key string) []byte
- func (db *Database) MustGetSS(key string) string
- func (db *Database) MustGetString(key string) []byte
- func (db *Database) MustGetStrings(key string) string
- func (db *Database) MustHas(key []byte) bool
- func (db *Database) MustHasS(key string) bool
- func (db *Database) MustHasString(key string) bool
- func (db *Database) Rollback() error
- func (db *Database) Set(key, value []byte) error
- func (db *Database) SetAO(key []byte, value interface{}) error
- func (db *Database) SetObject(key []byte, value interface{}) error
- func (db *Database) SetObjectString(key string, value interface{}) error
- func (db *Database) SetSA(key string, value []byte) error
- func (db *Database) SetSO(key string, value interface{}) error
- func (db *Database) SetSS(key, value string) error
- func (db *Database) SetString(key string, value []byte) error
- func (db *Database) SetStrings(key, value string) error
- type Environment
- func (env *Environment) Close() error
- func (env *Environment) Cmp(cmp Comparator) error
- func (env *Environment) Dir(access Access, directory string) error
- func (env *Environment) Error() error
- func (env *Environment) GC(enabled bool) error
- func (env *Environment) GCF(factor float64) error
- func (env *Environment) Grow(newsize uint32, newFactor float64) error
- func (env *Environment) Merge(merge bool) error
- func (env *Environment) MergeWM(watermark uint32) error
- func (env *Environment) Open() (*Database, error)
- func (env *Environment) Page(count int) error
- type Order
Constants ¶
const ( GreaterThan Order = C.SPGT GT = GreaterThan GreaterThanEqual = C.SPGTE GTE = GreaterThanEqual LessThan = C.SPLT LT = LessThan LessThanEqual = C.SPLTE LTE = LessThanEqual )
const ( ComparesEqual int = 0 ComparesLessThan = -1 ComparesGreaterThan = 1 )
const ( ReadWrite Access = C.SPO_RDWR ReadOnly = C.SPO_RDONLY Create = C.SPO_CREAT )
Variables ¶
var ErrNotFound = errors.New("Key not found")
ErrNotFound indicates that the key does not exist in the database.
var ErrTransactionInProgress = errors.New("Transaction already in progress")
ErrTransactionInProgress returned when attempt to begin a transaction while there is already a transaction in progress.
Functions ¶
This section is empty.
Types ¶
type Comparator ¶
Comparator function is used to compare keys in the database.
The function must return 0 if the keys are equal, -1 if the first key parameter is lower, and 1 if the second key parameter is lower.
See Environment.Cmp()
type Cursor ¶
Cursor iterates over key-values in a database.
func (*Cursor) Close ¶
Close closes the cursor. If a cursor is not closed, future operations on the database can hang indefinitely.
func (*Cursor) Fetch ¶
Fetch fetches the next row for the cursor, and returns true if there is a next row, false if the cursor has reached the end of the rows.
func (*Cursor) KeyString ¶
KeyString returns the current key as a string. @deprecated Use KeyS instead
func (*Cursor) Next ¶
Next is identical to Fetch. It exists because it seems that Next() is more go-idiomatic.
func (*Cursor) Object ¶
ValueObject returns the current object, by gob decoding the current value at the cursor. @deprecated Use ValueO instead.
func (*Cursor) ValueLen ¶
ValueLen returns the length of the current value. It is a synonym for ValueSize()
func (*Cursor) ValueO ¶
ValueO returns the current value as an object, by gob decoding the current value at the cursor.
func (*Cursor) ValueString ¶
ValueString returns the current value as a string. @deprecated Use ValueS instead
type Database ¶
Database is used for accessing a database.
func (*Database) Close ¶
Close closes the database and frees its associated memory. You must call Close on any database opened with Open()
func (*Database) Commit ¶
Commit applies changes to a multi-statement transaction. All modifications made during the transaction are written to the log file in a single batch.
If commit failed, transaction modifications are discarded.
func (*Database) Cursor ¶
Cursor returns a Cursor for iterating over rows in the database.
If no key is provided, the Cursor will iterate over all rows.
The order flag decides the direction of the iteration, and whether the key is included or excluded.
Iterate over values with Fetch or Next methods.
func (*Database) CursorS ¶
CursorS returns a Cursor that fetches rows from the database from the given key, passed as a string. Callers must call Close() on the received Cursor.
func (*Database) CursorString ¶
CursorString returns a Cursor that fetches rows from the database from the given key, passed as a string. Callers must call Close() on the received Cursor. @deprecated Use CursorS instead.
func (*Database) DeleteString ¶
DeleteString deletes the key from the database. @deprecated Use DeleteS instead.
func (*Database) Each ¶
Each iterates through the key-values in the database, passing each to the each function. It is a convenience wrapper around a Cursor iteration.
func (*Database) Error ¶
Error returns any error on the database. It should not be necessary to call this method, since most methods return errors automatically.
func (*Database) GetObject ¶
GetObject fetches a gob encoded object into the out object. @deprecated Use GetAO instead.
func (*Database) GetObjectString ¶
GetObjectString retrieves a gob encoded object into the out object. It is a convenience method to facilitate working with string keys. @deprecated Use GetSO instead.
func (*Database) GetSA ¶
GetS retrieves an array value for a string key. It is a convenience method to simplify working with string keys.
func (*Database) GetString ¶
GetString returns a byte array value for a string key. @deprecated Use GetS instead.
func (*Database) GetStrings ¶
GetString retrieves the string value for the string key. It is a convenience function for working with strings rather than byte slices. @deprecated Use GetSS instead.
func (*Database) HasString ¶
HasString returns true if the database has a value for the key. It is a convenience function for working with strings rather than byte slices. @deprecated Use HasS instead
func (*Database) MustGetSA ¶
MustGetSA returns the byte array value for the string key. It panics on error.
func (*Database) MustGetSS ¶
MustGetSS returns the string value for a string key. It panics on an error.
func (*Database) MustGetString ¶
MustGetString returns the byte array value for the string key. It panics on error. @deprecated Use MustGetSA instead.
func (*Database) MustGetStrings ¶
MustGetStrings returns the string value for a string key. It panics on error. @deprecated Use MustGetSS instead.
func (*Database) MustHas ¶
MustHas returns true if the key exists, false otherwise. It panics in the even of error.
func (*Database) MustHasS ¶
MustHasS returns true if the string exists, or false if it does not. It panics in the event of error.
func (*Database) MustHasString ¶
MustHasString returns true if the string exists, or false if it does not. It panics in the event of error. @deprecated Use MustHasS instead
func (*Database) Rollback ¶
Rollback discards the changes of a multi-statement transaction. All modifications made during the transaction are not written to the log file.
func (*Database) SetObject ¶
SetObject will gob encode the object and store it with the key. @deprecated Use SetAO instead
func (*Database) SetObjectString ¶
SetObjectString will gob encode the object and store it with the key. This is a convenience method to facilitate working with string keys. @deprecated Prefer SetSO
func (*Database) SetString ¶
SetString sets the byte-slice value of the string key. It is a convenience function for working with string keys rather than byte slices. @deprecated Use SetSA instead
func (*Database) SetStrings ¶
SetStrings sets the value of the key. It is a convenience function for working with strings rather than byte slices. @deprecated Use SetSS instead
type Environment ¶
Environment is used to configure the database before opening.
func NewEnvironment ¶
func NewEnvironment() (*Environment, error)
NewEnvironment creates a new environment for opening a database. Receivers must call Close() on the returned Environment.
func (*Environment) Close ¶
func (env *Environment) Close() error
Close closes the enviroment and frees its associated memory. You must call Close on any Environment created with NewEnvironment.
func (*Environment) Cmp ¶
func (env *Environment) Cmp(cmp Comparator) error
Cmp sets the database comparator function to use for ordering keys.
The function must return 0 if the keys are equal, -1 if the first key parameter is lower, and 1 if the second key parameter is lower.
func (*Environment) Dir ¶
func (env *Environment) Dir(access Access, directory string) error
Dir sets the access mode and the directory for the database.
func (*Environment) Error ¶
func (env *Environment) Error() error
Error returns any error on the Environment. It should not be necessary to call this method, since the Go methods all return with errors themselves.
func (*Environment) GC ¶
func (env *Environment) GC(enabled bool) error
GC turns the garbage collector on or off.
func (*Environment) GCF ¶
func (env *Environment) GCF(factor float64) error
GCF sets database garbage collector factor value, which is used to determine when to start the GC.
For example: factor 0.5 means that all 'live' pages from any db file will be copied to new db when half or fewer of them are left.
This option can be tweaked for performance.
func (*Environment) Grow ¶
func (env *Environment) Grow(newsize uint32, newFactor float64) error
Grow sets the initial new size and resize factor for new database files. The values are used while the database extends during a merge.
This option can be tweaked for performance.
func (*Environment) Merge ¶
func (env *Environment) Merge(merge bool) error
Merge sets whether to launch a merger thread during Open().
func (*Environment) MergeWM ¶
func (env *Environment) MergeWM(watermark uint32) error
MergeWM sets the database merge watermark value.
When the database update count reaches this value, it notifies the merger thread to create a new epoch and start merging in-memory keys.
This option can be tweaked for performance.
func (*Environment) Open ¶
func (env *Environment) Open() (*Database, error)
Open() opens the database that has been configured in the Environment. At a minimum, it should be necessary to call Dir() on the Environment to specify the directory for the database.
func (*Environment) Page ¶
func (env *Environment) Page(count int) error
Page sets the max key count in a single page for the database. This option can be tweaked for performance.
Source Files