simplehstore

package module
v1.8.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 2, 2024 License: BSD-3-Clause Imports: 14 Imported by: 2

README

simplehstore

Build GoDoc License Go Report Card

Easy way to use a PostgreSQL database (and the HSTORE feature) from Go.

Online API Documentation

godoc.org

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 test to work, and a database named test must exist.

License, author and version

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

View Source 
const (
	// VersionString is the current version of simplehstore.
	VersionString = "1.8.1"
)

Variables

View Source 
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")
)
View Source 
var Verbose = false

Verbose can be set to true when testing, for more information

Functions

func Decode 

func Decode(code *string) error

Decode decompresses and decodes an encoded string to an UTF-8 string.

func Encode 

func Encode(value *string) error

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 

func TestConnectionHost(connectionString string) error

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 

func TestConnectionHostWithDSN(connectionString string) error

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 

func NewHashMap(host *Host, name string) (*HashMap, error)

NewHashMap creates a new HashMap struct

func (*HashMap) All 

func (h *HashMap) All() ([]string, error)

All returns all owners for all hash map elements

func (*HashMap) AllWhere 

func (h *HashMap) AllWhere(key, value string) ([]string, error)

AllWhere returns all owner ID's that has a property where key == value

func (*HashMap) Clear 

func (h *HashMap) Clear() error

Clear the contents

func (*HashMap) Count 

func (h *HashMap) Count() (int, error)

Count counts the number of owners for hash map elements

func (*HashMap) CountInt64 added in v1.2.16 

func (h *HashMap) CountInt64() (int64, error)

CountInt64 counts the number of owners for hash map elements

func (*HashMap) CreateIndexTable 

func (h *HashMap) CreateIndexTable() error

CreateIndexTable creates an INDEX table for this hash map, that may speed up lookups

func (*HashMap) Del 

func (h *HashMap) Del(owner string) error

Del removes an element (for instance a user)

func (*HashMap) DelKey 

func (h *HashMap) DelKey(owner, key string) error

DelKey removes a key of an owner in a hashmap (for instance the email field for a user)

func (*HashMap) Exists 

func (h *HashMap) Exists(owner string) (bool, error)

Exists checks if a given owner exists as a hash map at all

func (*HashMap) Get 

func (h *HashMap) Get(owner, key string) (string, error)

Get a value from a hashmap given the element id (for instance a user id) and the key (for instance "password").

func (*HashMap) GetAll 

func (h *HashMap) GetAll() ([]string, error)

GetAll is deprecated in favor of All

func (*HashMap) Has 

func (h *HashMap) Has(owner, key string) (bool, error)

Has checks if a given owner + key exists in the hash map

func (*HashMap) Keys 

func (h *HashMap) Keys(owner string) ([]string, error)

Keys returns all keys for a given owner

func (*HashMap) Remove 

func (h *HashMap) Remove() error

Remove this hashmap

func (*HashMap) RemoveIndexTable 

func (h *HashMap) RemoveIndexTable(owner string) error

RemoveIndexTable removes the INDEX table for this hash map

func (*HashMap) Set 

func (h *HashMap) Set(owner, key, value string) error

Set a value in a hashmap given the element id (for instance a user id) and the key (for instance "password")

func (*HashMap) SetCheck added in v1.2.13 

func (h *HashMap) SetCheck(owner, key, value string) (bool, error)

SetCheck will set a value in a hashmap given the element id (for instance a user id) and the key (for instance "password") Returns true if the key already existed.

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 

func NewHashMap2(host *Host, name string) (*HashMap2, error)

NewHashMap2 creates a new HashMap2 struct

func (*HashMap2) All added in v1.2.14 

func (hm2 *HashMap2) All() ([]string, error)

All returns all owner ID's

func (*HashMap2) AllPossibleKeys added in v1.7.1 

func (hm2 *HashMap2) AllPossibleKeys() ([]string, error)

AllPossibleKeys returns all encountered keys for all owners

func (*HashMap2) AllWhere added in v1.2.14 

func (hm2 *HashMap2) AllWhere(key, value string) ([]string, error)

AllWhere returns all owner ID's that has a property where key == value

func (*HashMap2) Clear added in v1.2.14 

func (hm2 *HashMap2) Clear() error

Clear the contents

func (*HashMap2) Count added in v1.2.14 

func (hm2 *HashMap2) Count() (int64, error)

Count counts the number of owners for hash map elements

func (*HashMap2) Del added in v1.2.14 

func (hm2 *HashMap2) Del(owner string) error

Del removes an element (for instance a user)

func (*HashMap2) DelKey added in v1.2.14 

func (hm2 *HashMap2) DelKey(owner, key string) error

DelKey removes a key of an owner in a hashmap (for instance the email field for a user)

func (*HashMap2) Empty added in v1.6.3 

func (hm2 *HashMap2) Empty() (bool, error)

Empty checks if there are no owners+keys+values

func (*HashMap2) Exists added in v1.2.14 

func (hm2 *HashMap2) Exists(owner string) (bool, error)

Exists checks if a given owner exists as a hash map at all.

func (*HashMap2) Get added in v1.2.14 

func (hm2 *HashMap2) Get(owner, key string) (string, error)

Get a value. Returns: value, error If a value was not found, an empty string is returned.

func (*HashMap2) GetMap added in v1.4.1 

func (hm2 *HashMap2) GetMap(owner string, keys []string) (map[string]string, error)

GetMap can retrieve multiple values in one transaction

func (*HashMap2) Has added in v1.2.14 

func (hm2 *HashMap2) Has(owner, key string) (bool, error)

Has checks if a given owner + key exists in the hash map

func (*HashMap2) Keys added in v1.2.14 

func (hm2 *HashMap2) Keys(owner string) ([]string, error)

Keys loops through absolutely all owners and all properties in the database and returns all found keys.

func (*HashMap2) Remove added in v1.2.14 

func (hm2 *HashMap2) Remove() error

Remove this hashmap

func (*HashMap2) Set added in v1.2.14 

func (hm2 *HashMap2) Set(owner, key, value string) error

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 

func (hm2 *HashMap2) SetLargeMap(allProperties map[string]map[string]string) error

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.

func (*HashMap2) SetMap added in v1.2.14 

func (hm2 *HashMap2) SetMap(owner string, m map[string]string) error

SetMap will set many keys/values, in a single transaction

type Host 

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

Host represents a PostgreSQL database

func New 

func New() *Host

New sets up a connection to the default (local) database host

func NewHost 

func NewHost(connectionString string) *Host

NewHost sets up a new database connection. connectionString may be on the form "username:password@host:port/database".

func NewHost2 

func NewHost2(connectionString string) (*Host, error)

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 

func NewHostWithDSN(connectionString string, dbname string) *Host

NewHostWithDSN creates a new database connection with a valid DSN.

func NewHostWithDSN2 

func NewHostWithDSN2(connectionString string, dbname string) (*Host, error)

NewHostWithDSN2 creates a new database connection with a valid DSN. An error may be returned.

func (*Host) Close 

func (host *Host) Close()

Close the connection

func (*Host) Database 

func (host *Host) Database() *sql.DB

Database returns the underlying *sql.DB database struct

func (*Host) Ping 

func (host *Host) Ping() error

Ping the host

func (*Host) SelectDatabase 

func (host *Host) SelectDatabase(dbname string) error

SelectDatabase sets a different database name and creates the database if needed.

func (*Host) SetRawUTF8 

func (host *Host) SetRawUTF8(enabled bool)

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 

func NewKeyValue(host *Host, name string) (*KeyValue, error)

NewKeyValue creates a new KeyValue struct, for storing key/value pairs.

func (*KeyValue) All added in v1.6.1 

func (kv *KeyValue) All() ([]string, error)

All returns all elements in the set

func (*KeyValue) Clear 

func (kv *KeyValue) Clear() error

Clear this key/value

func (*KeyValue) Count added in v1.6.1 

func (kv *KeyValue) Count() (int, error)

Count counts the number of keys

func (*KeyValue) CountInt64 added in v1.6.1 

func (kv *KeyValue) CountInt64() (int64, error)

CountInt64 counts the number of keys

func (*KeyValue) CreateIndexTable 

func (kv *KeyValue) CreateIndexTable() error

CreateIndexTable creates an INDEX table for this key/value, that may speed up lookups

func (*KeyValue) Dec added in v1.2.14 

func (kv *KeyValue) Dec(key string) (string, error)

Dec increases the value of a key and returns the new value. Returns "1" if no previous value is found.

func (*KeyValue) Del 

func (kv *KeyValue) Del(key string) error

Del removes the given key

func (*KeyValue) Empty added in v1.6.3 

func (kv *KeyValue) Empty() (bool, error)

Empty checks if there are no keys, in an efficient way

func (*KeyValue) Get 

func (kv *KeyValue) Get(key string) (string, error)

Get a value given a key

func (*KeyValue) Inc 

func (kv *KeyValue) Inc(key string) (string, error)

Inc increases the value of a key and returns the new value. Returns "1" if no previous value is found.

func (*KeyValue) Remove 

func (kv *KeyValue) Remove() error

Remove this key/value

func (*KeyValue) RemoveIndexTable 

func (kv *KeyValue) RemoveIndexTable() error

RemoveIndexTable removes the INDEX table for this key/value

func (*KeyValue) Set 

func (kv *KeyValue) Set(key, value string) error

Set a key and value

type List 

type List dbDatastructure

List is a list of strings, stored in PostgreSQL

func NewList 

func NewList(host *Host, name string) (*List, error)

NewList creates a new List. Lists are ordered.

func (*List) Add 

func (l *List) Add(value string) error

Add an element to the list

func (*List) All 

func (l *List) All() ([]string, error)

All retrieves all elements of a list

func (*List) Clear 

func (l *List) Clear() error

Clear the list contents

func (*List) Count added in v1.2.14 

func (l *List) Count() (int, error)

Count counts the number of elements in this list

func (*List) CountInt64 added in v1.2.16 

func (l *List) CountInt64() (int64, error)

CountInt64 counts the number of elements in this list (int64)

func (*List) GetAll 

func (l *List) GetAll() ([]string, error)

GetAll is deprecated in favor of All

func (*List) GetLast 

func (l *List) GetLast() (string, error)

GetLast is deprecated in favor of Last

func (*List) GetLastN 

func (l *List) GetLastN(n int) ([]string, error)

GetLastN is deprecated in favor of LastN

func (*List) Has added in v1.2.14 

func (l *List) Has(owner string) (bool, error)

Has checks if an element exists in the list

func (*List) Last 

func (l *List) Last() (string, error)

Last retrieves the last element of a list

func (*List) LastN 

func (l *List) LastN(n int) ([]string, error)

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) Remove 

func (l *List) Remove() error

Remove this list

func (*List) RemoveByIndex 

func (l *List) RemoveByIndex(index int) error

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 NewSet 

func NewSet(host *Host, name string) (*Set, error)

NewSet creates a new set

func (*Set) Add 

func (s *Set) Add(value string) error

Add an element to the set

func (*Set) All 

func (s *Set) All() ([]string, error)

All returns all elements in the set

func (*Set) Clear 

func (s *Set) Clear() error

Clear the list contents

func (*Set) Count added in v1.2.14 

func (s *Set) Count() (int, error)

Count counts the number of elements in this list

func (*Set) CountInt64 added in v1.2.16 

func (s *Set) CountInt64() (int64, error)

CountInt64 counts the number of elements in this list (int64)

func (*Set) Del 

func (s *Set) Del(value string) error

Del removes an element from the set

func (*Set) GetAll 

func (s *Set) GetAll() ([]string, error)

GetAll is deprecated in favor of All

func (*Set) Has 

func (s *Set) Has(value string) (bool, error)

Has checks if the given value is in the set

func (*Set) Remove 

func (s *Set) Remove() error

Remove this set

Source Files

View all Source files

Directories

Path Synopsis
cmd
repl
simple

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.