dyndb

README

Dynamodb SQL Driver

This library is compatible with Go 1.17+

Please refer to CHANGELOG.md if you encounter breaking changes.

Please refer to CHANGELOG.md if you encounter breaking changes.

• DSN
• Usage
• Benchmark
• Bugs
• License
• Credits and Acknowledgements

This library provides fast implementation of the DynamoDB as a database/sql driver. For most of the operation this driver uses PartiSQL with ability to define custom functions.

DSN Data Source Name

The Dynamodb driver accepts the following DSN

• 'dynamodb://aws|{dockerEndpoint}/{region}/[{options}]'

  Where queryString can optionally configure the following option:

  • key: access key id
  • secret: access key secret
  • credURL: (url encoded) local location or URL supported by Scy
  • credKey: optional (url encoded) Scy secret manager key or key location
  • credID: Scy resource secret ID
  • roleArn, session to use assumed role

Usage:

The following is a very simple example of query operation

package main

import (
  "context"
  "database/sql"
  "encoding/json"
  "fmt"
  "log"
  _ "github.com/viant/dyndb"
  "time"
)

type Publication struct {
  ISBN      string
  Name      string
  IsTravel  bool
  IsFinance bool
}

func main() {

  db, err := sql.Open("dynamodb", "dynamodb://localhost:8000/us-west-1?key=dummy&secret=dummy")
  if err != nil {
    log.Fatalln(err)
  }
  defer db.Close()
  SQL := `SELECT ISBN, Name,
		ARRAY_EXISTS(Categories, 'TRAVEL') AS IS_TRAVEL ,
		ARRAY_EXISTS(Categories, 'FINANCE') AS IS_FINANCE
	FROM Publication`

  ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
  defer cancel()
  stmt, err := db.PrepareContext(ctx, SQL)
  if err != nil {
    log.Fatalln(err)
  }
  rows, err := stmt.Query()
  if err != nil {
    log.Fatalln(err)
  }
  var records []*Publication
  for rows.Next() {
    record := &Publication{}
    err = rows.Scan(&record.ISBN, &record.Name, &record.IsFinance, &record.IsTravel)
    if err != nil {
      log.Fatalln(err)
    }
    records = append(records, record)
  }
  data, _ := json.Marshal(records)
  fmt.Printf("%s\n", data)

}

Benchmark

Benchmark runs times the following query:

• QueryAll: (fetches 1000 records)

   SELECT id, state,gender,year,name, number  FROM usa_names

BenchmarkDatabaseSQL_QueryAll
BenchmarkDatabaseSQL_QueryAll-16       	      80	  14983399 ns/op	 1080045 B/op	   18194 allocs/op
BenchmarkAwsSDK_QueryAll
BenchmarkAwsSDK_QueryAll-16            	      54	  19998584 ns/op	 3654102 B/op	   51359 allocs/op

• QuerySingle: (fetches 1 record)

   SELECT id, state,gender,year,name, number  FROM usa_names WHERE id = 1

  BenchmarkDatabaseSQL_QuerySingle
  BenchmarkDatabaseSQL_QuerySingle-16    	     726	   1651893 ns/op	   24465 B/op	     333 allocs/op
  BenchmarkAwsSDK_QuerySingle
  BenchmarkAwsSDK_QuerySingle-16         	     795	   1682389 ns/op	   29651 B/op	     374 allocs/op

In both case database/sql driver is faster and allocate way less memory than native AWS SDK client

Bugs

This package implement only basic SQL with limited functionality. It extends original PartiSQL with extra client side functionality. Contributors are welcome.

License

The source code is made available under the terms of the Apache License, Version 2, as stated in the file LICENSE.

Individual files may be made available under their own specific license, all compatible with Apache License, Version 2. Please see individual files for details.

Credits and Acknowledgements

Library Author:

Contributors:

Documentation

Index

• type Config
  • func ParseDSN(dsn string) (*Config, error)
• type Connection
  • func (c *Connection) Begin() (driver.Tx, error)
  • func (c *Connection) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error)
  • func (c *Connection) Close() error
  • func (c *Connection) IsValid() bool
  • func (e *Connection) Lookup(SQL string) *exec.Execution
  • func (c *Connection) Ping(ctx context.Context) error
  • func (c *Connection) Prepare(SQL string) (driver.Stmt, error)
  • func (c *Connection) PrepareContext(ctx context.Context, SQL string) (driver.Stmt, error)
  • func (e *Connection) Put(execution *exec.Execution)
  • func (c *Connection) ResetSession(ctx context.Context) error
• type Driver
  • func (d Driver) Open(dsn string) (driver.Conn, error)
• type Rows
  • func (r *Rows) Close() error
  • func (r *Rows) ColumnTypeDatabaseTypeName(index int) string
  • func (r *Rows) ColumnTypeNullable(index int) (nullable, ok bool)
  • func (r *Rows) ColumnTypeScanType(index int) reflect.Type
  • func (r *Rows) Columns() []string
  • func (r *Rows) Next(dest []driver.Value) error
• type Statement
  • func (s *Statement) CheckNamedValue(named *driver.NamedValue) error
  • func (s *Statement) Close() error
  • func (s *Statement) Exec(args []driver.Value) (driver.Result, error)
  • func (s *Statement) ExecContext(ctx context.Context, args []driver.NamedValue) (driver.Result, error)
  • func (s *Statement) NumInput() int
  • func (s *Statement) Query(args []driver.Value) (driver.Rows, error)
  • func (s *Statement) QueryContext(ctx context.Context, args []driver.NamedValue) (driver.Rows, error)

Examples

• Connection.PrepareContext

Types

type Config

type Config struct {
	url.Values
	CredURL string
	CredKey string
	CredID  string
	cred.Aws
	ExecMaxCache int
}

Config represent Connection config

func ParseDSN

func ParseDSN(dsn string) (*Config, error)

ParseDSN parses the DSN string to a Config

type Connection

type Connection struct {
	// contains filtered or unexported fields
}

Connection represent connection

func (*Connection) Begin

func (c *Connection) Begin() (driver.Tx, error)

Begin starts and returns a new transaction.

func (*Connection) BeginTx

func (c *Connection) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error)

BeginTx starts and returns a new transaction.

func (*Connection) Close

func (c *Connection) Close() error

Close closes Connection

func (*Connection) IsValid

func (c *Connection) IsValid() bool

IsValid check is Connection is valid

func (*Connection) Lookup

func (e *Connection) Lookup(SQL string) *exec.Execution

func (*Connection) Ping

func (c *Connection) Ping(ctx context.Context) error

Ping pings server

func (*Connection) Prepare

func (c *Connection) Prepare(SQL string) (driver.Stmt, error)

Prepare returns a prepared statement, bound to this Connection.

func (*Connection) PrepareContext

func (c *Connection) PrepareContext(ctx context.Context, SQL string) (driver.Stmt, error)

PrepareContext returns a prepared statement, bound to this Connection.

Example

type Publication struct {
	ISBN      string
	Name      string
	IsTravel  bool
	IsFinance bool
}
db, err := sql.Open("dynamodb", "dynamodb://localhost:8000/us-west-1?cred=aws-e2e")
if err != nil {
	log.Fatalln(err)
}
defer db.Close()
SQL := `SELECT ISBN, Name,
		ARRAY_EXISTS(Categories, 'TRAVEL') AS IS_TRAVEL ,
		ARRAY_EXISTS(Categories, 'FINANCE') AS IS_FINANCE
	FROM Publication`

ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
defer cancel()
stmt, err := db.PrepareContext(ctx, SQL)
if err != nil {
	log.Fatalln(err)
}
rows, err := stmt.Query()
if err != nil {
	log.Fatalln(err)
}
var records []*Publication
for rows.Next() {
	record := &Publication{}
	err = rows.Scan(&record.ISBN, &record.Name, &record.IsFinance, &record.IsTravel)
	if err != nil {
		log.Fatalln(err)
	}
	records = append(records, record)
}
data, _ := json.Marshal(records)
fmt.Printf("%s\n", data)

func (*Connection) Put

func (e *Connection) Put(execution *exec.Execution)

func (*Connection) ResetSession

func (c *Connection) ResetSession(ctx context.Context) error

ResetSession resets session

type Driver

type Driver struct{}

Driver is exported to make the driver directly accessible. In general the driver is used via the database/sql package.

func (Driver) Open

func (d Driver) Open(dsn string) (driver.Conn, error)

Open new Connection. See https://github.com/viant/dynamodb#dsn-data-source-name for how the DSN string is formatted

type Rows

type Rows struct {
	// contains filtered or unexported fields
}

Rows represents rows driver

func (*Rows) Close

func (r *Rows) Close() error

Close closes rows

func (*Rows) ColumnTypeDatabaseTypeName

func (r *Rows) ColumnTypeDatabaseTypeName(index int) string

ColumnTypeDatabaseTypeName returns column database type name

func (*Rows) ColumnTypeNullable

func (r *Rows) ColumnTypeNullable(index int) (nullable, ok bool)

ColumnTypeNullable returns if column is nullable

func (*Rows) ColumnTypeScanType

func (r *Rows) ColumnTypeScanType(index int) reflect.Type

ColumnTypeScanType returns column scan type

func (*Rows) Columns

func (r *Rows) Columns() []string

Columns returns query columns

func (*Rows) Next

func (r *Rows) Next(dest []driver.Value) error

Next moves to next row

type Statement

type Statement struct {
	// contains filtered or unexported fields
}

Statement abstraction implements database/sql driver.Statement interface

func (*Statement) CheckNamedValue

func (s *Statement) CheckNamedValue(named *driver.NamedValue) error

CheckNamedValue checks supported types (all for now)

func (*Statement) Close

func (s *Statement) Close() error

Close closes statement

func (*Statement) Exec

func (s *Statement) Exec(args []driver.Value) (driver.Result, error)

Exec executes statements

func (*Statement) ExecContext

func (s *Statement) ExecContext(ctx context.Context, args []driver.NamedValue) (driver.Result, error)

ExecContext executes statements

func (*Statement) NumInput

func (s *Statement) NumInput() int

NumInput returns numinput

func (*Statement) Query

func (s *Statement) Query(args []driver.Value) (driver.Rows, error)

Query runs query

func (*Statement) QueryContext

func (s *Statement) QueryContext(ctx context.Context, args []driver.NamedValue) (driver.Rows, error)

QueryContext runs query