athenadriver

Athena supports joining tables across different databases/schemas within the same account using standard SQL syntax. You can reference tables using the database.table notation.

Example Join:

SELECT a.column_name, b.column_name 
FROM database_one.table_a a 
LEFT JOIN database_two.table_b b ON a.id = b.id;

-- Join tables from different databases
SELECT a.elb_name, a.url 
FROM default.elb_logs_new2 a 
LEFT JOIN sampledb.elb_logs_new1 b ON a.request_timestamp = b.request_timestamp;

Because athenadriver follows the Go database/sql design for streaming large datasets, you cannot perform random access on rows.

• To get the total row count: You must iterate through all rows using rows.Next() and maintain a manual counter.
• Random Access: There is no way to randomly access a row via the driver; you must traverse the result set sequentially.

Direct cross-account joins (e.g., account_1.db.table) are not supported because SQL cannot differentiate between tables with the same name in different accounts.

Recommended Workaround: Create a metadata copy (database or table) in the local account that points to the S3 data in the remote account. If the S3 bucket owner is different from the account owner, you must configure Cross-account Access permissions.

Reconnection

athenadriver supports database reconnection. Because it implements the standard Go database/sql interface, the internal connection pool handles reconnection and retry logic automatically.

Batching

athenadriver does not support batched queries. It is a standard sql.driver implementation. To perform bulk inserts, you should use db.Exec with a single INSERT statement containing multiple VALUES clauses instead of multiple individual INSERT calls.

Athena does not support row-level DELETE or UPDATE operations at the engine level.

• To remove data: You must use DROP for tables or views, or manage the underlying S3 data directly.
• To modify structure: You can use ALTER for tables and databases.

You can specify an Athena workgroup and attach resource/cost tags to your queries. By default, if the specified workgroup does not exist, athenadriver will attempt to create it programmatically. To prevent this behavior and ensure the query fails if the workgroup is missing, use Config.SetWGRemoteCreationAllowed(false).

Use drv.NewWGTags() to create a tag set and drv.NewWG(workgroupName, nil, wgTags) to create the workgroup object.

wgTags := drv.NewWGTags()
wgTags.AddTag("Uber User", "henry.wu")
// Specify that workgroup `henry_wu` is used
wg := drv.NewWG("henry_wu", nil, wgTags)
conf.SetWorkGroup(wg)

// Disable automatic creation of the workgroup if it doesn't exist
conf.SetWGRemoteCreationAllowed(false)

To determine how many rows were affected by a query (such as CTAS, CVAS, or INSERT INTO), you have two primary methods:

1. Recommended: Use DB.Exec().
2. Alternative: Use DB.Query(). The returned ResultSet contains an UpdateCount member variable. For CTAS, CVAS, and INSERT INTO statements, the result will be a single row and single column where the column name is rows and the value is an int representing the UpdateCount.

// Using QueryRow or QueryRowContext is suggested for single-row results
// to retrieve the UpdateCount from a CTAS/INSERT INTO query.
count, err := DB.QueryRowContext(ctx, "INSERT INTO ...").Scan(&rowsAffected)

The driver supports three primary ways to handle AWS authentication:

1. AWS CLI Config: Set the environment variable AWS_SDK_LOAD_CONFIG=1. The driver will then prioritize credentials from ~/.aws/credentials and region from ~/.aws/config. You must still provide a valid OutputBucket in the athenadriver.Config.
2. Explicit Driver Config: When AWS_SDK_LOAD_CONFIG is NOT set, pass valid accessID, secretAccessKey, region, and outputBucket directly into drv.NewDefaultConfig().
3. AWS SDK Default Resolution: If AWS_SDK_LOAD_CONFIG is NOT set and credentials are omitted from the config, the driver falls back to the standard AWS SDK default credential provider chain. You must still explicitly define Region and OutputBucket using conf.SetRegion() and conf.SetOutputBucket().

To use athenadriver, import the package and use the standard Go database/sql interface. You must first create a configuration using NewDefaultConfig specifying the S3 output bucket, AWS region, and credentials, then open a connection using sql.Open with drv.DriverName and the stringified configuration.

package main

import (
	"database/sql"
	drv "github.com/uber/athenadriver/go"
)

func main() {
	// Step 1. Set AWS Credential in Driver Config.
	conf, _ := drv.NewDefaultConfig("s3://myqueryresults/",
		"us-east-2", "DummyAccessID", "DummySecretAccessKey")
	// Step 2. Open Connection.
	db, _ := sql.Open(drv.DriverName, conf.Stringify())
	// Step 3. Query and print results
	var url string
	_ = db.QueryRow("SELECT url from sampledb.elb_logs limit 1").Scan(&url)
	println(url)
}