rdsql

README

rdsql

A SQL client for AWS Aurora serverless using rds-data API

Package usage:

import "github.com/raff/rdsql"

awscfg := rdsql.GetAWSConfig(profile, debug)
client := rdsql.ClientWithOptions(awscfg, resourceArn, secretArn, dbName)

ch := make(chan os.Signal, 1)

tid, err := client.BeginTransaction(ch)

params := map[string]interface{} {
    "p1": "value1",
    "p2", 42,
}

res, dberr = client.ExecuteStatement("SELECT * FROM table WHERE col1 = :p1 AND col2 < :p2", params, tid, ch)

//
// you can also use:
//   client.EndTransaction(tid, dberr == nil, ch)
//

if dberr != nil {
    client.RollbackTransaction(tid, ch)
} else {
    client.CommitTransaction(tid, ch)
}

Command usage:

rdsql [options] [sql statement]
  -continue
        continue after timeout (for DDL statements) (default true)
  -csv
        print output as csv
  -database string
        database
  -debug
        enable debugging
  -elapsed
        print elapsed time
  -params string
        query parameters (comma separated list of name=value pair)
  -profile string
        AWS profile
  -resource string
        resource ARN
  -secret string
        resource secret
  -timeout duration
        request timeout (default 2m0s)
  -transaction
        wrap full session in a remote transaction
  -verbose
        log statements before execution

Environment variables:

RDS_RESOURCE (database cluster resource ARN, same as -resource)
RDS_SECRET (database resource secret ARN, same as -secret)
RDS_PROFILE (AWS account profile, same as -profile)

Documentation

Overview

Package rdsql implements some methods to access an RDS Aurora Servless DB cluster via RDS DataService

See https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html

Index

• Variables
• func ContextWithSignal(timeout time.Duration, terminate chan os.Signal) (ctx context.Context, cancel context.CancelFunc)
• func GetAWSConfig(profile string, debug bool) aws.Config
• func SQLReader(db *Client, query string) chan string
• func SQLReaderLoop(db *Client, query, first string) chan string
• func StringOrNil(s string) *string
• type Client
  • func ClientWithOptions(config aws.Config, res, secret, db string) *Client
  • func ClientWithURI(uri string, debug bool) *Client
  • func (c *Client) BeginTransaction(terminate chan os.Signal) (string, error)
  • func (c *Client) CommitTransaction(tid string, terminate chan os.Signal) (string, error)
  • func (c *Client) CommitTransactionContext(ctx context.Context, tid string) (string, error)
  • func (c *Client) EndTransaction(tid string, commit bool, terminate chan os.Signal) (string, error)
  • func (c *Client) EndTransactionContext(ctx context.Context, tid string, commit bool) (string, error)
  • func (c *Client) ExecuteStatement(stmt string, params []Parameter, transactionId string, ...) (Results, error)
  • func (c *Client) ExecuteStatementContext(ctx context.Context, stmt string, params []Parameter, transactionId string) (Results, error)
  • func (c *Client) Ping(terminate chan os.Signal) (err error)
  • func (c *Client) PingContext(ctx context.Context) (err error)
  • func (c *Client) RollbackTransaction(tid string, terminate chan os.Signal) (string, error)
  • func (c *Client) RollbackTransactionContext(ctx context.Context, tid string) (string, error)
• type ColumnMetadata
• type Field
• type FieldMemberBooleanValue
• type FieldMemberIsNull
• type FieldMemberLongValue
• type FieldMemberStringValue
• type Parameter
  • func ParamMap(params map[string]interface{}) []Parameter
• type Results

Variables

var PingRetries = 5

var PingRetryPrefix = "PING RETRY"

var QueryRetries = 5

var SQLReaderBuffer = 10

var Verbose = true

Functions

func ContextWithSignal

func ContextWithSignal(timeout time.Duration, terminate chan os.Signal) (ctx context.Context, cancel context.CancelFunc)

func GetAWSConfig

func GetAWSConfig(profile string, debug bool) aws.Config

GetAWSConfig return an aws.Config profile

func SQLReader

func SQLReader(db *Client, query string) chan string

SQLReader returns a "list" of results from the specified queury

func SQLReaderLoop

func SQLReaderLoop(db *Client, query, first string) chan string

SQLReaderLoop returns a "list" of results from the specified queury. It will execute the query in a loop until there are no more results. It is possible to start a query from where the previous left off by adding a placeholder like {field} (i.e. select a,b,c from table where a > {a} limit 10). In this case {a} will be replaced with the last value of `a` from the previous call. Pass the appropriate value for `first` to initialize {field} (i.e. "" or 0)

func StringOrNil

func StringOrNil(s string) *string

StringOrNil return nil for an empty string or aws.String

Types

type Client

type Client struct {
	ResourceArn string
	SecretArn   string
	Database    string

	Timeout  time.Duration
	Continue bool // ContinueAfterTimeout
	// contains filtered or unexported fields
}

Client wraps *rdsdata.Client and client configuration (ResourceArn, SecretArn, etc...)

func ClientWithOptions

func ClientWithOptions(config aws.Config, res, secret, db string) *Client

ClientWithOptions creates an instance of Client given a list of options

func ClientWithURI

func ClientWithURI(uri string, debug bool) *Client

ClientWithURI creates an instance of Client given an rdsql URI

Format: rdsql:{profile};{resource};{secret};{database}

func (*Client) BeginTransaction

func (c *Client) BeginTransaction(terminate chan os.Signal) (string, error)

BeginTransaction executes rdsdata BeginTransaction

func (*Client) CommitTransaction

func (c *Client) CommitTransaction(tid string, terminate chan os.Signal) (string, error)

CommitTransaction executes rdsdata CommitTransaction

func (*Client) CommitTransactionContext

func (c *Client) CommitTransactionContext(ctx context.Context, tid string) (string, error)

CommitTransaction executes rdsdata CommitTransaction

func (*Client) EndTransaction

func (c *Client) EndTransaction(tid string, commit bool, terminate chan os.Signal) (string, error)

EndTransaction executes either a commit or a rollback request

func (*Client) EndTransactionContext

func (c *Client) EndTransactionContext(ctx context.Context, tid string, commit bool) (string, error)

EndTransaction executes either a commit or a rollback request

func (*Client) ExecuteStatement

func (c *Client) ExecuteStatement(stmt string, params []Parameter, transactionId string, terminate chan os.Signal) (Results, error)

ExecuteStatement executes a SQL statement and return Results

parameters could be passed as :par1, :par2... in the SQL statement with associated parameter mapping in the request

func (*Client) ExecuteStatementContext

func (c *Client) ExecuteStatementContext(ctx context.Context, stmt string, params []Parameter, transactionId string) (Results, error)

func (*Client) Ping

func (c *Client) Ping(terminate chan os.Signal) (err error)

Ping verifies the connection to the database is still alive.

func (*Client) PingContext

func (c *Client) PingContext(ctx context.Context) (err error)

func (*Client) RollbackTransaction

func (c *Client) RollbackTransaction(tid string, terminate chan os.Signal) (string, error)

RollbackTransaction executes rdsdata RollbackTransaction

func (*Client) RollbackTransactionContext

func (c *Client) RollbackTransactionContext(ctx context.Context, tid string) (string, error)

RollbackTransactionContext executes rdsdata RollbackTransaction

type ColumnMetadata

type ColumnMetadata = types.ColumnMetadata

ColumnMetadata is an alias for rdsdata types.ColumnMetadata

type Field

type Field = types.Field

Field is an alias for rdsdata types.Field

type FieldMemberBooleanValue

type FieldMemberBooleanValue = types.FieldMemberBooleanValue

type FieldMemberIsNull

type FieldMemberIsNull = types.FieldMemberIsNull

type FieldMemberLongValue

type FieldMemberLongValue = types.FieldMemberLongValue

type FieldMemberStringValue

type FieldMemberStringValue = types.FieldMemberStringValue

type Parameter

type Parameter = types.SqlParameter

Parameter is an alias for types.SqlParameter

func ParamMap

func ParamMap(params map[string]interface{}) []Parameter

type Results

type Results = *rdsdata.ExecuteStatementOutput

Results is an alias for *rdsdata.ExecuteStatementOutput