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
- 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
queryID := 1
queries, err := redashClient.Queries.Get(1)
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)
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?
- Easy to use Go client that covers some parts of the API.
- Swagger definition of the Redash API.
- Documentation and examples.
- Earthly-based build pipeline (lint and test).
- Many linters with golangci-lint and good test coverage.
Which parts of the API are covered?
- Data Sources
- Queries
- Visualizations
- 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.
