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: 2.11.0 (also tagged as 1.2.11)
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) 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) JSON(owner string) (string, 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) SetMap(owner string, items map[string]string) error
- type Host
- type KeyValue
- func (kv *KeyValue) Clear() error
- func (kv *KeyValue) CreateIndexTable() error
- func (kv *KeyValue) Del(key string) 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) GetAll() ([]string, error)
- func (l *List) GetLast() (string, error)
- func (l *List) GetLastN(n int) ([]string, 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
Constants ¶
const (
// Version number. Stable API within major version numbers.
Version = 2.11
)
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) 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 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) CreateIndexTable ¶
CreateIndexTable creates an INDEX table for this key/value, that may speed up lookups
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) 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.
Source Files
Directories