keyvalue

type Connection interface {
	metrics.Metricsable
	log.Logable
	io.Closer
	// DriverName returns the name of the associated driver.
	DriverName() string
	// ListDatabases returns the names of the available databases. The names
	// are sorted in increasing order. This is not supported by every driver,
	// in which case errors.OperationNotSupported will be returned.
	ListDatabases(ctx context.Context) ([]string, error)
	// CreateDatabase creates a database with the given name on the
	// connection.
	CreateDatabase(ctx context.Context, name string) error
	// DeleteDatabase deletes the indicated database on the connection. Does
	// not return an error if the table does not exist.
	DeleteDatabase(ctx context.Context, name string) error
	// ConnectToDatabase connects to the indicated database.
	ConnectToDatabase(ctx context.Context, name string) (Database, error)
}

type Database interface {
	metrics.Metricser
	log.Logger
	io.Closer
	// Name return the database name.
	Name() string
	// ListTables returns the names of the tables in the database. The names
	// are sorted in increasing order.
	ListTables(ctx context.Context) ([]string, error)
	// CreateTable creates a table with the given name in the database.
	//
	// The provided template will be used by the underlying storage-engine
	// to create the new table if appropriate; the storage-engine is free to
	// ignore the template if it is not required (for example, in a
	// schema-less database).
	CreateTable(ctx context.Context, name string, template record.Record) error
	// DeleteTable deletes the indicated table from the database. Does not
	// return an error if the table does not exist.
	DeleteTable(ctx context.Context, name string) error
	// RenameTable changes the name of a table in the database.
	RenameTable(ctx context.Context, oldname string, newname string) error
	// ConnectToTable connects to the indicated table in the database.
	ConnectToTable(ctx context.Context, name string) (Table, error)
}

type ReaderError interface {
	Error() string // Error returns a string representation of the error.
	Line() uint64  // Line returns the line number on which the error occurred.
	Index() uint64 // Index returns the record index for which the error occurred (indexed from 1).
	Key() string   // Key returns the key associated with this error, if known.
}

type ReaderOptions struct {
	Template           record.Record // Specifies the value types.
	AllowDuplicateKeys bool          // If true, duplicate keys are allowed, with only the most recently read value appearing in the read record.
	AllowEmptyKeys     bool          // If true, allow the read record to have empty keys.
	AllowMissingKeys   bool          // If true, allow read records not to have all the keys in Template; that is, there may be keys in Template that are missing from the read record.
	AllowUnknownKeys   bool          // If true, allow read records to have keys not in Template; that is, there may be keys in the read record that are missing from Template. The type of the associated value will be a string. Note that if IgnoreUnknownKeys is true then AllowUnknownKeys is ignored.
	IgnoreUnknownKeys  bool          // If true, ignore any keys not in Template; that is, any keys not in Template will be skipped and will be omitted from the read record. Note that IgnoreUnknownKeys takes priority over AllowUnknownKeys.
}

type Table interface {
	metrics.Metricser
	log.Logger
	io.Closer
	// Name return the table name.
	Name() string
	// Describe returns a best-guess template for the data in this table.
	//
	// Note that the accuracy of this template depends on the underlying
	// storage engine. It might not be possible to return an exact
	// description (for example, in a schema-less database), and in this
	// case we return a good guess based on a sample of the data available.
	Describe(ctx context.Context) (record.Record, error)
	// Count returns the number of records in the table that match
	// "selector".
	Count(ctx context.Context, selector record.Record) (int64, error)
	// CountWhere returns the number of records in the table that satisfy
	// condition "cond" (which may be nil if there are no conditions).
	CountWhere(ctx context.Context, cond condition.Condition) (int64, error)
	// InsertRecords inserts the given records into the table.
	InsertRecords(ctx context.Context, records ...record.Record) error
	// Insert inserts the records in the given iterator into the table.
	Insert(ctx context.Context, itr record.Iterator) error
	// Update updates all records in the table that match "selector" by
	// setting all keys present in "replacement" to the given values.
	// Returns the number of records updated.
	Update(ctx context.Context, replacement record.Record, selector record.Record) (int64, error)
	// UpdateWhere updates all records in the table that satisfy condition
	// "cond" (which may be nil if there are no conditions) by setting all
	// keys present in "replacement" to the given values. Returns the number
	// of records updated.
	UpdateWhere(ctx context.Context, replacement record.Record, cond condition.Condition) (int64, error)
	// Select returns the records matching "selector", sorted as specified
	// by "order" (which may be nil if there is no sort order required).
	// The returned records will be in the form specified by "template".
	Select(ctx context.Context, template record.Record, selector record.Record, order sort.OrderBy) (record.Iterator, error)
	// SelectWhere returns the results satisfying condition "cond" (which
	// may be nil if there are no conditions), sorted as specified by
	// "order" (which may be nil if there is no sort order required). The
	// returned records will be in the form specified by "template".
	SelectWhere(ctx context.Context, template record.Record, cond condition.Condition, order sort.OrderBy) (record.Iterator, error)
	// SelectLimit returns at most n records matching "selector", sorted as
	// specified by "order" (which may be nil if there is no sort order
	// required). The returned records will be in the form specified by
	// "template".
	SelectLimit(ctx context.Context, template record.Record, selector record.Record, order sort.OrderBy, n int64) (record.Iterator, error)
	// SelectWhereLimit returns at most n results satisfying condition
	// "cond" (which may be nil if there are no conditions), sorted as
	// specified by "order" (which may be nil if there is no sort order
	// required). The returned records will be in the form specified by
	// "template".
	SelectWhereLimit(ctx context.Context, template record.Record, cond condition.Condition, order sort.OrderBy, n int64) (record.Iterator, error)
	// SelectOne returns the first record matching "selector", sorted as
	// specified by "order" (which may be nil if there is no sort order
	// required). The returned record will be in the form specified by
	// "template". If no records match, then a nil record will be returned.
	SelectOne(ctx context.Context, template record.Record, selector record.Record, order sort.OrderBy) (record.Record, error)
	// SelectOneWhere returns the first record satisfying condition "cond"
	// (which may be nil if there are no conditions), sorted as specified by
	// "order" (which may be nil if there is no sort order required). The
	// returned record will be in the form specified by "template". If no
	// records match, then a nil record will be returned.
	SelectOneWhere(ctx context.Context, template record.Record, cond condition.Condition, order sort.OrderBy) (record.Record, error)
	// Delete deletes those records in the table that match "selector".
	// Returns the number of records deleted.
	Delete(ctx context.Context, selector record.Record) (int64, error)
	// DeleteWhere deletes those records in the table that satisfy condition
	// "cond" (which may be nil if there are no conditions). Returns the
	// number of records deleted.
	DeleteWhere(ctx context.Context, cond condition.Condition) (int64, error)
	// AddIndex adds an index on the given key. If an index already exists,
	// this index is unmodified and nil is returned.
	AddIndex(ctx context.Context, key string) error
	// DeleteIndex deletes the index on the given key. If no index is
	// present, nil is returned.
	DeleteIndex(ctx context.Context, key string) error
	// ListIndices lists the keys for which indices are present. The keys
	// are sorted in increasing order.
	ListIndices(ctx context.Context) ([]string, error)
	// AddKeys updates each record r the table, adding any keys in rec that
	// are not already present along with the corresponding values. Any keys
	// that are already present in r will be left unmodified.
	AddKeys(ctx context.Context, rec record.Record) error
	// AddKey updates each record r in the table, adding the given
	// key-value pair if key is not already present in r.
	AddKey(ctx context.Context, key string, value interface{}) error
	// DeleteKeys updates each record in the table, deleting all the
	// specified keys if present.
	DeleteKeys(ctx context.Context, keys []string) error
	// DeleteKey updates each record in the table, deleting the specified
	// key if present.
	DeleteKey(ctx context.Context, key string) error
}