Redash Go SDK

An SDK for the programmatic management of Redash. The main component of the SDK is a client, which is a go wrapper of Redash's REST API.

• Redash Go SDK
  • Usage
    • Installation
    • Client Initialization
      • How to find your API key
      • How to initialize the client
    • Queries
      • List Queries
      • Get Query
      • Add Query
      • Archive Query
      • Regenerate Query API token
    • DataSources
      • List DataSource
      • Get DataSource
      • Add DataSource
      • Delete DataSource
    • Visualizations
      • Get a Visualization's URL
      • Add Visualization
      • Delete Visualization
    • Users
      • Get User
    • Supported versions
  • What's included?
    • Which parts of the API are covered?
  • Development
    • Generating code
    • Generating Tests
      • Generating Test Templates
      • Generating mocks
    • View documentation
    • Linting
    • Testing
  • Why

Usage

Installation

• TODO add go get instructions

Client Initialization

To initialize the client, you need to know your API key and your Redash address. The Redash address is your server address without protocol and trailing slash /. For example, if your server is on https://localhost:5000/ then you need localhost:5000 as your host.

How to find your API key

After logging in to your Redash instance, go to the profile page:

And then, you can copy your API key in the "Account" tab:

Based on this documentation page.

How to initialize the client

import (
    "fmt"

    redashclient "github.com/recolabs/redash-go-sdk"
    "github.com/recolabs/redash-go-sdk/gen/client"
)

func main() {
    redashClient := redashclient.NewClient(
        "{{.API_KEY}}",
        &client.TransportConfig{
            Host: "{{.HOST_ADDRESS}}",
        })

    // This part is just an example, not required.
    err := redashClient.Administration.Ping()
    if err == nil {
        fmt.Println("Client successfully initialized! Happy Redash-ing.")
    }
}

Queries

List Queries

queries, err := redashClient.Queries.List()

Get Query

queryID := 1
queries, err := redashClient.Queries.Get(1)

Add Query

queryStr := "SELECT * FROM postgres.public.table"
queryName := "swagger query"
queryOptions = `{
        "parameters": []
}`
query, err := queries.NewQuery(queryName, queryOptions, queryStr, 1)
if err != nil {
    fmt.Printf("%v\n", err)
}
responseQuery, err := redashClient.Queries.Add(query)

Archive Query

queryID := 1
err := redashClient.Queries.Archive(1)

Regenerate Query API token

queryID := 1
err := redashClient.Queries.RegenerateQueryAPIKey(1)

DataSources

List DataSource

dataSources, err := redashClient.DataSources.List()

Get DataSource

dsID := 1
queries, err := redashClient.DataSources.Get(dsID)

Add DataSource

import redashclient "github.com/recolabs/redash-go-sdk/datasources"

...

dataSourceType := "pg"
dataSourceName := "test"
postgresqlOptions := `{
    "dbname": "aa",
        "host": "1.1.1.1",
        "port": 5432
}`

ds, err := datasources.NewDataSource(dataSourceType,dataSourceName, postgresqlOptions)
if err != nil {
fmt.Printf("%v\n", err)
}
responseQuery, err := redashClient.Queries.Add(ds)

Delete DataSource

queryID := 1
err := redashClient.DataSources.Delete(queryID)

Update DataSource

import redashclient "github.com/recolabs/redash-go-sdk/datasources"

...

dataSourceType := "pg"
dataSourceName := "test"
postgresqlOptions := `{
    "dbname": "aa",
        "host": "1.1.1.1",
        "port": 5432
}`

ds, err := datasources.NewDataSource(dataSourceType,dataSourceName, postgresqlOptions)
if err != nil {
fmt.Printf("%v\n", err)
}
ds.ID = 1
responseQuery, err := redashClient.Queries.Update(ds)

Visualizations

Get a Visualization's URL

queryID := 1
visualizationID := 1
queryAPIKey := "{API_KEY}"
dataSources, err := redashClient.Visualizations.GetURL(visualizationID, queryID, queryAPIKey)

Add Visualization

import redashclient "github.com/recolabs/redash-go-sdk/visualizations"

...

visualizationType := "CHART"
visualizationName := "test chart"
visualizationOptions := "{}"
description := "test visualization"
queryID := 1

vis, err := visualizations.NewVisualization(visualizationType, visualizationName, visualizationOptions, queryID)
if err != nil {
fmt.Printf("%v\n", err)
}

responseQuery, err := redashClient.Visualizations.Add(vis)

Delete Visualization

queryID := 1
err := redashClient.Visualizations.Delete(queryID)

Users

Get User

userID := 1
dataSources, err := redashClient.Users.Get(userID)

Supported versions

The SDK has been tested against the following Redash versions:

• 10.1.0

What's included?

1. Easy to use Go client that covers some parts of the API.
2. Swagger definition of the Redash API.
3. Documentation and examples.
4. Earthly-based build pipeline (lint and test).
5. Many linters with golangci-lint and good test coverage.

Which parts of the API are covered?

1. Data Sources
2. Queries
3. Visualizations
4. Users

Note that some of these resources might only be partially covered.

Development

Generating code

Install go-swagger, if you have Homebrew or Linuxbrew run this:

brew tap go-swagger/go-swagger
brew install go-swagger

And then, to generate the client code from the swagger definition, run:

scripts/generate_client.sh

Generating Tests

Generating Test Templates

For each go file you'd like to generate tests for, run:

gotests -w -all file.go

For example:

gotests -w -all users/users.go

Generating mocks

The tests mock the swagger generated code (to avoid the need for a live Redash server for the tests). In order to generate the mocks, run

for dir in $(ls gen/client);do  mockery --dir="gen/client/$dir" --all --output=./mocks/"$dir" --outpkg="$dir"mock; done

View documentation

Install godoc.

go install -v golang.org/x/tools/cmd/godoc@latest

Then run the following if you're on Linux:

godoc -http=localhost:6060 &
xdg-open http://localhost:6060/pkg/github.com/recolabs/redash-go-sdk

MacOS:

godoc -http=localhost:6060 &
open http://localhost:6060/pkg/github.com/recolabs/redash-go-sdk

Linting

We use golangci-lint as our linter aggregator. Our linter configurations are stored in the .golangci.yml file. Run the linters using this command:

golangci-lint run

Testing

Simply run go test -v ./....

Why

We needed a way to programmatically control our self-hosted Redash instance from our backend services - we developed a custom dashboard screen in our product and Redash solved many issues for us, so we decided to use it as both the backend and the Data Analyst query development IDE.

Contributing

Read more about it here