minidb

package module
v0.0.9 Latest Latest
Warning

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

 Go to latest Published: Sep 14, 2019 License: BSD-3-Clause Imports: 19 Imported by: 0

README

Minidb

-- a minimalist database for Golang and a key-value database command line tool

GoDoc Go Report Card License

Minidb is an early version of an SQL database wrapper library and a command line database written in Go. It currently allows you to create tables with "fields", where each field may contain a string, int, blob, or date. It also has types string-list, int-list, blob-list, and date-list. Tables and their fields can then be queried by the command line tool minidb. Use the --help command line option for more information about the CLI tool.

The database uses an existing SQL driver and wraps around it. The command line tool uses Sqlite3 and the library is also only tested with Sqlite. I try to avoid using Sqlite-specific constructs but currently do not guarantee that it will work with other SQL databases.

The Library

You can use go get github.com/rasteric/minidb to import the library. The library for Go has two APIs. The direct API provides functions for manipulating the database, most of which work on the basis of an MDB structure. This structure stores the driver and is obtained via the Open function. The direct API functions are pretty straightforward wrapper to the underlying SQL database. Although there are many internal error checks, you ought never manipulate the underlying database directly, though.

The indirect API uses Command and Result structures that provide an additional abstraction layer on top of the direct API. These structures can be marshalled and unmarshalled to JSON, which allows them to be used in client/server architectures. A function Exec executes a Command and returns a Result. For convenience, functions are provided that return commands and take a numerical database id instead of a pointer to MDB as the first argument, but otherwise mirror the direct API exactly. For example, the counterpart to (db *MDB) GetFields(table string) ([]Field, error) is GetFieldsCommand(db CommandDB, table string) *Command.

The command line tool in the cmd directory uses the indirect API to implement inter-process communication between the command line tool cmd/minidb/minidb and the local server in cmd/mdbserve/mdbserve.

Public functions in the source code are commented unless they are easy to read.

The Command Line Tool

The command line tool is in cmd/minidb/minidb and uses a relative path to the server executable by default. Use the --help option to get information about its usage. One important thing that is not documented yet, because it's not fully finished, is the find query syntax. It works like this: You can only search within one table at a time and combine field queries with boolean operators and, or, and not. List fields allow additional prefix-operators every and no. The actual query format is fieldname=like-clause.

Examples:

minidb table Person string-list Name string ZIP int Age Email string

creates a table Person with a Name field that can store a list of strings, a ZIP field that stores a string, an Age field that stores an integer, and an Email field that stores a string.

minidb new Person

returns a numeric id for a new Person.

minidb set Person 1 Name John Caesar Smith Jr

sets the name of Person 1 to the list of strings "John", "Caesar", "Smith", "Jr" (since the shell splits up the strings in this way).

minidb find Person Name=%John%

look for every person whose name contains the string "John".

minidb find Person every Name=%r% and ZIP=111%

look for every Person whose name is such that every name string contains the letter "r" and whose ZIP string starts with "111". This assumes that Person Name is a string-list.

minidb find Person no Name=John

assuming that Person Name is of type string-list, this query matches all Persons for which no Name list entry is "John".

minidb find Person Name=John or Name=Smith%

find every Person whose Name is exactly "John" (in one of its Name fields, if it is a string-list) or whose name starts with "Smith" (in one of its Name entries, if it is a string-list).

minidb set-str 1 "Hello world!"

sets the string with numeric key 1 to "Hello world!"

minidb get-str 1

returns "Hello world!" + newline if the previous command has been executed before.

In the key-value interface all keys are integers.

Documentation

Overview

Package minidb is a minimalist database. It stores items in tables, where each item has a fixed number of fields. The package has two APIs. The direct API is centered around MDB structures that represent database connections. Functions of MDB call directly the underlying database layer. The second API is slower and may be used for cases when commands and results have to be serialized. It uses Command structures that are created by functions like OpenCommand, AddTableCommand, etc. These are passed to Exec() which returns a Result structure that is populated with result values.

Index

Constants

View Source 
const (
	NoErr int64 = iota + 1
	ErrCannotOpen
	ErrUnknownDB
	ErrUnknownCommand
	ErrAddTableFailed
	ErrClosingDB
	ErrCountFailed
	ErrFindFailed
	ErrGetFailed
	ErrGetTablesFailed
	ErrListItemsFailed
	ErrNewItemFailed
	ErrParseFieldValuesFailed
	ErrSetFailed
	ErrToSQLFailed
	ErrFieldExistsFailed
	ErrGetFieldsFailed
	ErrInvalidDate
	ErrBackupFailed
	ErrRemoveItemFailed
	ErrIndexFailed
	ErrUnknownTx
	ErrBeginFailed
	ErrCommitFailed
	ErrRollbackFailed
)

Numeric error codes returned by Exec() in a Result structure's Int field.

Variables

This section is empty.

Functions

func CloseAllDBs 

func CloseAllDBs()

CloseAllDBs closes all open DB connections and cleans up resources.

func CreateDirIfNotExist added in v0.0.8 

func CreateDirIfNotExist(dir string) error

CreateDirIfNotExists creates a directory including all subdirectories needed, or returns an error.

func Fail 

func Fail(msg string, args ...interface{}) error

Fail returns a new error message formatted with fmt.Sprintf.

func GenerateExternalSalt added in v0.0.8 

func GenerateExternalSalt(params *Params) []byte

GenerateExternalSalt returns some new external salt of the length specified in params. This salt should be passed to NewUser and can be used for passphrase hashing prior to calling NewUser. It is stored in the user database and can be retrieved as ExternalSalt.

func GenerateKey added in v0.0.8 

func GenerateKey(password string, salt []byte, params *Params) *saltedKey

GenerateKey takes a password and some salt, and generates a salted key of length 64 bytes. Use the ExternalSalt as salt and the original, unaltered password. The function use Blake2b-512 for key derivation.

func GetUserTypeString 

func GetUserTypeString(field FieldType) string

GetUserTypeString returns a user-readable string for the type of a field.

func ParseTime added in v0.0.3 

func ParseTime(s string) (time.Time, error)

ParseTime parses a time string in RFC3339 format and returns the time or an error if the format is wrong.

func QuerySortToStr added in v0.0.4 

func QuerySortToStr(s QuerySort) string

QuerySortToStr convert the sort of a query to a string. This is merely used for debugging and testing.

Types

type Command 

type Command struct {
	ID        CommandID `json:"id"`
	DB        CommandDB `json:"dbid"`
	Tx        TxID      `json:"txid"`
	StrArgs   []string  `json:"strings"`
	ItemArg   Item      `json:"item"`
	FieldArgs []Field   `json:"fields"`
	ValueArgs []Value   `json:"values"`
	QueryArg  Query     `json:"query"`
	IntArg    int64     `json:"int"`
	IntArg2   int64     `json:"int2"`
}

Command structures contains all information needed to execute an arbitrary command. Use Exec() to execute a command and get the result. Every function <Name> in minidb has a corresponding function <Name>Command that returns the corresponding command. Consult the API for <Name> for help, as the input parameters are exactly the same, except that the first two arguments are a database path of type CommandDB and often also a transaction id of type TxID. You should never use Command structures directly, but use the provided wrapper functions for strong typing. Result structures have the HasError field set to true if an error has occurred. Commands and results can be serialized to json.

func AddTableCommand 

func AddTableCommand(db CommandDB, table string, fields []Field) *Command

AddTableCommand returns a pointer to a command structure for mdb.AddTable().

func BackupCommand added in v0.0.8 

func BackupCommand(db CommandDB, destination string) *Command

BackupCommand returns a pointer to a command structure for tx.Backup().

func BeginCommand added in v0.0.8 

func BeginCommand(db CommandDB) *Command

BeginCommand returns a pointer to a command structure for mdb.Begin().

func CloseCommand 

func CloseCommand(db CommandDB) *Command

CloseCommand returns a pointer to a command structure for mdb.Close().

func CommitCommand added in v0.0.8 

func CommitCommand(db CommandDB, tx TxID) *Command

CommitCommand returns a pointer to a command structure for tx.Commit().

func CountCommand 

func CountCommand(db CommandDB, table string) *Command

CountCommand returns a pointer to a command structure for tx.Count()

func DeleteBlobCommand added in v0.0.3 

func DeleteBlobCommand(db CommandDB, tx TxID, key int64) *Command

DeleteBlobCommand returns a pointer to a command structure for tx.DeleteBlob().

func DeleteDateCommand added in v0.0.3 

func DeleteDateCommand(db CommandDB, tx TxID, key int64) *Command

DeleteDateCommand returns a pointer to a command structure for tx.DeleteDate().

func DeleteIntCommand added in v0.0.3 

func DeleteIntCommand(db CommandDB, tx TxID, key int64) *Command

DeleteIntCommand returns a pointer to a command structure for tx.DeleteInt().

func DeleteStrCommand added in v0.0.3 

func DeleteStrCommand(db CommandDB, tx TxID, key int64) *Command

DeleteStrCommand returns a pointer to a command structure for tx.DeleteStr().

func FieldExistsCommand 

func FieldExistsCommand(db CommandDB, table string, field string) *Command

FieldExistsCommand returns a pointer to a command structure for tx.FieldExists().

func FieldIsEmptyCommand added in v0.0.5 

func FieldIsEmptyCommand(db CommandDB, item Item, field string) *Command

FieldIsEmptyCommand returns a pointer to a command structure for tx.FieldIsEmpty().

func FieldIsNullCommand 

func FieldIsNullCommand(db CommandDB, item Item, field string) *Command

FieldIsNullCommand returns a pointer to a command structure for tx.FieldIsNull().

func FindCommand 

func FindCommand(db CommandDB, query *Query, limit int64) *Command

FindCommand returns a pointer to a command structure for tx.Find().

func GetBlobCommand added in v0.0.3 

func GetBlobCommand(db CommandDB, key int64) *Command

GetBlobCommand returns a pointer to a command structure for tx.GetBlob().

func GetCommand 

func GetCommand(db CommandDB, table string, item Item, field string) *Command

GetCommand returns a pointer to a command structure for tx.Get().

func GetDateCommand added in v0.0.3 

func GetDateCommand(db CommandDB, key int64) *Command

GetDateCommand returns a pointer to a command structure for tx.GetDate().

func GetFieldsCommand 

func GetFieldsCommand(db CommandDB, table string) *Command

GetFieldsCommand returns a pointer to a command structure for tx.GetFields().

func GetIntCommand added in v0.0.3 

func GetIntCommand(db CommandDB, key int64) *Command

GetIntCommand returns a pointer to a command structure for tx.GetInt().

func GetStrCommand added in v0.0.3 

func GetStrCommand(db CommandDB, key int64) *Command

GetStrCommand returns a pointer to a command structure for tx.GetStr().

func GetTablesCommand 

func GetTablesCommand(db CommandDB) *Command

GetTablesCommand returns a pointer to a command structure for tx.GetTables().

func HasBlobCommand added in v0.0.3 

func HasBlobCommand(db CommandDB, key int64) *Command

HasBlobCommand returns a pointer to a command structure for tx.HasBlob().

func HasDateCommand added in v0.0.3 

func HasDateCommand(db CommandDB, key int64) *Command

HasDateCommand returns a pointer to a command structure for tx.HasDate().

func HasIntCommand added in v0.0.3 

func HasIntCommand(db CommandDB, key int64) *Command

HasIntCommand returns a pointer to a command structure for tx.HasInt().

func HasStrCommand added in v0.0.3 

func HasStrCommand(db CommandDB, key int64) *Command

HasStrCommand returns a pointer to a command structure for tx.HasStr().

func IndexCommand added in v0.0.8 

func IndexCommand(db CommandDB, tx TxID, table string, field string) *Command

IndexCommand returns a pointer to a command structure for tx.Index().

func IsEmptyListFieldCommand 

func IsEmptyListFieldCommand(db CommandDB, table string, item Item, field string) *Command

IsEmptyListFieldCommand returns a pointer to a command structure for tx.IsEmptyListField().

func IsListFieldCommand 

func IsListFieldCommand(db CommandDB, table string, field string) *Command

IsListFieldCommand returns a pointer to a command structure for tx.IsListField().

func ItemExistsCommand 

func ItemExistsCommand(db CommandDB, table string, item Item) *Command

ItemExistsCommand returns a pointer to a command structure for tx.ItemExists().

func ListBlobCommand added in v0.0.3 

func ListBlobCommand(db CommandDB) *Command

ListBlobCommand returns a pointer to a command structure for tx.ListBlob().

func ListDateCommand added in v0.0.3 

func ListDateCommand(db CommandDB) *Command

ListDateCommand returns a pointer to a command structure for tx.ListDate().

func ListIntCommand added in v0.0.3 

func ListIntCommand(db CommandDB, tx TxID) *Command

ListIntCommand returns a pointer to a command structure for tx.ListInt().

func ListItemsCommand 

func ListItemsCommand(db CommandDB, table string, limit int64) *Command

ListItemsCommand returns a pointer to a command structure for tx.ListItems().

func ListStrCommand added in v0.0.3 

func ListStrCommand(db CommandDB) *Command

ListStrCommand returns a pointer to a command structure for tx.ListStr().

func MustGetFieldTypeCommand 

func MustGetFieldTypeCommand(db CommandDB, table string, field string) *Command

MustGetFieldTypeCommand returns a pointer to a command structure for tx.MustGetFieldType().

func NewItemCommand 

func NewItemCommand(db CommandDB, tx TxID, table string) *Command

NewItemCommand returns a pointer to a command structure for tx.NewItem().

func OpenCommand 

func OpenCommand(driver string, file string) *Command

OpenCommand returns a pointer to a command structure for mdb.Open().

func ParseFieldValuesCommand 

func ParseFieldValuesCommand(db CommandDB, table string, field string, data []string) *Command

ParseFieldValuesCommand returns a pointer to a command structure for tx.ParseFieldValues().

func RemoveItemCommand added in v0.0.8 

func RemoveItemCommand(db CommandDB, tx TxID, table string, item Item) *Command

RemoveItemCommand returns a pointer to a command structure for tx.RemoveItem().

func RollbackCommand added in v0.0.8 

func RollbackCommand(db CommandDB, tx TxID) *Command

RollbackCommand returns a pointer to a command structure for tx.Rollback().

func SetBlobCommand added in v0.0.3 

func SetBlobCommand(db CommandDB, tx TxID, key int64, value []byte) *Command

SetBlobCommand returns a pointer to a command structure for tx.SetBlob().

func SetCommand 

func SetCommand(db CommandDB, tx TxID, table string, item Item, field string, data []Value) *Command

SetCommand returns a pointer to a command structure for tx.Set().

func SetDateCommand added in v0.0.3 

func SetDateCommand(db CommandDB, tx TxID, key int64, value time.Time) *Command

SetDateCommand returns a pointer to a command structure for tx.SetDate().

func SetDateStrCommand added in v0.0.3 

func SetDateStrCommand(db CommandDB, tx TxID, key int64, value string) *Command

SetDateStrCommand returns a pointer to a command structure for tx.SetDateStr().

func SetIntCommand added in v0.0.3 

func SetIntCommand(db CommandDB, tx TxID, key int64, value int64) *Command

SetIntCommand returns a pointer to a command structure for tx.SetInt().

func SetStrCommand added in v0.0.3 

func SetStrCommand(db CommandDB, tx TxID, key int64, value string) *Command

SetStrCommand returns a pointer to a command structure for tx.SetStr().

func TableExistsCommand 

func TableExistsCommand(db CommandDB, table string) *Command

TableExistsCommand returns a pointer to a command structure for tx.TableExists().

func ToSqlCommand 

func ToSqlCommand(db CommandDB, table string, query *Query, limit int64) *Command

ToSqlCommand returns a pointer to a command structure for tx.ToSql().

type CommandDB 

type CommandDB string

CommandDB is the database that has been opened.

type CommandID 

type CommandID int

CommandID represents the type of a command in the Exec() function. 

const (
	// CmdOpen is the type of an Open command struct.
	CmdOpen CommandID = iota + 1
	// CmdBegin opens a transaction
	CmdBegin
	// CmdRollback rolls back a transaction
	CmdRollback
	// CmdCommit commits a transaction
	CmdCommit
	// CmdAddTable is the type of an AddTable command struct.
	CmdAddTable
	// CmdClose is the type of a Close command struct.
	CmdClose
	// CmdCount is the type of a Count command struct.
	CmdCount
	// CmdFind is the type of a Find command struct.
	CmdFind
	// CmdGet is the type of a Get command struct.
	CmdGet
	// CmdGetTables is the type of a GetTables command struct.
	CmdGetTables
	// CmdIsListField is the type of an IsListField command struct.
	CmdIsListField
	// CmdItemExists is the type of an ItemExists command struct.
	CmdItemExists
	// CmdListItems is the type of a ListItems command struct.
	CmdListItems
	// CmdNewItem is the type of a NewItem command struct.
	CmdNewItem
	// CmdParseFieldValues is the type of a ParseFieldValues command struct.
	CmdParseFieldValues
	// CmdSet is the type of a Set command struct.
	CmdSet
	// CmdTableExists is the type of a TableExists command struct.
	CmdTableExists
	// CmdToSQL is the type of a ToSQL command struct.
	CmdToSQL
	// CmdFieldIsNull is the type of a FieldIsNull command struct.
	CmdFieldIsNull
	// CmdFieldExists is the type of a FieldExists command struct.
	CmdFieldExists
	// CmdGetFields is the type of a GetFields command struct.
	CmdGetFields
	// CmdIsEmptyListField is the type of an IsEmptyListField command struct.
	CmdIsEmptyListField
	// CmdMustGetFieldType is the type of a MustGetFieldType command struct.
	CmdMustGetFieldType
	// CmdGetInt is the type of a GetInt command struct.
	CmdGetInt
	// CmdGetStr is the type of a GetStr command struct.
	CmdGetStr
	// CmdGetBlob is the type of a GetBlob command struct.
	CmdGetBlob
	// CmdGetDate is the type of a GetDate command struct.
	CmdGetDate
	// CmdSetInt is the type of a SetInt command struct.
	CmdSetInt
	// CmdSetStr is the type of a SetStr commmand struct.
	CmdSetStr
	// CmdSetBlob is the type of a SetBlob commmand struct.
	CmdSetBlob
	// CmdSetDate is the type of a SetDate command struct.
	CmdSetDate
	// CmdDeleteInt is the type of a DeleteInt command struct.
	CmdDeleteInt
	// CmdDeleteStr is the type of a DeleteStr command struct.
	CmdDeleteStr
	// CmdDeleteBlob is the type of a DeleteBlob command struct.
	CmdDeleteBlob
	// CmdDeleteDate is the type of a DeleteDate command struct.
	CmdDeleteDate
	// CmdHadInt is the type of a HasInt command struct.
	CmdHasInt
	// CmdHasStr is the type of a HasStr command struct.
	CmdHasStr
	// CmdHasBlob is the type of a HasBlob command struct.
	CmdHasBlob
	// CmdHasDate is the type of a HasDate command struct.
	CmdHasDate
	// CmdListInt is the type of a ListInt commmand struct.
	CmdListInt
	// CmdListStr is the type of a ListStr command struct.
	CmdListStr
	// CmdListBlob is the type of a ListBlob command struct.
	CmdListBlob
	// CmdListDate is the type of a ListDate command struct.
	CmdListDate
	// CmdSetDateStr is the type of a SetDateStr command struct.
	CmdSetDateStr
	// CmdFieldIsEmpty is the type of a FieldIsEmpty commmand struct.
	CmdFieldIsEmpty
	// CmdBackup is the type of a Backup commmand struct.
	CmdBackup
	// CmdRemoveItem is the type of a RemoveItem commmand struct.
	CmdRemoveItem
	// CmdIndex is the type of an Index command struct.
	CmdIndex
)

The actual Exec() CommandID values. Names mirror the respective functions.

type ErrCode added in v0.0.8 

type ErrCode int

ErrCode types represent errors instead of error structures. 

const (
	ErrAuthenticationFailed ErrCode = iota + 1 // User authentication has failed (wrong password).
	OK                                         // No error has occured.
	ErrUsernameInUse                           // The user name is already being used.
	ErrEmailInUse                              // The email is already being used.
	ErrCryptoRandFailure                       // The random number generator has failed.
	ErrInvalidParams                           // One or more parameters were invalid.
	ErrUnknownUser                             // The user is not known.
	ErrNotEnoughSalt                           // Insufficiently long salt has been supplied.
	ErrInvalidUser                             // The user name or email is invalid.
	ErrDBClosed                                // The internal housekeeping DB is locked, corrupted, or closed.
	ErrDBFail                                  // A database operation has failed.
	ErrFileSystem                              // A directory or file could not be created.
	ErrNoHome                                  // The user's DB home directory does not exist.
	ErrCloseFailed                             // Could not close the user database.
	ErrOpenFailed                              // Could not open the user database.
	ErrPackFail                                // Compressing user data failed.
	ErrInvalidKey                              // A given salted key is invalid (either nil, or other problems).
	ErrTransactionFail                         // Could not perform op because of a failed transaction.
)

Error codes returned by the functions.

type Field 

type Field struct {
	Name string    `json:"name"`
	Sort FieldType `json:"sort"`
}

Field represents a database field.

func ParseFieldDesc 

func ParseFieldDesc(desc []string) ([]Field, error)

ParseFieldDesc parses the given string slice into a []Field slice based on the format "type name", or returns an error. This can be used for command line parsing.

type FieldType 

type FieldType int

FieldType is a field in the database, which might be a list type or a base type. 

const (
	// DBError represents an error in a field definition.
	DBError FieldType = iota + 1
	// DBInt is the type of an int64 field.
	DBInt
	// DBString is the type of a string field.
	DBString
	// DBBlob is the type of a []byte field.
	DBBlob
	// DBIntList is the type of a list of int64 field.
	DBIntList
	// DBStringList is the type of a list of strings field.
	DBStringList
	// DBBlobList is the type of a list of []byte field, i.e., corresponding to [][]byte.
	DBBlobList
	// DBDate is the type of an RFC 3339 date field.
	DBDate
	// DBDateList is the type of a list of RFC 3339 dates field.
	DBDateList
)

func ToBaseType 

func ToBaseType(t FieldType) FieldType

ToBaseType converts a list type into the list's base type. A non-list type remains unchanged.

type Item 

type Item int64

Item is a database item. Fields and tables are identified by strings.

type MDB 

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

MDB is the main database object.

func Open 

func Open(driver string, file string) (*MDB, error)

Open creates or opens a minidb.

func (*MDB) AddTable 

func (db *MDB) AddTable(table string, fields []Field) error

AddTable is used to create a new table. Table and field names are validated. They need to be alphanumeric sequences plus underscore "_" as the only allowed special character. None of the names may start with an underscore.

func (*MDB) Backup added in v0.0.8 

func (db *MDB) Backup(destination string) error

Backup a database and return the original opened, not the backed up database. The new MDB pointer needs to be used after this method unless an error has occurred since the old one might have become invalid. This function may result in a corrupt copy if the database is open by another process, so you need to make sure that it isn't.

func (*MDB) Base added in v0.0.8 

func (db *MDB) Base() *sql.DB

Base returns the base sqlx.DB that minidb uses for its underlying storage.

func (*MDB) Begin added in v0.0.8 

func (db *MDB) Begin() (*Tx, error)

Begin starts a transaction.

func (*MDB) Close 

func (db *MDB) Close() error

Close closes the database, making sure that all remaining transactions are finished.

func (*MDB) Count 

func (db *MDB) Count(table string) (int64, error)

Count returns the number of items in the table.

func (*MDB) FieldExists 

func (db *MDB) FieldExists(table string, field string) bool

FieldExists returns true if the table has the field, false otherwise.

func (*MDB) FieldIsEmpty added in v0.0.4 

func (db *MDB) FieldIsEmpty(table string, item Item, field string) bool

FieldIsEmpty returns true if the field is null or empty, false otherwise.

func (*MDB) FieldIsNull 

func (db *MDB) FieldIsNull(table string, item Item, field string) bool

FieldIsNull returns true if the field is null for the item in the table, false otherwise.

func (*MDB) Find 

func (db *MDB) Find(query *Query, limit int64) ([]Item, error)

Find items matching the query, return error if the query is ill-formed and the items otherwise.

func (*MDB) Get 

func (db *MDB) Get(table string, item Item, field string) ([]Value, error)

Get returns the value(s) of a field of an item in a table.

func (*MDB) GetBlob added in v0.0.3 

func (db *MDB) GetBlob(key int64) []byte

GetBlob returns the blob value for a key, nil if key doesn't exist.

func (*MDB) GetDate added in v0.0.3 

func (db *MDB) GetDate(key int64) time.Time

GetDate returns the time.Time value of a, January 1, year 1, 00:00:00.000000000 UTC if the key doesn't exist.

func (*MDB) GetDateStr added in v0.0.3 

func (db *MDB) GetDateStr(key int64) string

GetDateStr returns a date in RFC3339 string form, the empty string if the key doesn't exist.

func (*MDB) GetFields 

func (db *MDB) GetFields(table string) ([]Field, error)

GetFields returns the fields that belong to a table, including list fields.

func (*MDB) GetInt added in v0.0.3 

func (db *MDB) GetInt(key int64) int64

GetInt returns the int64 value for a key, 0 if key doesn't exist.

func (*MDB) GetStr added in v0.0.3 

func (db *MDB) GetStr(key int64) string

GetStr returns the string value for a key, "" if key doesn't exist.

func (*MDB) GetTables 

func (db *MDB) GetTables() []string

GetTables returns the tables in the database.

func (*MDB) HasBlob added in v0.0.3 

func (db *MDB) HasBlob(key int64) bool

HasBlob returns true if a byte array value is stored for the key, false otherwise.

func (*MDB) HasDate added in v0.0.3 

func (db *MDB) HasDate(key int64) bool

HasDate returns true if a time.Time value is stored for the key, false otherwise.

func (*MDB) HasInt added in v0.0.3 

func (db *MDB) HasInt(key int64) bool

HasInt returns true if an int value is stored for the key, false otherwise.

func (*MDB) HasStr added in v0.0.3 

func (db *MDB) HasStr(key int64) bool

HasStr returns true of a string value is stored for the key, false otherwise.

func (*MDB) IsEmptyListField 

func (db *MDB) IsEmptyListField(table string, item Item, field string) bool

IsEmptyListField returns true if the field is a list field and has no element matching item. If the item does not exist, the function returns true as well.

func (*MDB) IsListField 

func (db *MDB) IsListField(table string, field string) bool

IsListField is true if the field in the table is a list, false otherwise. List fields are internally stored as special tables.

func (*MDB) ItemExists 

func (db *MDB) ItemExists(table string, item Item) bool

ItemExists returns true if the item exists in the table, false otherwise.

func (*MDB) ListBlob added in v0.0.3 

func (db *MDB) ListBlob() []int64

ListBlob lists all blob keys.

func (*MDB) ListDate added in v0.0.3 

func (db *MDB) ListDate() []int64

ListDate lists all date keys.

func (*MDB) ListInt added in v0.0.3 

func (db *MDB) ListInt() []int64

ListInt lists all int keys.

func (*MDB) ListItems 

func (db *MDB) ListItems(table string, limit int64) ([]Item, error)

ListItems returns a list of items in the table.

func (*MDB) ListStr added in v0.0.3 

func (db *MDB) ListStr() []int64

ListStr lists all string keys.

func (*MDB) MustGetFieldType 

func (db *MDB) MustGetFieldType(table string, field string) FieldType

MustGetFieldType returns the type of the field. This method panics if the table or field don't exist.

func (*MDB) NewItem 

func (db *MDB) NewItem(table string) (Item, error)

NewItem creates a new item in the table and returns its numerical ID.

func (*MDB) ParseFieldValues 

func (db *MDB) ParseFieldValues(table string, field string, data []string) ([]Value, error)

ParseFieldValues parses potential value(s) for a field from strings, returns an error if their type is incompatible with the field type, the table or field don't exist, or if the input is empty. Data for a Blob field must be Base64 encoded, data for an Integer field must be a valid digit sequence for a 64 bit integer in base 10 format.

func (*MDB) TableExists 

func (db *MDB) TableExists(table string) bool

TableExists returns true if the table exists, false otherwise.

func (*MDB) ToSql 

func (db *MDB) ToSql(table string, inquery *Query, limit int64) (string, error)

ToSql returns the sql query for the table, taking into account list fields, or returns an error if the query structure is ill-formed.

func (*MDB) UseItem added in v0.0.8 

func (db *MDB) UseItem(table string, id uint64) (Item, error)

UseItem creates a new item with the given ID or returns the item with the given ID if it already exists. This may be used when fixed IDs are needed, but should be avoided when these are not strictly necessary.

type MultiDB added in v0.0.8 

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

MultiDB contains all information needed for housekeeping multiple DBs, except for the parameters and context-specific information like passwords.

func NewMultiDB added in v0.0.8 

func NewMultiDB(basedir string, driver string) (*MultiDB, error)

NewMultiDB returns a new multi user database.

func (*MultiDB) ArchiveUser added in v0.0.8 

func (m *MultiDB) ArchiveUser(user *User, archivedir string) (ErrCode, error)

ArchiveUser stores the user data in a packed zip file but does not close or remove the user. This can be used for backups or for archiving.

func (*MultiDB) Authenticate added in v0.0.8 

func (m *MultiDB) Authenticate(username string, key *saltedKey) (*User, ErrCode, error)

Authenticate a user by given name and salted password. Returns the user and OK if successful, otherwise nil, a numeric error code and the error. Notice that the external salt is not passed to this function. Instead, the password string should have been prepared (securely hashed, whitened, etc.) before calling this function on the basis of the user's ExternalSalt.

func (*MultiDB) BaseDir added in v0.0.8 

func (m *MultiDB) BaseDir() string

BaseDir returns the base directory of the multiuser database. This directory contains databases for all users.

func (*MultiDB) Begin added in v0.0.8 

func (m *MultiDB) Begin() (*Tx, error)

Begin a transaction.

func (*MultiDB) Close added in v0.0.8 

func (m *MultiDB) Close() (ErrCode, error)

Close the MultiDB, closing the internal housekeeping and all open user databases.

func (*MultiDB) Delete added in v0.0.8 

func (m *MultiDB) Delete() (ErrCode, error)

Delete deletes the whole multiuser db including all housekeeping information and directories. This action cannot be undone.

func (*MultiDB) DeleteUser added in v0.0.8 

func (m *MultiDB) DeleteUser(user *User) (ErrCode, error)

DeleteUser deletes a user and all associated user content from a multiuser database.

func (*MultiDB) DeleteUserContent added in v0.0.8 

func (m *MultiDB) DeleteUserContent(user *User) (ErrCode, error)

DeleteUserContent deletes a user's content in the multiuser database, i.e., all the user data. This action cannot be undone.

func (*MultiDB) ExistingEmail added in v0.0.8 

func (m *MultiDB) ExistingEmail(email string) bool

ExistingEmail returns true if a user with this email address exists, false otherwise.

func (*MultiDB) ExistingUser added in v0.0.8 

func (m *MultiDB) ExistingUser(username string) bool

ExistingUser returns true if a user with the given user name exists, false otherwise.

func (*MultiDB) ExternalSalt added in v0.0.8 

func (m *MultiDB) ExternalSalt(username string) ([]byte, ErrCode, error)

ExternalSalt is the salt associated with a user. It is stored in the database and may be used for hashing the password prior to authentication. The external salt is not used for internal key derivation.

func (*MultiDB) NewUser added in v0.0.8 

func (m *MultiDB) NewUser(username, email string, key *saltedKey) (*User, ErrCode, error)

NewUser creates a new user with given username, email, and password. Based on a strong salt that is only used internally and the Argon2 algorithm with the given parameters an internal key is created and stored in an internal database. The user and OK are returned unless an error has occurred. The integer returned is a numeric error code to make it easier to distinguish certain cases: EmailInUse - the email has already been registered, UsernameInUse - a user with the same user name has already been registered. Both emails and usernames must be unique and cannot be registered twice.

func (*MultiDB) UserDB added in v0.0.8 

func (m *MultiDB) UserDB(user *User) (*MDB, ErrCode, error)

UserDB returns the database of the given user.

func (*MultiDB) UserDir added in v0.0.8 

func (m *MultiDB) UserDir(user *User) string

UserDir returns the given user's directory where the user database is stored.

func (*MultiDB) UserEmail added in v0.0.8 

func (m *MultiDB) UserEmail(user *User) (string, ErrCode, error)

type Params added in v0.0.8 

type Params struct {
	Argon2Memory       uint32
	Argon2Iterations   uint32
	Argon2Parallelism  uint8
	KeyLength          uint32
	InternalSaltLength uint32
	ExternalSaltLength uint32
}

Params contain all the parameters that are used by a multiuser database.

func DefaultParams added in v0.0.8 

func DefaultParams() *Params

DefaultParams returns parameters with reasonable default values that are safe to use. Be aware that default parameters may change from release to release to reflect updates and changes in security requirements.

type Query 

type Query struct {
	Sort     QuerySort `json:"sort"`
	Children []Query   `json:"children"`
	Data     string    `json:"data"`
}

Query represents a simple or complex database query.

func FailedQuery 

func FailedQuery(msg string) *Query

FailedQuery returns a failed Query pointer with the given message as explanation why it failed.

func ParseQuery 

func ParseQuery(s string) (*Query, error)

ParseQuery parses a string representing the part after the table name into a Query structure. Implements the classic Shunting Yard algorithm.

func (*Query) DebugDump added in v0.0.4 

func (q *Query) DebugDump() string

DebugDump returns a string representation of a query. This is used for debugging and testing, the result is neither pretty-printed nor intended for human consumption.

type QuerySort 

type QuerySort int

QuerySort is the type of a query. Some of these sorts are only used internally. 

const (
	// ParseError indicates that query parsing was unsuccessful.
	ParseError QuerySort = iota + 1
	// TableString is the type of a string for a table, e.g. "Person".
	TableString
	// QueryString is the type of a string for a query, i.e., what's right of "=".
	QueryString
	// LogicalAnd is the type of "and".
	LogicalAnd
	// LogicalOr is the type of "or".
	LogicalOr
	// LogicalNot is the type of "not".
	LogicalNot
	// FieldString is the type of a string for a field, e.g. "name".
	FieldString
	// SearchClause is the type of a main search clause (outermost level of a query).
	SearchClause
	// NoTerm is the type of "no" in a list-field query like "Person no name=John".
	NoTerm
	// EveryTerm is the type of "every" in a list-field query like "Person every name=%s%".
	EveryTerm
	// LeftParen is the type of "(" and variants, used internally.
	LeftParen
	// RightParen is the type of ")" and variants, used internally.
	RightParen
	// InfixOP is the type of "=".
	InfixOP
)

The sorts of query entries.

type Result 

type Result struct {
	Str      string   `json:"str"`
	Strings  []string `json:"strings"`
	Int      int64    `json:"int64"`
	Bool     bool     `json:"bool"`
	Items    []Item   `json:"items"`
	Values   []Value  `json:"values"`
	Fields   []Field  `json:"fields"`
	Bytes    []byte   `json:"binary"`
	Ints     []int64  `json:"ints"`
	HasError bool     `json:"iserror"`
}

Result is a structure representing the result of a command execution via Exec(). If an error has occurred, then HasError is true and the Int and S fields contain the numeric error code and the error message string. Otherwise the respective fields are filled in, as corresponding to the return value(s) of the respective function call.

func Exec 

func Exec(cmd *Command) *Result

Exec takes a Command structure and executes it, returning a Result or an error. This function is a large switch, as a wrapper around the more specific API functions. It incurs a runtime penalty and should only used when needed (e.g. when commands have to be marshalled and unmarshalled).

type Tx added in v0.0.8 

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

Tx represents a transaction similar to sql.Tx.

func (*Tx) Commit added in v0.0.8 

func (tx *Tx) Commit() error

Commit the changes to the database.

func (*Tx) DeleteBlob added in v0.0.8 

func (tx *Tx) DeleteBlob(key int64)

DeleteBlob deletes the key and string for given key. It has no effect if the key-value pair doesn't exist.

func (*Tx) DeleteDate added in v0.0.8 

func (tx *Tx) DeleteDate(key int64)

DeleteDate deletes the key and date value for given key. It has no effect if the key-value pair doesn't exist.

func (*Tx) DeleteInt added in v0.0.8 

func (tx *Tx) DeleteInt(key int64)

DeleteInt deletes the key and int value for given key. It has no effect if the key-value pair doesn't exist.

func (*Tx) DeleteStr added in v0.0.8 

func (tx *Tx) DeleteStr(key int64)

DeleteStr deletes the key and string value for given key. It has no effect if the key-value pair doesn't exist.

func (*Tx) Index added in v0.0.8 

func (tx *Tx) Index(table, field string) error

Index creates an index for field in table unless the index exists already. An index increases the search speed of certain string queries on the field, such as "Person name=joh%".

func (*Tx) RemoveItem added in v0.0.8 

func (tx *Tx) RemoveItem(table string, item Item) error

RemoveItem remove an item from the table.

func (*Tx) Rollback added in v0.0.8 

func (tx *Tx) Rollback() error

Rollback the changes in the database.

func (*Tx) Set added in v0.0.8 

func (tx *Tx) Set(table string, item Item, field string, data []Value) error

Set the given values in the item in table and given field. An error is returned if the field types don't match the data.

func (*Tx) SetBlob added in v0.0.8 

func (tx *Tx) SetBlob(key int64, value []byte)

SetBlob stores a byte array by key.

func (*Tx) SetDate added in v0.0.8 

func (tx *Tx) SetDate(key int64, value time.Time)

SetDate stores a time.Time value by key.

func (*Tx) SetDateStr added in v0.0.8 

func (tx *Tx) SetDateStr(key int64, value string)

SetDateStr stores a datetime in RFC3339 format by key. The correctness of the string is not validated. Use this function in combination with GetDateStr to prevent unnecessary conversions.

func (*Tx) SetInt added in v0.0.8 

func (tx *Tx) SetInt(key int64, value int64)

SetInt stores an int64 value by key.

func (*Tx) SetStr added in v0.0.8 

func (tx *Tx) SetStr(key int64, value string)

SetStr stores a string value by key.

type TxID added in v0.0.8 

type TxID int64

TxID is the ID of a transaction.

type User added in v0.0.8 

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

User represents a user.

func (*User) ID added in v0.0.8 

func (u *User) ID() Item

ID returns the ID of the user.

func (*User) Name added in v0.0.8 

func (u *User) Name() string

Name returns the name of the user.

type Value 

type Value struct {
	Str  string    `json:"str"`
	Num  int64     `json:"num"`
	Sort FieldType `json:"sort"`
}

Value holds the values that can be put into the database or retrieved from it.

func NewBytes 

func NewBytes(b []byte) Value

NewBytes creates a value that holds a []byte slice. This is similar to String() but notice that strings and byte slices are handled differently in the database. For example, byte slices may contain NULL characters and may be converted to and from Base64.

func NewDate 

func NewDate(t time.Time) Value

NewDate create a value that holds a datetime.

func NewDateStr added in v0.0.3 

func NewDateStr(d string) Value

NewDateStr creates a value that holds a datetime given by a RFC3339 representation. The correctness of the date string is not validated, so use this function with care.

func NewInt 

func NewInt(n int64) Value

NewInt creates a value that stores an int64.

func NewString 

func NewString(s string) Value

NewString creates a value that stores a string.

func (*Value) Bytes 

func (v *Value) Bytes() []byte

Bytes returns the value as a bytes slice. It automatically converts int64 and string. An int64 is written in Little Endian format.

func (*Value) Datetime 

func (v *Value) Datetime() time.Time

Datetime returns the time value and panics of no valid date is stored.

func (*Value) Int 

func (v *Value) Int() int64

Int returns the value as an int64 and panics if conversion is not possible

func (*Value) String 

func (v *Value) String() string

String returns the string value. It automatically converts int and blob, where binary Blob data is Base64 encoded and the int is converted to decimal format.

Source Files

View all Source files

Directories

Path Synopsis
cmd
mdbserve
minidb

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.