sqlstore

README

---

title: sqlstore draft: true

sqlstore

This directory holds the code for implementation collection storage in a SQL database support JSON columns.

Documentation

Overview

sqlstore is a sub module of the dataset package.

Authors R. S. Doiel, <rsdoiel@library.caltech.edu> and Tom Morrel, <tmorrell@library.caltech.edu>

Copyright (c) 2022, Caltech All rights not granted herein are expressly reserved by Caltech.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Index

• Constants
• type Storage
  • func Init(name string, dsnURI string) (*Storage, error)
  • func Open(name string, dsnURI string) (*Storage, error)
  • func (store *Storage) Close() error
  • func (store *Storage) Create(key string, src []byte) error
  • func (store *Storage) Delete(key string) error
  • func (store *Storage) HasKey(key string) bool
  • func (store *Storage) Keys() ([]string, error)
  • func (store *Storage) Length() int64
  • func (store *Storage) Read(key string) ([]byte, error)
  • func (store *Storage) ReadVersion(key string, version string) ([]byte, error)
  • func (store *Storage) SetVersioning(setting int) error
  • func (store *Storage) Update(key string, src []byte) error
  • func (store *Storage) UpdatedKeys(start string, end string) ([]string, error)
  • func (store *Storage) Versions(key string) ([]string, error)

Constants

const (
	// None means versioning is turned off for collection
	None = iota
	// Major means increment the major semver value on creation or update
	Major
	// Minor means increment the minor semver value on creation or update
	Minor
	// Patach means increment the patch semver value on creation or update
	Patch
)

Types

type Storage

type Storage struct {
	// WorkPath holds the path to where the collection definition is held.
	WorkPath string

	// versioning
	Versioning int
	// contains filtered or unexported fields
}

func Init

func Init(name string, dsnURI string) (*Storage, error)

Init creates a table to hold the collection if it doesn't already exist.

func Open

func Open(name string, dsnURI string) (*Storage, error)

Open opens the storage system and returns an storage struct and error It is passed either a filename. For a Pairtree the would be the path to collection.json and for a sql store file holding a DSN URI. The DSN URI is formed from a protocal prefixed to the DSN. E.g. for a SQLite connection to test.ds database the DSN URI might be "sqlite://collections.db".

```

store, err := c.Store.Open(c.Name, c.DsnURI)
if err != nil {
   ...
}

```

func (*Storage) Close

func (store *Storage) Close() error

Close closes the storage system freeing resources as needed.

```

if err := storage.Close(); err != nil {
   ...
}

```

func (*Storage) Create

func (store *Storage) Create(key string, src []byte) error

Create stores a new JSON object in the collection It takes a string as a key and a byte slice of encoded JSON

err := storage.Create("123", []byte(`{"one": 1}`))
if err != nil {
   ...
}

func (*Storage) Delete

func (store *Storage) Delete(key string) error

Delete removes a JSON document from the collection

key := "123"
if err := storage.Delete(key); err != nil {
   ...
}

func (*Storage) HasKey

func (store *Storage) HasKey(key string) bool

HasKey will look up and make sure key is in collection. Storage must be open or zero false will always be returned.

```

key := "123"
if store.HasKey(key) {
   ...
}

```

func (*Storage) Keys

func (store *Storage) Keys() ([]string, error)

Keys returns all keys in a collection as a slice of strings.

var keys []string
keys, _ = storage.Keys()
/* iterate over the keys retrieved */
for _, key := range keys {
   ...
}

func (*Storage) Length

func (store *Storage) Length() int64

Length returns the number of records (count of rows in collection). Requires collection to be open.

func (*Storage) Read

func (store *Storage) Read(key string) ([]byte, error)

Read retrieves takes a string as a key and returns the encoded JSON document from the collection

src, err := storage.Read("123")
if err != nil {
   ...
}
obj := map[string]interface{}{}
if err := json.Unmarshal(src, &obj); err != nil {
   ...
}

func (*Storage) ReadVersion

func (store *Storage) ReadVersion(key string, version string) ([]byte, error)

ReadVersion returns a specific version of a JSON object.

func (*Storage) SetVersioning

func (store *Storage) SetVersioning(setting int) error

SetVersioning sets versioning to Major, Minor, Patch or None If versioning is set to Major, Minor or Patch a table in the open SQL storage engine will be created.

func (*Storage) Update

func (store *Storage) Update(key string, src []byte) error

Update takes a key and encoded JSON object and updates a

key := "123"
src := []byte(`{"one": 1, "two": 2}`)
if err := storage.Update(key, src); err != nil {
   ...
}

func (*Storage) UpdatedKeys

func (store *Storage) UpdatedKeys(start string, end string) ([]string, error)

UpdatedKeys returns all keys updated in a time range

```

var (
   keys []string
   start = "2022-06-01 00:00:00"
   end = "20022-06-30 23:23:59"
)
keys, _ = storage.UpdatedKeys(start, end)
/* iterate over the keys retrieved */
for _, key := range keys {
   ...
}

```

func (*Storage) Versions

func (store *Storage) Versions(key string) ([]string, error)

Versions return a list of semver strings for a versioned object.