Documentation
¶
Overview ¶
Package athena is a database/sql driver for Amazon Athena, which runs SQL over its JSON API with HTTPS. It registers the one name "athena", and takes a DSN of the form athena://key:secret@athena.us-east-1.amazonaws.com/database?workgroup=name (D192).
db, err := sql.Open("athena", "athena://key:secret@athena.us-east-1.amazonaws.com/mydb?workgroup=main")
The region comes from the host of the DSN. The driver signs each request with AWS Signature Version 4, which it writes with the standard library, and it reads no credential from the environment or from a file (D7).
A statement is three or more calls. The driver sends StartQueryExecution, polls GetQueryExecution until the query ends, and reads the rows with GetQueryResults, one page at a time, each page one row at a time (D25 and D192). The server runs the whole query before the first row, so an error comes before any row. When the context ends while the query runs, the driver sends StopQueryExecution. The server binds each ? with ExecutionParameters, and the driver writes each argument as an SQL literal. Every value arrives as text, and the driver decodes it by the type of the column. The text of an ARRAY, a MAP and a ROW has no escape, so the driver returns it as a string.
Athena has no transaction, so BeginTx fails with dbimp.ErrNotSupported (D20). docs/ATHENA.md holds what the driver knows about the server.
Index ¶
Constants ¶
const ( // ErrCanceled is the error of a query that ended in the state CANCELLED. // It is returned also when the driver did not stop the query, because // someone else did, such as an administrator (D192 item 8). ErrCanceled dbimp.Error = "the query was canceled" // ErrNoCredentials is the error of a connector whose Config holds no // access key and no secret key, because the driver reads no credential // from the environment (D7 and D192). ErrNoCredentials dbimp.Error = "the configuration has no access key or secret key" )
The sentinel errors of the driver. Each one wraps into a failure with errors.Is (D6).
const Name = "athena"
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 endpoint, such as athena.us-east-1.amazonaws.com.
Host string
// Port is the port of the endpoint. Zero means the port of the scheme, 443
// for HTTPS and 80 for HTTP.
Port int
// TLS is true to speak HTTPS. ParseDSN sets it, and only a test of the
// driver has a reason to turn it off, because the DSN has no key for it.
TLS bool
// Region is the region of AWS that each signature names, such as
// us-east-1. ParseDSN reads it from the host.
Region string
// User is the access key, and Password is the secret key, which the driver
// signs each request with (D94 and D192). A Config with no User and no
// Password opens no connection, because the driver reads no credential from
// the environment (D7).
User string
Password string
// Token is the session token of temporary credentials. The driver sends it
// in the header X-Amz-Security-Token and signs that header. It is a secret,
// like Password (D94). It is empty for the credentials of a user.
Token string
// Database is the database of the Glue Data Catalog that a statement
// uses, which the path of the DSN names. It can be empty.
Database string
// WorkGroup is the workgroup that runs a statement. When it is empty, the
// request names none, and Athena uses the workgroup primary.
WorkGroup string
// Output is the S3 location of the results, such as s3://bucket/prefix/.
// A workgroup that enforces its own location ignores it (recorded).
Output string
// Catalog is the data catalog of a statement. When it is empty, the request
// names none, and Athena uses AwsDataCatalog.
Catalog string
}
Config is the configuration of a connector, which the DSN holds. The caller owns it (D7).
func ParseDSN ¶
ParseDSN parses a DSN of the form athena://key:secret@athena.us-east-1.amazonaws.com/database?workgroup=name (D27, D35 and D192). The host names the endpoint, and the region comes from it: the label after athena or athena-fips, so athena.us-east-1.amazonaws.com and vpce-1.athena.us-east-1.vpce.amazonaws.com are in us-east-1. The path is the database, with no further slash. The keys are workgroup, output, token and catalog, and each is empty by default. The access key and the secret key are the user and the password of the URL. They can be left out, and then the Config has none and the connector refuses to connect (D7). Any other key is refused.
type Connector ¶
type Connector struct {
// contains filtered or unexported fields
}
Connector opens connections to one endpoint. 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.
type Driver ¶
type Driver struct{}
Driver is the database/sql driver for Amazon Athena.
type Error ¶
type Error struct {
// HTTPStatus is the status code of the response, and zero for a query that
// ended in a state.
HTTPStatus int
// Type is the name of the type of the error, such as
// InvalidRequestException. It is empty for a query that ended in a state.
Type string
// Code is AthenaErrorCode, such as MALFORMED_QUERY, and empty when the
// answer has none.
Code string
// State is the state of a query that ended without rows, FAILED or
// CANCELLED, and empty for a request that the server refused.
State string
// ErrorType is the member ErrorType of AthenaError, such as 1301, and zero
// when the answer has none.
ErrorType int
// Category is the member ErrorCategory of AthenaError: 1 is a fault of the
// system, 2 a fault of the user, and 3 another one. It is zero when the
// answer has none.
Category int
// Message is the text of the error.
Message string
// QueryID is the id of the query, and empty for a request that the server
// refused before a query existed.
QueryID string
// contains filtered or unexported fields
}
Error is an error that Athena reported. It has two forms. A request that the server refuses answers HTTP 400 with a JSON object that names its type in __type, and its text in Message or message, and that holds AthenaErrorCode for an InvalidRequestException (recorded). A query that fails answers HTTP 200, and GetQueryExecution then has the state FAILED with the text in StateChangeReason and the code in AthenaError (recorded). A query that was canceled has the state CANCELLED and no AthenaError.
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 WithCatalog ¶
WithCatalog sets the data catalog of one statement, as the key catalog of the DSN does. It is Catalog of QueryExecutionContext.
func WithDatabase ¶
WithDatabase sets the database of the Glue Data Catalog for one statement, as the path of the DSN does. It is Database of QueryExecutionContext.
func WithOutput ¶
WithOutput sets the S3 location of the results of one statement, as the key output of the DSN does. A workgroup that enforces its own location ignores it (recorded: "another result configuration").
func WithParameter ¶
WithParameter sets any key of the body of StartQueryExecution by its name, such as "ResultReuseConfiguration". The value is encoded with json/v2. A key named here replaces one that the driver sets itself, such as "QueryString" or "ExecutionParameters", as in Couchbase.
func WithReadonly ¶
WithReadonly asks that the statement write nothing. Athena has no setting that makes it refuse a write for one request, so WithReadonly(true) fails the statement with dbimp.ErrNotSupported. A policy of IAM that allows reads only makes a read-only principal.
func WithTimeout ¶
WithTimeout sets the time that the server gives the statement. A request of Athena has no such setting, because only the workgroup sets the timeout of its queries, so a positive value fails the statement with dbimp.ErrNotSupported. The context of the statement is the way to bound it, and the driver stops the query when the context ends. Zero asks for nothing.
func WithWorkGroup ¶
WithWorkGroup sets the workgroup of one statement, as the key workgroup of the DSN does.
Source Files