Documentation ¶
Overview ¶
Package gorqlite provieds a database/sql-like driver for rqlite, the distributed consistent sqlite.
Copyright (c)2016 andrew fabbro (andrew@fabbro.org)
See LICENSE.md for license. tl;dr: MIT. Conveniently, the same license as rqlite.
Project home page: https://github.com/raindo308/gorqlite
Learn more about rqlite at: https://github.com/rqlite/rqlite
Index ¶
- Constants
- Variables
- func TraceOff()
- func TraceOn(w io.Writer)
- type Connection
- func (conn *Connection) Close()
- func (conn *Connection) ConsistencyLevel() (string, error)
- func (conn *Connection) Leader() (string, error)
- func (conn *Connection) Peers() ([]string, error)
- func (conn *Connection) Query(sqlStatements []string) (results []QueryResult, err error)
- func (conn *Connection) QueryContext(ctx context.Context, sqlStatements []string) (results []QueryResult, err error)
- func (conn *Connection) QueryOne(sqlStatement string) (qr QueryResult, err error)
- func (conn *Connection) QueryOneContext(ctx context.Context, sqlStatement string) (qr QueryResult, err error)
- func (conn *Connection) QueryOneParameterized(statement ParameterizedStatement) (qr QueryResult, err error)
- func (conn *Connection) QueryOneParameterizedContext(ctx context.Context, statement ParameterizedStatement) (qr QueryResult, err error)
- func (conn *Connection) QueryParameterized(sqlStatements []ParameterizedStatement) (results []QueryResult, err error)
- func (conn *Connection) QueryParameterizedContext(ctx context.Context, sqlStatements []ParameterizedStatement) (results []QueryResult, err error)
- func (conn *Connection) Queue(sqlStatements []string) (seq int64, err error)
- func (conn *Connection) QueueContext(ctx context.Context, sqlStatements []string) (seq int64, err error)
- func (conn *Connection) QueueOne(sqlStatement string) (seq int64, err error)
- func (conn *Connection) QueueOneContext(ctx context.Context, sqlStatement string) (seq int64, err error)
- func (conn *Connection) QueueOneParameterized(statement ParameterizedStatement) (seq int64, err error)
- func (conn *Connection) QueueOneParameterizedContext(ctx context.Context, statement ParameterizedStatement) (seq int64, err error)
- func (conn *Connection) QueueParameterized(sqlStatements []ParameterizedStatement) (seq int64, err error)
- func (conn *Connection) QueueParameterizedContext(ctx context.Context, sqlStatements []ParameterizedStatement) (seq int64, err error)
- func (conn *Connection) Request(sqlStatements []string) (results []RequestResult, err error)
- func (conn *Connection) RequestContext(ctx context.Context, sqlStatements []string) (results []RequestResult, err error)
- func (conn *Connection) RequestParameterized(sqlStatements []ParameterizedStatement) (results []RequestResult, err error)
- func (conn *Connection) RequestParameterizedContext(ctx context.Context, sqlStatements []ParameterizedStatement) (results []RequestResult, err error)
- func (conn *Connection) SetConsistencyLevel(levelDesired consistencyLevel) error
- func (conn *Connection) SetExecutionWithTransaction(state bool) error
- func (conn *Connection) Write(sqlStatements []string) (results []WriteResult, err error)
- func (conn *Connection) WriteContext(ctx context.Context, sqlStatements []string) (results []WriteResult, err error)
- func (conn *Connection) WriteOne(sqlStatement string) (wr WriteResult, err error)
- func (conn *Connection) WriteOneContext(ctx context.Context, sqlStatement string) (wr WriteResult, err error)
- func (conn *Connection) WriteOneParameterized(statement ParameterizedStatement) (wr WriteResult, err error)
- func (conn *Connection) WriteOneParameterizedContext(ctx context.Context, statement ParameterizedStatement) (wr WriteResult, err error)
- func (conn *Connection) WriteParameterized(sqlStatements []ParameterizedStatement) (results []WriteResult, err error)
- func (conn *Connection) WriteParameterizedContext(ctx context.Context, sqlStatements []ParameterizedStatement) (results []WriteResult, err error)
- type NullBool
- type NullFloat64
- type NullInt16
- type NullInt32
- type NullInt64
- type NullString
- type NullTime
- type ParameterizedStatement
- type QueryResult
- func (qr *QueryResult) Columns() []string
- func (qr *QueryResult) Map() (map[string]interface{}, error)
- func (qr *QueryResult) Next() bool
- func (qr *QueryResult) NumRows() int64
- func (qr *QueryResult) RowNumber() int64
- func (qr *QueryResult) Scan(dest ...interface{}) error
- func (qr *QueryResult) Slice() ([]interface{}, error)
- func (qr *QueryResult) Types() []string
- type RequestResult
- type StatementErrors
- type WriteResult
Constants ¶
const ( // ConsistencyLevelNone provides no consistency to other nodes. ConsistencyLevelNone consistencyLevel = iota // ConsistencyLevelWeak provides a weak consistency that guarantees the // queries are sent to the leader. ConsistencyLevelWeak // ConsistencyLevelStrong provides a strong consistency and guarantees // that queries are sent and received by other nodes. ConsistencyLevelStrong )
Variables ¶
var ( // ErrClosed indicates that client connection was closed ErrClosed = errors.New("gorqlite: connection is closed") )
Functions ¶
func TraceOff ¶
func TraceOff()
TraceOff turns off tracing output. Once you call TraceOff(), no further info is sent to the io.Writer, unless it is TraceOn'd again.
Types ¶
type Connection ¶
type Connection struct { ID string // generated in init() // contains filtered or unexported fields }
Connection provides the connection abstraction. Note that since rqlite is stateless, there really is no "connection". However, this type holds information such as the current leader, peers, connection string to build URLs, etc.
Connections are assigned a "connection ID" which is a pseudo-UUID for connection identification in trace output only. This helps sort out what's going on if you have multiple connections going at once. It's generated using a non-standards-or-anything-else-compliant function that uses crypto/rand to generate 16 random bytes.
Note that the Connection objection holds info on all peers, gathered at time of Open() from the node specified.
func Open ¶
func Open(connURL string) (*Connection, error)
Open creates and returns a "connection" to rqlite.
Since rqlite is stateless, there is no actual connection. Open() creates and initializes a gorqlite Connection type, which represents various config information.
The URL should be in a form like this:
http://localhost:4001 http:// default, no auth, localhost:4001 https:// default, no auth, localhost:4001, using https http://localhost:1234 http://mary:secret2@localhost:1234 https://mary:secret2@somewhere.example.com:1234 https://mary:secret2@somewhere.example.com // will use 4001
func (*Connection) Close ¶
func (conn *Connection) Close()
Close will mark the connection as closed. It is safe to be called multiple times.
func (*Connection) ConsistencyLevel ¶
func (conn *Connection) ConsistencyLevel() (string, error)
ConsistencyLevel tells the current consistency level
func (*Connection) Leader ¶
func (conn *Connection) Leader() (string, error)
Leader tells the current leader of the cluster
func (*Connection) Peers ¶
func (conn *Connection) Peers() ([]string, error)
Peers tells the current peers of the cluster
func (*Connection) Query ¶
func (conn *Connection) Query(sqlStatements []string) (results []QueryResult, err error)
Query is used to perform SELECT operations in the database. It takes an array of SQL statements and executes them in a single transaction, returning an array of QueryResult.
Query uses context.Background() internally; to specify the context, use QueryContext.
func (*Connection) QueryContext ¶
func (conn *Connection) QueryContext(ctx context.Context, sqlStatements []string) (results []QueryResult, err error)
QueryContext is used to perform SELECT operations in the database. It takes an array of SQL statements and executes them in a single transaction, returning an array of QueryResult.
func (*Connection) QueryOne ¶
func (conn *Connection) QueryOne(sqlStatement string) (qr QueryResult, err error)
QueryOne wraps Query into a single-statement method.
QueryOne uses context.Background() internally; to specify the context, use QueryOneContext.
func (*Connection) QueryOneContext ¶
func (conn *Connection) QueryOneContext(ctx context.Context, sqlStatement string) (qr QueryResult, err error)
QueryOneContext wraps Query into a single-statement method.
func (*Connection) QueryOneParameterized ¶
func (conn *Connection) QueryOneParameterized(statement ParameterizedStatement) (qr QueryResult, err error)
QueryOneParameterized wraps QueryParameterized into a single-statement method.
QueryOneParameterized uses context.Background() internally; to specify the context, use QueryOneParameterizedContext.
func (*Connection) QueryOneParameterizedContext ¶
func (conn *Connection) QueryOneParameterizedContext(ctx context.Context, statement ParameterizedStatement) (qr QueryResult, err error)
QueryOneParameterizedContext wraps QueryParameterizedContext into a single-statement method.
func (*Connection) QueryParameterized ¶
func (conn *Connection) QueryParameterized(sqlStatements []ParameterizedStatement) (results []QueryResult, err error)
QueryParameterized is used to perform SELECT operations in the database.
It takes an array of parameterized SQL statements and executes them in a single transaction, returning an array of QueryResult vars.
QueryParameterized uses context.Background() internally; to specify the context, use QueryParameterizedContext.
func (*Connection) QueryParameterizedContext ¶
func (conn *Connection) QueryParameterizedContext(ctx context.Context, sqlStatements []ParameterizedStatement) (results []QueryResult, err error)
QueryParameterizedContext is used to perform SELECT operations in the database.
It takes an array of parameterized SQL statements and executes them in a single transaction, returning an array of QueryResult vars.
func (*Connection) Queue ¶
func (conn *Connection) Queue(sqlStatements []string) (seq int64, err error)
Queue is used to perform asynchronous writes to the rqlite database as defined in the documentation: https://github.com/rqlite/rqlite/blob/master/DOC/QUEUED_WRITES.md
Queue uses context.Background() internally; to specify the context, use QueueContext. To use Queue with parameterized queries, use QueueParameterized.
func (*Connection) QueueContext ¶
func (conn *Connection) QueueContext(ctx context.Context, sqlStatements []string) (seq int64, err error)
QueueContext is used to perform asynchronous writes to the rqlite database as defined in the documentation: https://github.com/rqlite/rqlite/blob/master/DOC/QUEUED_WRITES.md
To use QueueContext with parameterized queries, use QueueParameterizedContext.
func (*Connection) QueueOne ¶
func (conn *Connection) QueueOne(sqlStatement string) (seq int64, err error)
QueueOne is a convenience method that wraps Queue into a single-statement.
QueueOne uses context.Background() internally; to specify the context, use QueueOneContext.
func (*Connection) QueueOneContext ¶
func (conn *Connection) QueueOneContext(ctx context.Context, sqlStatement string) (seq int64, err error)
QueueOneContext is a convenience method that wraps QueueContext into a single-statement
func (*Connection) QueueOneParameterized ¶
func (conn *Connection) QueueOneParameterized(statement ParameterizedStatement) (seq int64, err error)
QueueOneParameterized is a convenience method that wraps QueueParameterized into a single-statement method.
QueueOneParameterized uses context.Background() internally; to specify the context, use QueueOneParameterizedContext.
func (*Connection) QueueOneParameterizedContext ¶
func (conn *Connection) QueueOneParameterizedContext(ctx context.Context, statement ParameterizedStatement) (seq int64, err error)
QueueOneParameterizedContext is a convenience method that wraps QueueParameterizedContext() into a single-statement method.
func (*Connection) QueueParameterized ¶
func (conn *Connection) QueueParameterized(sqlStatements []ParameterizedStatement) (seq int64, err error)
QueueParameterized is used to perform asynchronous writes with parameterized queries to the rqlite database as defined in the documentation: https://github.com/rqlite/rqlite/blob/master/DOC/QUEUED_WRITES.md
QueueParameterized uses context.Background() internally; to specify the context, use QueueParameterizedContext.
func (*Connection) QueueParameterizedContext ¶
func (conn *Connection) QueueParameterizedContext(ctx context.Context, sqlStatements []ParameterizedStatement) (seq int64, err error)
QueueParameterizedContext is used to perform asynchronous writes with parameterized queries to the rqlite database as defined in the documentation: https://github.com/rqlite/rqlite/blob/master/DOC/QUEUED_WRITES.md
func (*Connection) Request ¶
func (conn *Connection) Request(sqlStatements []string) (results []RequestResult, err error)
Request is used to access Unified Endpoint to send read and writes requests in one operation.
func (*Connection) RequestContext ¶
func (conn *Connection) RequestContext(ctx context.Context, sqlStatements []string) (results []RequestResult, err error)
RequestContext is used to access Unified Endpoint to send read and writes requests in one operation.
To use RequestContext with parameterized queries, use RequestParameterizedContext.
func (*Connection) RequestParameterized ¶
func (conn *Connection) RequestParameterized(sqlStatements []ParameterizedStatement) (results []RequestResult, err error)
RequestParameterized returns an error if one is encountered during its operation. If it's something like a call to the rqlite API, then it'll return that error. If one statement out of several has an error, you can look at the individual statement's Err for more info.
RequestParameterized uses context.Background() internally; to specify the context, use RequestParameterizedContext.
func (*Connection) RequestParameterizedContext ¶
func (conn *Connection) RequestParameterizedContext(ctx context.Context, sqlStatements []ParameterizedStatement) (results []RequestResult, err error)
RequestParameterizedContext returns an error if one is encountered during its operation. If it's something like a call to the rqlite API, then it'll return that error. If one statement out of several has an error, you can look at the individual statement's Err for more info.
func (*Connection) SetConsistencyLevel ¶
func (conn *Connection) SetConsistencyLevel(levelDesired consistencyLevel) error
func (*Connection) SetExecutionWithTransaction ¶
func (conn *Connection) SetExecutionWithTransaction(state bool) error
func (*Connection) Write ¶
func (conn *Connection) Write(sqlStatements []string) (results []WriteResult, err error)
Write is used to perform DDL/DML in the database synchronously without parameters.
Write uses context.Background() internally; to specify the context, use WriteContext. To use Write with parameterized queries, use WriteParameterized.
func (*Connection) WriteContext ¶
func (conn *Connection) WriteContext(ctx context.Context, sqlStatements []string) (results []WriteResult, err error)
WriteContext is used to perform DDL/DML in the database synchronously without parameters.
To use WriteContext with parameterized queries, use WriteParameterizedContext.
func (*Connection) WriteOne ¶
func (conn *Connection) WriteOne(sqlStatement string) (wr WriteResult, err error)
WriteOne wraps Write() into a single-statement method.
WriteOne uses context.Background() internally; to specify the context, use WriteOneContext.
func (*Connection) WriteOneContext ¶
func (conn *Connection) WriteOneContext(ctx context.Context, sqlStatement string) (wr WriteResult, err error)
WriteOneContext wraps WriteContext() into a single-statement
func (*Connection) WriteOneParameterized ¶
func (conn *Connection) WriteOneParameterized(statement ParameterizedStatement) (wr WriteResult, err error)
WriteOneParameterized wraps WriteParameterized() into a single-statement method.
WriteOneParameterized uses context.Background() internally; to specify the context, use WriteOneParameterizedContext.
func (*Connection) WriteOneParameterizedContext ¶
func (conn *Connection) WriteOneParameterizedContext(ctx context.Context, statement ParameterizedStatement) (wr WriteResult, err error)
WriteOneParameterizedContext wraps WriteParameterizedContext into a single-statement method.
func (*Connection) WriteParameterized ¶
func (conn *Connection) WriteParameterized(sqlStatements []ParameterizedStatement) (results []WriteResult, err error)
WriteParameterized is used to perform DDL/DML in the database synchronously.
WriteParameterized takes an array of SQL statements, and returns an equal-sized array of WriteResults, each corresponding to the SQL statement that produced it.
All statements are executed as a single transaction.
WriteParameterized returns an error if one is encountered during its operation. If it's something like a call to the rqlite API, then it'll return that error. If one statement out of several has an error, you can look at the individual statement's Err for more info.
WriteParameterized uses context.Background() internally; to specify the context, use WriteParameterizedContext.
func (*Connection) WriteParameterizedContext ¶
func (conn *Connection) WriteParameterizedContext(ctx context.Context, sqlStatements []ParameterizedStatement) (results []WriteResult, err error)
WriteParameterizedContext is used to perform DDL/DML in the database synchronously.
WriteParameterizedContext takes an array of SQL statements, and returns an equal-sized array of WriteResults, each corresponding to the SQL statement that produced it.
All statements are executed as a single transaction.
WriteParameterizedContext returns an error if one is encountered during its operation. If it's something like a call to the rqlite API, then it'll return that error. If one statement out of several has an error, you can look at the individual statement's Err for more info.
type NullFloat64 ¶
NullFloat64 represents a float64 that may be null.
type NullString ¶
NullString represents a string that may be null.
type ParameterizedStatement ¶
type ParameterizedStatement struct { Query string Arguments []interface{} }
type QueryResult ¶
QueryResult holds the results of a call to Query(). You could think of it as a rowset.
So if you were to query:
SELECT id, name FROM some_table;
then a QueryResult would hold any errors from that query, a list of columns and types, and the actual row values.
Query() returns an array of QueryResult vars, while QueryOne() returns a single variable.
func (*QueryResult) Columns ¶
func (qr *QueryResult) Columns() []string
Columns returns a list of the column names for this QueryResult.
func (*QueryResult) Map ¶
func (qr *QueryResult) Map() (map[string]interface{}, error)
Map returns the current row (as advanced by Next()) as a map[string]interface{}.
The key is a string corresponding to a column name. The value is the corresponding column.
Note that only json values are supported, so you will need to type the interface{} accordingly.
func (*QueryResult) Next ¶
func (qr *QueryResult) Next() bool
Next positions the QueryResult result pointer so that Scan() or Map() is ready.
You should call Next() first, but gorqlite will fix it if you call Map() or Scan() before the initial Next().
A common idiom:
rows := conn.Write(something) for rows.Next() { // your Scan/Map and processing here. }
func (*QueryResult) NumRows ¶
func (qr *QueryResult) NumRows() int64
NumRows returns the number of rows returned by the query.
func (*QueryResult) RowNumber ¶
func (qr *QueryResult) RowNumber() int64
RowNumber returns the current row number as Next() iterates through the result's rows.
func (*QueryResult) Scan ¶
func (qr *QueryResult) Scan(dest ...interface{}) error
Scan takes a list of pointers and then updates them to reflect the current row's data.
Note that only the following data types are used, and they are a subset of the types JSON uses:
string, for JSON strings float64, for JSON numbers int64, as a convenient extension nil for JSON null
booleans, JSON arrays, and JSON objects are not supported, since sqlite does not support them.
func (*QueryResult) Slice ¶
func (qr *QueryResult) Slice() ([]interface{}, error)
Slice returns the current row (as advanced by Next()) as a []interface{}.
The slice is a shallow copy of the internal representation of the row data.
Note that only json values are supported, so you will need to type the interface{} accordingly.
func (*QueryResult) Types ¶
func (qr *QueryResult) Types() []string
Types returns an array of the column's types.
Note that sqlite will repeat the type you tell it, but in many cases, it's ignored. So you can initialize a column as CHAR(3) but it's really TEXT. See https://www.sqlite.org/datatype3.html
This info may additionally conflict with the reality that your data is being JSON encoded/decoded.
type RequestResult ¶
type RequestResult struct { Err error Query *QueryResult Write *WriteResult }
RequestResult holds the result of a single statement sent to Unified Endpoint.
If statement failed, Err contains the error, neither Query nor Write is set. If statement succeeded, either of Query or Write is set — depending on the type of the statement. Query.Err and Write.Err are never set.
type StatementErrors ¶
type StatementErrors []error
func (StatementErrors) As ¶
func (errs StatementErrors) As(target interface{}) bool
As returns true if the current error, or one of the statement errors can be assigned to the target error.
func (StatementErrors) Error ¶
func (errs StatementErrors) Error() string
Error returns a string representation of the statement errors.
func (StatementErrors) Is ¶
func (errs StatementErrors) Is(target error) bool
Is returns true if the current error, or one of the statement errors is equal to the target error.
func (StatementErrors) Unwrap ¶
func (errs StatementErrors) Unwrap() []error
Unwrap returns the slice of statement errors.
type WriteResult ¶
type WriteResult struct { Err error // don't trust the rest if this isn't nil Timing float64 RowsAffected int64 // affected by the change LastInsertID int64 // if relevant, otherwise zero value // contains filtered or unexported fields }
WriteResult holds the result of a single statement sent to Write().
Write() returns an array of WriteResult vars, while WriteOne() returns a single WriteResult.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package stdlib provides a compatability layer from gorqlite to database/sql.
|
Package stdlib provides a compatability layer from gorqlite to database/sql. |