Documentation
¶
Overview ¶
Package libsql is a database/sql driver for libSQL, the fork of SQLite by Turso, which its server sqld and Turso Cloud serve over the Hrana protocol on HTTP. It registers the one name "libsql", and takes a DSN of the form libsql://user:token@host:port?key=value (D148). dburl names turso as an alias.
db, err := sql.Open("libsql", "libsql://:token@mydb-myorg.turso.io")
TLS is on unless tls=false, and the token goes as Bearer (D148). A query reads its rows from /v3/cursor one token at a time, and Exec runs on /v3/pipeline (D149). A transaction lives on a stream of Hrana, which its baton holds across requests (D150). The server binds each argument as a typed value (D152). A value has the Go type of the affinity of its declared type, and a value of another storage class keeps its own Go type (D140 and D147). docs/LIBSQL.md holds what the driver knows about the server.
Index ¶
Constants ¶
const ( // AuthBearer sends the password as a Bearer token. It is the default. AuthBearer = dbimp.AuthBearer // AuthBasic sends the user and the password with basic authentication, // for sqld with SQLD_HTTP_AUTH. AuthBasic = dbimp.AuthBasic )
The values of the key auth, which say how the driver sends the password (D94 and D148).
const ( // CodeStreamExpired is the code of a stream that had no request for 10 // seconds. The server rolled back its transaction (measured). CodeStreamExpired = "STREAM_EXPIRED" )
The codes of Hrana that the driver reads (docs/LIBSQL.md, Errors).
const Name = "libsql"
Name is the name that the driver registers with database/sql, and the scheme of its DSN.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
// Host is the host of the server.
Host string
// Port is the port of the server, 443 by default with TLS.
Port int
// NoTLS is true to speak HTTP, which the key tls=false asks for. TLS is
// on by default (D148).
NoTLS bool
// User and Password are the credentials. The password is the token
// (D94).
User string
Password string
// Auth is AuthBearer or AuthBasic (D94).
Auth string
// Namespace is the namespace of each request, sent as x-namespace, or ""
// for the default one.
Namespace string
}
Config is the configuration of a connector, which the DSN holds. The caller owns it (D7).
type Connector ¶
type Connector struct {
// contains filtered or unexported fields
}
Connector opens connections to one server. It owns its transport, and every connection shares it. A caller can build one from a Config and open it with sql.OpenDB.
func NewConnector ¶
NewConnector returns a Connector for cfg. The connector keeps a copy of cfg, and fills each field that is zero with its default.
type Driver ¶
type Driver struct{}
Driver is the database/sql driver for libSQL.
type Error ¶
type Error struct {
// HTTPStatus is the status code of the response.
HTTPStatus int
// Code is the code of Hrana or of SQLite, or "" when the server sent
// none.
Code string
// Message is the message of the server.
Message string
// contains filtered or unexported fields
}
Error is an error that libSQL reported. An error of a statement arrives with HTTP 200, as a result of the type error with a message and a code, such as SQL_PARSE_ERROR or SQLITE_CONSTRAINT (measured). A request that the server refused arrives with another status: HTTP 400 for a fault of the protocol, as text, or for an expired stream, HTTP 401 for a token that is not valid, and HTTP 403 for a write with a token that can only read (measured).
type Option ¶
Option sets an option of one statement (D109). An option comes from the DSN, then from the context through WithOptions, then from an argument of the statement, and a later one wins.
func WithDatabase ¶
WithDatabase sets the namespace of the statement, as WithNamespace does. A namespace is the database of libSQL.
func WithNamespace ¶
WithNamespace sets the namespace of the statement, sent as x-namespace, as the key namespace of the DSN does (D148). A statement of a transaction runs in the namespace of the transaction.
func WithParameter ¶
WithParameter sets any key of the statement of Hrana by its name, such as "want_rows". The value is encoded with json/v2. A key named here replaces one that the driver sets itself, such as "sql" or "args".
func WithReadonly ¶
WithReadonly would make the server refuse a write. The server keeps no statement or transaction read-only: it took an INSERT inside BEGIN TRANSACTION READONLY (measured). So WithReadonly(true) fails with dbimp.ErrNotSupported. A token with the claim ro is read-only.
func WithTimeout ¶
WithTimeout ends the request of the statement after d. The server stops a statement when its client leaves (measured), and Hrana has no timeout of its own, so the end of the request stops the statement. Zero sets no timeout.
Source Files