Documentation
¶
Overview ¶
Package dynamodb is a database/sql driver for Amazon DynamoDB. It registers the one name "dynamodb", and takes a DSN of the form dynamodb://key:secret@host:port?region=us-east-1 (D169).
db, err := sql.Open("dynamodb", "dynamodb://key:secret@localhost:8000?region=us-east-1&tls=false")
A statement is PartiQL, which the driver sends with ExecuteStatement. The server binds each ? as a typed value, and the driver refuses a count of arguments that is not the count of the placeholders, because the server takes too many with no error. The driver follows NextToken to the end of a result, one page at a time, and reads each page one item at a time (D25 and D169). The columns of a result are the names that the statement gives, in its order. SELECT * gives one column, which holds each item as a map[string]any (D163). A missing attribute and NULL are one value, nil (D169). Each request is signed with AWS Signature Version 4, which the driver writes with the standard library.
DynamoDB has no transaction that database/sql can express, so BeginTx fails with dbimp.ErrNotSupported (D169). The driver sends no DDL. A table is made through the API of DynamoDB, which is no SQL. docs/DYNAMODB.md holds what the driver knows about the server.
Index ¶
Constants ¶
const Name = "dynamodb"
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 localhost or
// dynamodb.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. The DSN turns it on by default.
TLS bool
// Region is the region of AWS that each signature names, such as
// us-east-1. It has no default.
Region string
// User is the access key, and Password is the secret key, which the
// driver signs each request with (D94 and D169).
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
}
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 dynamodb://key:secret@host:port?region=us-east-1 (D27, D35 and D169). The keys are tls, which is true by default, region, which has no default and must be set, and token, the session token of temporary credentials, which is empty by default. A DSN with a path is refused, because DynamoDB has no database to choose, and so is every other key. The signature needs the access key and the secret key, so a DSN with no user or no password 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 DynamoDB.
type Error ¶
type Error struct {
// HTTPStatus is the status code of the response.
HTTPStatus int
// Type is the name of the type of the error, such as ValidationException,
// without its namespace. It is empty when the answer has none.
Type string
// Message is the text of the error, or the text of the answer when it
// has none.
Message string
// contains filtered or unexported fields
}
Error is an error that DynamoDB reported. An error answers HTTP 400 with a JSON object that names its type in __type and its text in Message, such as com.amazon.coral.validate#ValidationException for a syntax error and com.amazonaws.dynamodb.v20120810#ResourceNotFoundException for an unknown table (recorded). DynamoDB Local answers HTTP 500 and InternalFailure for a body that it cannot read. The driver sends no request again after an error, so HTTP 429 and HTTP 503 reach the caller (D8).
func (*Error) Is ¶ added in v0.18.0
Is reports whether target is dbimp.ErrAuthentication, which the error matches when the server refused the credential: the type UnrecognizedClientException or InvalidSignatureException, or HTTP 401 (D197). AccessDeniedException is a missing permission, and it does not match.
type Option ¶
Option sets an option of one statement (D109). An option comes from the context through WithOptions, and then from an argument of the statement, and a later one wins. The DSN holds no option, because its two keys are keys of the connection (D169).
func WithDatabase ¶
WithDatabase names the database of one statement. DynamoDB has no database to choose (D169), so a statement with it fails with dbimp.ErrNotSupported.
func WithParameter ¶
WithParameter sets any key of the body of ExecuteStatement by its name, such as "ConsistentRead", "Limit" or "ReturnConsumedCapacity". The value is encoded with json/v2. A key named here replaces one that the driver sets itself, such as "Statement" or "Parameters", as in Couchbase. The driver sends the keys again with each page of a result, so "Limit" limits each page, and not the result.
func WithReadonly ¶
WithReadonly asks that the statement write nothing. DynamoDB 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. DynamoDB has no such setting, because each request reads one page and ends fast (D169), so a positive value fails the statement with dbimp.ErrNotSupported. The context of the statement is the way to bound it. Zero asks for nothing.
type Set ¶
type Set []any
Set is a set of strings, of numbers or of binary values, which a caller sends as an argument. A []any is a list, and an argument cannot tell a list from a set by its Go type, so a set has a type of its own (D169). The type of the first element names the kind of the set: a string gives SS, a number gives NS, and a []byte gives BS. The values are the same as those of a list, and every element must have the kind of the first one. The server refuses an empty set, so the driver does too. A set that the driver reads is a []any, as the type table says.
Source Files