sqobj

README

sqlite3 objects (SQObjects)

This package provides a method forwriting, reading and deleting go objects (structures) to and from SQLite databases. Not exactly a full "Object Relational Database" but a way to reduce the amount of boilerplate code and error handling need to keep a database in syncronization with objects.

This package is part of a wider project, github.com/mutablelogic/go-sqlite. Please see the module documentation for more information.

The general method is:

1. Use tags on your struct definition to define the database table, columns, indexes and foreign keys;
2. Create a database connection and register the structs you want to use to syncronize with the database. You also need to register foreign key relationships;
3. Create the tables and indexes in the database;
4. Read, write and delete objects using the Read, Write and Delete methods. You may need to use some hook functions to handle foreign key relationships.

For example, the following definition:

type Doc struct {
	A int    `sqlite:"a,autoincrement"`
	B int    `sqlite:"b,unique"`
	C string `sqlite:"c"`
}

Will create a table with the following statement:

CREATE TABLE IF NOT EXISTS main.doc (
  a INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
  b INTEGER,
  c TEXT,
  UNIQUE (b)
)

A fuller explanation of the tags and supported types is provided below. SQObjects is currently in development.

Introduction

TODO

Registering a definition

TODO

Supported scalar types

TODO

Writing objects (inserting and updating)

TODO

Reading objects (selecting)

TODO

Deleting objects

TODO

Documentation

Index

• Constants
• func DeclType(t reflect.Type) string
• func ValueOf(v interface{}) reflect.Value
• type Class
  • func MustRegisterClass(source SQSource, proto interface{}) *Class
  • func RegisterClass(source SQSource, proto interface{}) (*Class, error)
  • func (this *Class) Create(txn SQTransaction, schema string) error
  • func (c *Class) DeleteKeys(txn SQTransaction, v ...interface{}) (int, error)
  • func (c *Class) DeleteRows(txn SQTransaction, row []int64) (int, error)
  • func (this *Class) ForeignKey(parent SQClass, parentcols ...string) SQClass
  • func (c *Class) Insert(txn SQTransaction, v ...interface{}) ([]int64, error)
  • func (this *Class) Proto() reflect.Value
  • func (this *Class) Read(txn SQTransaction) (SQIterator, error)
  • func (this *Class) String() string
  • func (c *Class) UpdateKeys(txn SQTransaction, v ...interface{}) (int, error)
  • func (c *Class) UpsertKeys(txn SQTransaction, v ...interface{}) ([]int64, error)
  • func (this *Class) WithForeignKey(parent SQClass, parentcols ...string) error
• type Iterator
  • func (i *Iterator) Next() interface{}
  • func (i *Iterator) RowId() int64
• type Objects
  • func With(conn SQConnection, schema string, classes ...SQClass) (*Objects, error)
  • func WithPool(pool SQPool, schema string, classes ...SQClass) (*Objects, error)
  • func (obj *Objects) String() string
  • func (obj *Objects) Write(ctx context.Context, v ...interface{}) error
• type SQReflect
  • func NewReflect(proto interface{}) (*SQReflect, error)
  • func (this *SQReflect) Column(name string) SQColumn
  • func (this *SQReflect) Columns() []SQColumn
  • func (this *SQReflect) Index(source SQSource, name string) SQIndexView
  • func (this *SQReflect) String() string
  • func (this *SQReflect) Table(source SQSource, ifnotexists bool) []SQStatement
  • func (this *SQReflect) WithForeignKey(parent SQSource, parentcols ...string) error

Constants

const (
	SQKeyNone stkey = iota
	SQKeySelect
	SQKeyInsert
	SQKeyDeleteRows
	SQKeyDeleteKeys
	SQKeyUpdateKeys
	SQKeyUpsertKeys
	SQKeyMax = SQKeyUpdateKeys
)

Functions

func DeclType

func DeclType(t reflect.Type) string

DeclType returns the declared column type for a given field uses TEXT by default. Accepts both scalar types and pointer types

func ValueOf

func ValueOf(v interface{}) reflect.Value

ValueOf returns a struct value or nil if not valid

Types

type Class

type Class struct {
	*SQReflect
	SQSource
	// contains filtered or unexported fields
}

func MustRegisterClass

func MustRegisterClass(source SQSource, proto interface{}) *Class

MustRegisterClass registers a SQObject class, panics if an error occurs.

func RegisterClass

func RegisterClass(source SQSource, proto interface{}) (*Class, error)

RegisterClass registers a SQObject class, returns the class and any errors

func (*Class) Create

func (this *Class) Create(txn SQTransaction, schema string) error

Create creates a table, keys and prepared statements within a transaction. If the flag SQLITE_OPEN_OVERWRITE is set when creating the connection, then tables and indexes are dropped and then re-created.

func (*Class) DeleteKeys

func (c *Class) DeleteKeys(txn SQTransaction, v ...interface{}) (int, error)

Delete keys in table based on primary keys. Returns number of deleted rows

func (*Class) DeleteRows

func (c *Class) DeleteRows(txn SQTransaction, row []int64) (int, error)

Delete from the table based on rowids, returns the number of changes made

func (*Class) ForeignKey

func (this *Class) ForeignKey(parent SQClass, parentcols ...string) SQClass

ForeignKey appends a foreign key constraint, panics on error. Optionally sets the columns to refer to in the parent.

func (*Class) Insert

func (c *Class) Insert(txn SQTransaction, v ...interface{}) ([]int64, error)

Insert into a table and return rowids. If any autoincremented fields are zero valued, these are automatically set to NULL on insert

func (*Class) Proto

func (this *Class) Proto() reflect.Value

Proto returns a prototype of the class

func (*Class) Read

func (this *Class) Read(txn SQTransaction) (SQIterator, error)

Read from table and return an iterator. It is expected that Read would accept a query, including: order, limit, offset, distinct and a list of expressions

func (*Class) String

func (this *Class) String() string

func (*Class) UpdateKeys

func (c *Class) UpdateKeys(txn SQTransaction, v ...interface{}) (int, error)

Update objects by primary key, return number of updated rows

func (*Class) UpsertKeys

func (c *Class) UpsertKeys(txn SQTransaction, v ...interface{}) ([]int64, error)

func (*Class) WithForeignKey

func (this *Class) WithForeignKey(parent SQClass, parentcols ...string) error

WithForeignKey appends a foreign key constraint to the class, returns error. Optionally sets the columns to refer to in the parent.

type Iterator

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

func (*Iterator) Next

func (i *Iterator) Next() interface{}

func (*Iterator) RowId

func (i *Iterator) RowId() int64

type Objects

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

func With

func With(conn SQConnection, schema string, classes ...SQClass) (*Objects, error)

With creates an SQObjects with a database connection and named schema

func WithPool

func WithPool(pool SQPool, schema string, classes ...SQClass) (*Objects, error)

WithPool creates an SQObjects with a connection pool and named schema

func (*Objects) String

func (obj *Objects) String() string

func (*Objects) Write

func (obj *Objects) Write(ctx context.Context, v ...interface{}) error

Write objects (insert or update) to the database

type SQReflect

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

func NewReflect

func NewReflect(proto interface{}) (*SQReflect, error)

Return a reflection object for the given struct or nil if the argument is not a pointer to a struct or has no fields which are exported

func (*SQReflect) Column

func (this *SQReflect) Column(name string) SQColumn

Return a column definition for a given column name

func (*SQReflect) Columns

func (this *SQReflect) Columns() []SQColumn

Return column definitions

func (*SQReflect) Index

func (this *SQReflect) Index(source SQSource, name string) SQIndexView

Return an index definition for a given index name and source table

func (*SQReflect) String

func (this *SQReflect) String() string

func (*SQReflect) Table

func (this *SQReflect) Table(source SQSource, ifnotexists bool) []SQStatement

Return table and index definitions for a given source table adding IF NOT EXISTS to the table and indexes

func (*SQReflect) WithForeignKey

func (this *SQReflect) WithForeignKey(parent SQSource, parentcols ...string) error

WithForeignKey defines a foreign key to a parent class.