README
¶
simplehstore
Easy way to use a PostgreSQL database (and the HSTORE feature) from Go.
Online API Documentation
Features and limitations
- Requires PostgreSQL 9.1 or later.
- Requires Go 1.10 or later.
- Supports simple use of lists, hashmaps, sets and key/values.
- Deals mainly with strings.
- Uses the pq package.
- Modeled after simpleredis.
- Uses SQL queries with HSTORE for the KeyValue and HashMap types.
- Uses regular SQL for the List and Set types.
Sample usage
package main
import (
"log"
db "github.com/xyproto/simplehstore"
)
func main() {
// Check if the local db service is up
if err := db.TestConnection(); err != nil {
log.Fatalln("Could not connect to local database. Is the service up and running?")
}
// Create a Host, connect to the local db server
host := db.New()
// Connecting to a different host/port
//host := db.NewHost("server:5432/db")
// Connect to a different db host/port, with a username and password
// host := db.NewHost("username:password@server/db")
// Close the connection when the function returns
defer host.Close()
// Create a list named "greetings"
list, err := db.NewList(host, "greetings")
if err != nil {
log.Fatalln("Could not create list!")
}
// Add "hello" to the list, check if there are errors
if list.Add("hello") != nil {
log.Fatalln("Could not add an item to list!")
}
// Get the last item of the list
if item, err := list.GetLast(); err != nil {
log.Fatalln("Could not fetch the last item from the list!")
} else {
log.Println("The value of the stored item is:", item)
}
// Remove the list
if list.Remove() != nil {
log.Fatalln("Could not remove the list!")
}
}
Testing
- A PostgreSQL server must be up and running locally for
go testto work, and a database namedtestmust exist.
License, author and version
- License: BSD-3
- Author: Alexander F. Rødseth <xyproto@archlinux.org>
- Version: 1.8.2
Documentation
¶
Overview ¶
Package simplehstore offers a simple way to use a PostgreSQL database with HSTORE. The database back end is interchangeable with Redis (xyproto/simpleredis), BoltDB (xyproto/simplebolt) and MariaDB/MySQL (xyproto/simplemaria) by using the interfaces in the xyproto/pinterface package.
Index ¶
- Constants
- Variables
- func Decode(code *string) error
- func Encode(value *string) error
- func SetColumnNames(list, set, hashMapOwner, keyValuePrefix string)
- func TestConnection() (err error)
- func TestConnectionHost(connectionString string) error
- func TestConnectionHostWithDSN(connectionString string) error
- type HashMap
- func (h *HashMap) All() ([]string, error)
- func (h *HashMap) AllWhere(key, value string) ([]string, error)
- func (h *HashMap) Clear() error
- func (h *HashMap) Count() (int, error)
- func (h *HashMap) CountInt64() (int64, error)
- func (h *HashMap) CreateIndexTable() error
- func (h *HashMap) Del(owner string) error
- func (h *HashMap) DelKey(owner, key string) error
- func (h *HashMap) Exists(owner string) (bool, error)
- func (h *HashMap) Get(owner, key string) (string, error)
- func (h *HashMap) GetAll() ([]string, error)
- func (h *HashMap) Has(owner, key string) (bool, error)
- func (h *HashMap) Keys(owner string) ([]string, error)
- func (h *HashMap) Remove() error
- func (h *HashMap) RemoveIndexTable(owner string) error
- func (h *HashMap) Set(owner, key, value string) error
- func (h *HashMap) SetCheck(owner, key, value string) (bool, error)
- type HashMap2
- func (hm2 *HashMap2) All() ([]string, error)
- func (hm2 *HashMap2) AllPossibleKeys() ([]string, error)
- func (hm2 *HashMap2) AllWhere(key, value string) ([]string, error)
- func (hm2 *HashMap2) Clear() error
- func (hm2 *HashMap2) Count() (int64, error)
- func (hm2 *HashMap2) Del(owner string) error
- func (hm2 *HashMap2) DelKey(owner, key string) error
- func (hm2 *HashMap2) Empty() (bool, error)
- func (hm2 *HashMap2) Exists(owner string) (bool, error)
- func (hm2 *HashMap2) Get(owner, key string) (string, error)
- func (hm2 *HashMap2) GetMap(owner string, keys []string) (map[string]string, error)
- func (hm2 *HashMap2) Has(owner, key string) (bool, error)
- func (hm2 *HashMap2) Keys(owner string) ([]string, error)
- func (hm2 *HashMap2) Remove() error
- func (hm2 *HashMap2) Set(owner, key, value string) error
- func (hm2 *HashMap2) SetLargeMap(allProperties map[string]map[string]string) error
- func (hm2 *HashMap2) SetMap(owner string, m map[string]string) error
- type Host
- type KeyValue
- func (kv *KeyValue) All() ([]string, error)
- func (kv *KeyValue) Clear() error
- func (kv *KeyValue) Count() (int, error)
- func (kv *KeyValue) CountInt64() (int64, error)
- func (kv *KeyValue) CreateIndexTable() error
- func (kv *KeyValue) Dec(key string) (string, error)
- func (kv *KeyValue) Del(key string) error
- func (kv *KeyValue) Empty() (bool, error)
- func (kv *KeyValue) Get(key string) (string, error)
- func (kv *KeyValue) Inc(key string) (string, error)
- func (kv *KeyValue) Remove() error
- func (kv *KeyValue) RemoveIndexTable() error
- func (kv *KeyValue) Set(key, value string) error
- type List
- func (l *List) Add(value string) error
- func (l *List) All() ([]string, error)
- func (l *List) Clear() error
- func (l *List) Count() (int, error)
- func (l *List) CountInt64() (int64, error)
- func (l *List) GetAll() ([]string, error)
- func (l *List) GetLast() (string, error)
- func (l *List) GetLastN(n int) ([]string, error)
- func (l *List) Has(owner string) (bool, error)
- func (l *List) Last() (string, error)
- func (l *List) LastN(n int) ([]string, error)
- func (l *List) Remove() error
- func (l *List) RemoveByIndex(index int) error
- type PostgresCreator
- type Set
- func (s *Set) Add(value string) error
- func (s *Set) All() ([]string, error)
- func (s *Set) Clear() error
- func (s *Set) Count() (int, error)
- func (s *Set) CountInt64() (int64, error)
- func (s *Set) Del(value string) error
- func (s *Set) GetAll() ([]string, error)
- func (s *Set) Has(value string) (bool, error)
- func (s *Set) Remove() error
Constants ¶
const (
// VersionString is the current version of simplehstore.
VersionString = "1.8.1"
)
Variables ¶
var ( // ErrNoAvailableValues is used as an error if an SQL query returns no values ErrNoAvailableValues = errors.New("no available values") // ErrTooFewResults is used as an error if an SQL query returns too few results ErrTooFewResults = errors.New("too few results") )
var Verbose = false
Verbose can be set to true when testing, for more information
Functions ¶
func Encode ¶
Encode compresses and encodes a given string in order to safely handle *any* UTF-8 characters.
func SetColumnNames ¶
func SetColumnNames(list, set, hashMapOwner, keyValuePrefix string)
SetColumnNames can be used to change the column names and prefixes that are used in the PostgreSQL tables. The default values are: "a_list", "a_set", "owner" and "a_kv_".
func TestConnection ¶
func TestConnection() (err error)
TestConnection checks if the local database server is up and running
func TestConnectionHost ¶
TestConnectionHost checks if a given database server is up and running. connectionString may be on the form "username:password@host:port/database". The database name is ignored.
func TestConnectionHostWithDSN ¶
TestConnectionHostWithDSN checks if a given database server is up and running.
Types ¶
type HashMap ¶
type HashMap dbDatastructure
HashMap is a hash map with a name, key and value, stored in PostgreSQL Useful when storing several keys and values for a specific username, for instance.
func NewHashMap ¶
NewHashMap creates a new HashMap struct
func (*HashMap) CountInt64 ¶ added in v1.2.16
CountInt64 counts the number of owners for hash map elements
func (*HashMap) CreateIndexTable ¶
CreateIndexTable creates an INDEX table for this hash map, that may speed up lookups
func (*HashMap) DelKey ¶
DelKey removes a key of an owner in a hashmap (for instance the email field for a user)
func (*HashMap) Get ¶
Get a value from a hashmap given the element id (for instance a user id) and the key (for instance "password").
func (*HashMap) RemoveIndexTable ¶
RemoveIndexTable removes the INDEX table for this hash map
type HashMap2 ¶ added in v1.2.14
type HashMap2 struct {
// contains filtered or unexported fields
}
HashMap2 contains a KeyValue struct and a dbDatastructure. Each value is a JSON data blob and can contains sub-keys.
func NewHashMap2 ¶ added in v1.2.14
NewHashMap2 creates a new HashMap2 struct
func (*HashMap2) AllPossibleKeys ¶ added in v1.7.1
AllPossibleKeys returns all encountered keys for all owners
func (*HashMap2) AllWhere ¶ added in v1.2.14
AllWhere returns all owner ID's that has a property where key == value
func (*HashMap2) DelKey ¶ added in v1.2.14
DelKey removes a key of an owner in a hashmap (for instance the email field for a user)
func (*HashMap2) Exists ¶ added in v1.2.14
Exists checks if a given owner exists as a hash map at all.
func (*HashMap2) Get ¶ added in v1.2.14
Get a value. Returns: value, error If a value was not found, an empty string is returned.
func (*HashMap2) Keys ¶ added in v1.2.14
Keys loops through absolutely all owners and all properties in the database and returns all found keys.
func (*HashMap2) Set ¶ added in v1.2.14
Set a value in a hashmap given the element id (for instance a user id) and the key (for instance "password")
func (*HashMap2) SetLargeMap ¶ added in v1.4.2
SetLargeMap will add many owners+keys/values, in a single transaction, without checking if they already exists. It also does not check if the keys or property keys contains fieldSep (¤) or not, for performance. These must all be brand new "usernames" (the first key), and not be in the existing hm2.OwnerSet(). This function has good performance, but must be used carefully.
type Host ¶
type Host struct {
// contains filtered or unexported fields
}
Host represents a PostgreSQL database
func NewHost ¶
NewHost sets up a new database connection. connectionString may be on the form "username:password@host:port/database".
func NewHost2 ¶
NewHost2 sets up a new database connection. connectionString may be on the form "username:password@host:port/database". An error may be returned.
func NewHostWithDSN ¶
NewHostWithDSN creates a new database connection with a valid DSN.
func NewHostWithDSN2 ¶
NewHostWithDSN2 creates a new database connection with a valid DSN. An error may be returned.
func (*Host) SelectDatabase ¶
SelectDatabase sets a different database name and creates the database if needed.
func (*Host) SetRawUTF8 ¶
SetRawUTF8 can be used to select if the UTF-8 data be unprocessed, and not hex encoded and compressed. Unprocessed UTF-8 may be slightly faster, but malformed UTF-8 strings can potentially cause problems. Encoding the strings before sending them to PostgreSQL is the default. Choose the setting that best suits your situation.
type KeyValue ¶
type KeyValue dbDatastructure
KeyValue is a hash map with a key and a value, stored in PostgreSQL
func NewKeyValue ¶
NewKeyValue creates a new KeyValue struct, for storing key/value pairs.
func (*KeyValue) CountInt64 ¶ added in v1.6.1
CountInt64 counts the number of keys
func (*KeyValue) CreateIndexTable ¶
CreateIndexTable creates an INDEX table for this key/value, that may speed up lookups
func (*KeyValue) Dec ¶ added in v1.2.14
Dec increases the value of a key and returns the new value. Returns "1" if no previous value is found.
func (*KeyValue) Inc ¶
Inc increases the value of a key and returns the new value. Returns "1" if no previous value is found.
func (*KeyValue) RemoveIndexTable ¶
RemoveIndexTable removes the INDEX table for this key/value
type List ¶
type List dbDatastructure
List is a list of strings, stored in PostgreSQL
func (*List) CountInt64 ¶ added in v1.2.16
CountInt64 counts the number of elements in this list (int64)
func (*List) LastN ¶
LastN retrieves the N last elements of a list. If there are too few available elements, the values that were found are returned, together with a TooFewElementsError.
func (*List) RemoveByIndex ¶
RemoveByIndex can remove the Nth item, in the same order as returned by All()
type PostgresCreator ¶
type PostgresCreator struct {
// contains filtered or unexported fields
}
PostgresCreator is a general struct to create datatypes with. The main purpose is to implement pinterface.ICreator.
func NewCreator ¶
func NewCreator(host *Host) *PostgresCreator
NewCreator can be used to create a new PostgresCreator. The main purpose is to implement pinterface.ICreator.
func (*PostgresCreator) NewHashMap ¶
func (m *PostgresCreator) NewHashMap(id string) (pinterface.IHashMap, error)
NewHashMap can be used to create a new pinterface.IHashMap. The main purpose is to implement pinterface.ICreator.
func (*PostgresCreator) NewKeyValue ¶
func (m *PostgresCreator) NewKeyValue(id string) (pinterface.IKeyValue, error)
NewKeyValue can be used to create a new pinterface.IKeyValue. The main purpose is to implement pinterface.ICreator.
func (*PostgresCreator) NewList ¶
func (m *PostgresCreator) NewList(id string) (pinterface.IList, error)
NewList can be used to create a new pinterface.IList. The main purpose is to implement pinterface.ICreator.
func (*PostgresCreator) NewSet ¶
func (m *PostgresCreator) NewSet(id string) (pinterface.ISet, error)
NewSet can be used to create a new pinterface.ISet. The main purpose is to implement pinterface.ICreator.
type Set ¶
type Set dbDatastructure
Set is a set of strings, stored in PostgreSQL
func (*Set) CountInt64 ¶ added in v1.2.16
CountInt64 counts the number of elements in this list (int64)
Source Files
Directories