awql

Awql Database Driver

AWQL driver for Go's sql package.

Installation

Simple install the package to your $GOPATH with the go tool:

~ $ go get -u github.com/rvflash/awql-driver

Usage

AWQL Driver is an implementation of Go's database/sql/driver interface. You only need to import the driver and can use the full database/sql API then.

Use awql as driverName and a valid DSN as dataSourceName:

import "database/sql"
import _ "github.com/rvflash/awql-driver"

db, err := sql.Open("awql", "AdwordsID:APIVersion|DeveloperToken|AccessToken")

Data Source Name

The Data Source Name has two common formats, the optional parts are marked by squared brackets:

Minimal

AdwordsID|DeveloperToken[|AccessToken]

OAuth credentials

AdwordsID|DeveloperToken[|ClientID|ClientSecret|RefreshToken]

The first part with AdwordsID can contains Adwords API options. A DSN in its fullest form:

AdwordsID[:APIVersion:SupportsZeroImpressions:SkipColumnHeader:UseRawEnumValues]|DeveloperToken[|AccessToken][|ClientID|ClientSecret|RefreshToken]

Alternatively, NewDSN can be used to create a DSN string by filling a struct.

AdwordsID

The client customer ID is the account number of the AdWords client account you want to manage via the API, usually in the form 123-456-7890.

APIVersion

Type:           string
Valid Values:   <version>
Default:        v201809

Version of the Adwords API to use.

SupportsZeroImpressions

Type:           bool
Valid Values:   true, false
Default:        false

If true, report output will include rows where all specified metric fields are zero, provided the requested fields and predicates support zero impressions. If false, report output will not include such rows. Thus, even if this header is false and the Impressions of a row is zero, the row is still returned in case any of the specified metric fields have non-zero values.

SkipColumnHeader

Type:           bool
Valid Values:   true, false
Default:        false

If true, report output will not include a header row containing field names. If false or not specified, report output will include the field names.

UseRawEnumValues

Type:           bool
Valid Values:   true, false
Default:        false

Set to true if you want the returned format to be the actual enum value, for example, "IMAGE_AD" instead of "Image ad". Set to false or omit this header if you want the returned format to be the display value.

DeveloperToken

The developer token identifies your app to the AdWords API. Only approved tokens can connect to the API for production AdWords accounts; pending tokens can connect only to test accounts.

AccessToken

Use to grant connection to Google API

ClientID

Client identifier, used to connect to Adwords with OAuth2.

ClientSecret

Client secret, used to connect to Adwords with OAuth2.

RefreshToken

Because OAuth2 access expires after a limited time, an OAuth2 refresh token is used to automatically renew OAuth2 access.

Examples

Simple Awql query

// Ignores errors for the demo.
query := "SELECT ExternalCustomerId, AccountDescriptiveName FROM ACCOUNT_PERFORMANCE_REPORT"
db, _ := sql.Open("awql", "123-456-7890|dEve1op3er7okeN|ya29.Acc3ss-7ok3n")
stmt, _ := db.Query(query)
for stmt.Next() {
    var id int
    var name string
    stmt.Scan(&id, &name)
    fmt.Printf("%v: %v\n", id, name)
    // Output: 1234567890: Rv
}

Awql query row with arguments

// Ignores errors for the demo.
var name string
query := "SELECT CampaignName FROM CAMPAIGN_PERFORMANCE_REPORT Where CampaignId = ?"
row := db.QueryRow(query, 123456789)
row.Scan(&name)
fmt.Printf("%v\n", name)
// Output: Campaign #19

Advanced sample

// Instantiates a data source name.
dsn := awql.NewDsn("123-456-7890")
dsn.DeveloperToken = "dEve1op3er7okeN"
dsn.ClientID = "1234567890-Aw91.apps.googleusercontent.com"
dsn.ClientSecret = "C13nt5e0r3t"
dsn.RefreshToken = "1/n-R3fr35h70k3n"

// Ignores errors for the demo.
query := "SELECT ConversionTypeName, AllConversions, ConversionValue FROM CRITERIA_PERFORMANCE_REPORT DURING LAST_7_DAYS"
db, _ := sql.Open("awql", dsn.String())
stmt, _ := db.Query(query)
cols, _ := stmt.Columns()
fmt.Printf("%q\n", cols)
// Output: ["Conversion name" "All conv." "Total conv. value"]

// Copy references into the slice
size := len(cols)
vals := make([]string, size)
ints := make([]interface{}, size)
for i := range ints {
    ints[i] = &vals[i]
}
for stmt.Next() {
    stmt.Scan(ints...)
    fmt.Printf("%q\n", vals)
}
// Output:
// ["Transactions (Phone)" "6.0" "362.33"]
// ["Transactions (Web)" "1.0" "89.3"]