gorqlite – github.com/rqlite/gorqlite Index | Files | Directories

package gorqlite

import "github.com/rqlite/gorqlite"

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 

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
	// ConsitencyLevelLinearizable provides a linearizable consistency and
	// guarantees that read result will reflect all previous writes.
	ConsistencyLevelLinearizable
	// ConsistencyLevelStrong provides a strong consistency and guarantees
	// that the read result will reflect all previous writes and that all
	// previously commmitted writes in the Raft log have been applied..
	ConsistencyLevelStrong
)

Variables 

var DefaultHTTPClient = &http.Client{
	Timeout: defaultTimeout * time.Second,
}
var (
	// ErrClosed indicates that client connection was closed
	ErrClosed = errors.New("gorqlite: connection is closed")
)

Functions

func ParseConsistencyLevel 

func ParseConsistencyLevel(s string) (consistencyLevel, error)

ParseConsistencyLevel parses a string into a consistencyLevel.

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.

func TraceOn 

func TraceOn(w io.Writer)

TraceOn turns on tracing output to the io.Writer of your choice.

Trace output is very detailed and verbose, as you might expect.

Normally, you should run with tracing off, as it makes absolutely no concession to performance and is intended for debugging/dev use.

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, using the default HTTP client.

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 OpenWithClient 

func OpenWithClient(connURL string, client *http.Client) (*Connection, error)

OpenWithClient creates and returns a "connection" to rqlite, and uses the given HTTP client for all connections to rqlite. This allows clients to have complete conntrol over the HTTP communications between this client and the rqlite system.

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 NullBool 

type NullBool struct {
	Bool  bool
	Valid bool // Valid is true if Bool is not NULL
}

NullBool represents a bool that may be null.

type NullFloat64 

type NullFloat64 struct {
	Float64 float64
	Valid   bool // Valid is true if Float64 is not NULL
}

NullFloat64 represents a float64 that may be null.

type NullInt16 

type NullInt16 struct {
	Int16 int16
	Valid bool // Valid is true if Int16 is not NULL
}

NullInt16 represents an int16 that may be null.

type NullInt32 

type NullInt32 struct {
	Int32 int32
	Valid bool // Valid is true if Int32 is not NULL
}

NullInt32 represents an int32 that may be null.

type NullInt64 

type NullInt64 struct {
	Int64 int64
	Valid bool // Valid is true if Int64 is not NULL
}

NullInt64 represents an int64 that may be null.

type NullString 

type NullString struct {
	String string
	Valid  bool // Valid is true if String is not NULL
}

NullString represents a string that may be null.

type NullTime 

type NullTime struct {
	Time  time.Time
	Valid bool // Valid is true if Time is not NULL
}

NullTime represents a time.Time that may be null.

type ParameterizedStatement 

type ParameterizedStatement struct {
	Query     string
	Arguments []interface{}
}

type QueryResult 

type QueryResult struct {
	Err error

	Timing float64
	// contains filtered or unexported fields
}

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

api.go cluster.go conn.go consistency.go error.go gorqlite.go query.go request.go write.go

Directories

PathSynopsis
integration
stdlibPackage stdlib provides a compatability layer from gorqlite to database/sql.
Version
v0.0.0-20250128004930-114c7828b55a (latest)
Published
Jan 28, 2025
Platform
js/wasm
Imports
12 packages
Last checked
now –

Tools for package owners.