Documentation
¶
Overview ¶
Package influxdb is a database/sql driver for InfluxDB 1, InfluxDB 2, and InfluxDB 3 and later (D78). It registers the one name "influxdb", and takes a DSN of the form influxdb://user:pass@host:port/database?key=value (D82).
db, err := sql.Open("influxdb", "influxdb://_admin:apiv3_token@localhost:8181/mydb")
The driver speaks two dialects. SQL, the dialect "influxdb", goes to /api/v3/query_sql, which only InfluxDB 3 and later have. InfluxQL, the dialect "influxql", goes to /query on every release. The key sqlmode says which one a connection speaks, as sslmode does for PostgreSQL, and its default, prefer, asks the server for its release (D78). Dialect and Version tell a caller what a connection speaks and what it talks to.
The server binds each argument, except in INSERT, which the driver binds (D85): sql.Named("k", v) fills $k, and a positional argument n fills $n, such as $1, in both dialects (D111). SQL reads its columns and their types from DESCRIBE (D80). InfluxQL gives each series of a statement a result set of its own. Its first columns are measurement, which holds the name of the series, and its tags (D81, D83 and D96). InfluxDB has no transactions. docs/INFLUXDB.md holds what the driver knows about the server.
Index ¶
Constants ¶
const ( // AuthBasic sends the user and the password with basic authentication. // It is the default, and every release takes a token as the password. AuthBasic = dbimp.AuthBasic // AuthBearer sends the password as a token, and no user: Bearer on // InfluxDB 1, which takes it as a JWT, and on InfluxDB 3, and Token on // InfluxDB 2, which refuses Bearer (measured). AuthBearer = dbimp.AuthBearer )
The values of the key auth, which say how the driver sends the password (D94 and D110).
const ( // SQLModeDisable speaks InfluxQL, and sends no request to learn the // release. SQLModeDisable = "disable" // SQLModeAllow speaks SQL, and sends no request to learn the release. SQLModeAllow = "allow" // SQLModePrefer learns the release from GET /ping, and speaks SQL to // InfluxDB 3 and later and InfluxQL to InfluxDB 1 and 2. It is the // default. SQLModePrefer = "prefer" // SQLModeRequire learns the release from GET /ping, and speaks SQL. The // connection fails on InfluxDB 1 and 2. SQLModeRequire = "require" )
The values of the key sqlmode, which say which dialect a connection speaks (D78).
const ( // DescribeAlways sends DESCRIBE before each statement, and reads the // columns and their types from it. It is the default. DescribeAlways = "always" // DescribeDisable reads the columns from the keys of the first row, and // learns no types. DescribeDisable = "disable" )
The values of the key describe, which say where SQL reads its columns (D80).
const ( // ChunkedPrefer asks InfluxDB 1 for chunks, and InfluxDB 2 and 3 for one // document. It is the default. ChunkedPrefer = "prefer" // ChunkedDisable asks every release for one document. ChunkedDisable = "disable" )
The values of the key chunked, which say whether InfluxQL asks for its answer in chunks (D83).
const ( // SQL is the dialect of SQL on InfluxDB 3 and later. Its name is the name // of the driver, as dburl D29 names it. SQL = "influxdb" // InfluxQL is the dialect of InfluxQL, on every release. InfluxQL = "influxql" )
The dialects of a connection (D78).
const Name = "influxdb"
Name is the name that the driver registers with database/sql, and the scheme of its DSN.
Variables ¶
This section is empty.
Functions ¶
func Dialect ¶
Dialect returns the dialect that a connection speaks: SQL or InfluxQL (D78). A caller calls it inside sql.Conn.Raw, as for Version.
func Version ¶
Version returns the release of the server of a connection, from the header X-Influxdb-Version of GET /ping, such as 1.13.1, 2.9.1 or 3.11.5 (D78). It removes the "v" that InfluxDB 2 writes before the number. A caller calls it inside sql.Conn.Raw, with the connection of the driver:
err = conn.Raw(func(dc any) error {
v, err = influxdb.Version(ctx, dc)
return err
})
Types ¶
type Config ¶
type Config struct {
// Host is the host of the server.
Host string
// Port is the port of the server: 8086 for Version 1 or 2, and 8181
// otherwise, by default.
Port int
// TLS is true to speak HTTPS.
TLS bool
// User and Password are the credentials, sent on every request as Auth
// says. A token is the password. With neither, the driver sends no
// credentials, for a server that runs with authentication off.
User string
Password string
// Auth is AuthBasic or AuthBearer (D94 and D110).
Auth string
// Database is the database, which the driver sends as db. It is empty
// for a DSN with no path, and then a statement names its database.
Database string
// RetentionPolicy is the retention policy that InfluxQL reads, sent as
// rp, or empty.
RetentionPolicy string
// SQLMode is SQLModeDisable, SQLModeAllow, SQLModePrefer or
// SQLModeRequire (D78).
SQLMode string
// Version is the major release, 1, 2 or 3, that the driver talks to when
// SQLMode is SQLModeDisable or SQLModeAllow (D78). It also chooses the
// default port, under every SQLMode (D82).
Version int
// Describe is DescribeAlways or DescribeDisable (D80).
Describe string
// Chunked is ChunkedPrefer or ChunkedDisable (D83).
Chunked 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.
func (*Connector) Close ¶
Close closes the idle connections of the transport. database/sql calls it when the database closes.
type Driver ¶
type Driver struct{}
Driver is the database/sql driver for InfluxDB.
type Error ¶
type Error struct {
// HTTPStatus is the status code of the response.
HTTPStatus int
// Statement is the statement_id of the InfluxQL statement that failed.
// It is -1 for an error of the whole request.
Statement int
// Message is the message of the server.
Message string
// contains filtered or unexported fields
}
Error is an error that InfluxDB reported. It is the answer to a request whose status is not 2xx, the error of one InfluxQL statement or of the whole InfluxQL answer with HTTP 200, or an answer with HTTP 200 that is not JSON (measured).
func (*Error) Is ¶ added in v0.18.0
Is reports whether err matches target. It matches dbimp.ErrAuthentication for HTTP 401, which every release sends for a wrong password or token (recorded: "a wrong password"). HTTP 403 and a statement that failed with HTTP 200, such as `insufficient permissions` on InfluxDB 2, are a missing permission and do not match (D197).
type Option ¶ added in v0.6.0
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. InfluxDB has no transactions (D20), so no option applies to BeginTx.
func WithChunked ¶ added in v0.6.0
WithChunked sets whether InfluxQL asks for its answer in chunks, ChunkedPrefer or ChunkedDisable, as the key chunked of the DSN does (D83).
func WithDatabase ¶ added in v0.6.0
WithDatabase sets the database of the statement, sent as db, as the path of the DSN does. An INSERT with INTO writes to the database of INTO.
func WithDescribe ¶ added in v0.6.0
WithDescribe sets where SQL reads its columns, DescribeAlways or DescribeDisable, as the key describe of the DSN does (D80).
func WithParameter ¶ added in v0.6.0
WithParameter sets any key of the body of the request by its name, such as "epoch" for InfluxQL. For SQL, the value is encoded with json/v2. For InfluxQL, whose body is a form, a string is the value as it is, and any other value is its JSON text. A key named here replaces one that the driver sets itself, as in Couchbase. An INSERT sends no body of keys, so it ignores WithParameter.
func WithReadonly ¶ added in v0.6.0
WithReadonly would make the server refuse a write. GET /query runs a write on InfluxDB 1 with only a warning (measured by hand on 1.13.1), and no release has another read-only mode. So a statement with it fails with dbimp.ErrNotSupported (D109).
func WithRetentionPolicy ¶ added in v0.6.0
WithRetentionPolicy sets the retention policy of the statement, sent as rp, as the key rp of the DSN does.
func WithTimeout ¶ added in v0.6.0
WithTimeout would set the time that the server gives the statement. No release has a timeout for one request: InfluxDB 1 and 2 have one for the whole server, and the manual of InfluxDB 3 names none. So a statement with it fails with dbimp.ErrNotSupported (D109).
Source Files