Driver do Databricks SQL para Go

Artigo
11/14/2024

O Driver do Databricks SQL para Go é a biblioteca do Go que permite usar código Go para executar comandos SQL em recursos de computação do Azure Databricks. Este artigo complementa o LEIAME, a referência de API e os exemplos do Driver SQL do Databricks para Go.

Requisitos

Um computador de desenvolvimento executando o Go, versão 1.20 ou superior. Para imprimir a versão instalada do Go, execute o comando go version. Baixe e instale o Go.
Um cluster ou SQL warehouse existente.
Os valores de Nome do host do servidor, Porta e Caminho HTTP para o cluster ou o SQL warehouse existente.
- Obter esses valores para um cluster.
- Obter esses valores para um SQL warehouse.

Introdução ao Driver do Databricks SQL para Go

Em seu computador de desenvolvimento com o Go 1.20 ou superior já instalado e um projeto de código Go existente já criado, crie um arquivo go.mod para rastrear as dependências do seu código Go executando o comando go mod init, por exemplo:
```
go mod init sample
```
Crie uma dependência no pacote Driver do SQL do Databricks para Go executando o comando go mod edit -require, substituindo v1.5.2 pela versão mais recente do pacote Driver do SQL do Databricks para Go, conforme listado em Versões:
```
go mod edit -require github.com/databricks/databricks-sql-go@v1.5.2
```
Seu arquivo go.mod agora deve ser assim:
```
module sample

go 1.20

require github.com/databricks/databricks-sql-go v1.5.2
```

Em seu projeto, crie um arquivo de código Go que importe o Driver do SQL do Databricks para Go. O exemplo a seguir, em um arquivo nomeado main.go com o conteúdo a seguir, lista todos os clusters no seu espaço de trabalho do Azure Databricks:

package main

import (
  "database/sql"
  "os"
  _ "github.com/databricks/databricks-sql-go"
)

func main() {
  dsn := os.Getenv("DATABRICKS_DSN")

  if dsn == "" {
    panic("No connection string found. " +
     "Set the DATABRICKS_DSN environment variable, and try again.")
  }

  db, err := sql.Open("databricks", dsn)
  if err != nil {
    panic(err)
  }
  defer db.Close()

  if err := db.Ping(); err != nil {
    panic(err)
  }
}

Adicione as dependências de módulo ausentes executando o comando go mod tidy:
```
go mod tidy
```
Observação

Se receber o erro go: warning: "all" matched no packages, você esqueceu de adicionar um arquivo de código Go que importa o Driver do SQL do Databricks para Go.
Faça cópias de todos os pacotes necessários para dar suporte a compilações e testes de pacotes em seu módulo main, executando o comando go mod vendor:
```
go mod vendor
```
Modifique seu código conforme necessário para definir a variável de ambiente DATABRICKS_DSN para a autenticação do Azure Databricks. Consulte também Conectar-se com uma cadeia de conexão DSN.
Execute o arquivo de código Go, considerando um arquivo chamado main.go, executando o comando go run:
```
go run main.go
```
Se nenhum erro for retornado, você autenticou com êxito o Driver do SQL do Databricks para Go com o Workspace do Azure Databricks e se conectou ao seu cluster do Azure Databricks em execução ou ao SQL Warehouse nesse espaço de trabalho.

Conectar-se com uma cadeia de conexão DSN

Para acessar clusters e QL warehouses, use sql.Open() para criar um identificador de banco de dados por meio de uma cadeia de conexão DSN (nome da fonte de dados). Este exemplo de código recupera a cadeia de conexão DSN de uma variável de ambiente chamada DATABRICKS_DSN:

package main

import (
  "database/sql"
  "os"
  _ "github.com/databricks/databricks-sql-go"
)

func main() {
  dsn := os.Getenv("DATABRICKS_DSN")

  if dsn == "" {
    panic("No connection string found. " +
          "Set the DATABRICKS_DSN environment variable, and try again.")
  }

  db, err := sql.Open("databricks", dsn)
  if err != nil {
    panic(err)
  }
  defer db.Close()

  if err := db.Ping(); err != nil {
    panic(err)
  }
}

Para especificar a cadeia de conexão DSN no formato correto, confira os exemplos de cadeia de conexão DSN em Autenticação. Por exemplo, para a autenticação de token de acesso pessoal do Azure Databricks, use a seguinte sintaxe, na qual:

<personal-access-token> é o token de acesso pessoal do Azure Databricks dos requisitos.
<server-hostname> pelo valor do Nome do host do servidor nos requisitos.
<port-number> é o valor Porta dos requisitos, que normalmente é 443.
<http-path> é o valor do Caminho HTTP obtido nos requisitos.
<paramX=valueX> é um ou mais Parâmetros opcionais listados posteriormente neste artigo.

token:<personal-access-token>@<server-hostname>:<port-number>/<http-path>?<param1=value1>&<param2=value2>

Por exemplo, para um cluster:

token:dapi12345678901234567890123456789012@adb-1234567890123456.7.azuredatabricks.net:443/sql/protocolv1/o/1234567890123456/1234-567890-abcdefgh

Por exemplo, para um SQL warehouse:

token:dapi12345678901234567890123456789012@adb-1234567890123456.7.azuredatabricks.net:443/sql/1.0/endpoints/a1b234c5678901d2

Observação

Como prática recomendada de segurança, você não deve codificar essa cadeia de conexão DSN em seu código Go. Em vez disso, você deve recuperar essa cadeia de conexão DSN de um local seguro. Por exemplo, o exemplo de código anterior neste artigo usou uma variável de ambiente.

Parâmetros opcionais

Os parâmetros de conexão opcionais com suporte podem ser especificados em <param=value>. Alguns dos mais usados incluem:
- catalog: define o nome inicial do catálogo na sessão.
- schema: define o nome inicial do esquema na sessão.
- maxRows: configura o número máximo de linhas buscadas por solicitação. O padrão é 10000.
- timeout: adiciona o tempo limite (em segundos) para execução da consulta do servidor. O padrão é não ter um tempo limite.
- userAgentEntry: usado para identificar parceiros. Para obter mais informações, consulte a documentação de seu parceiro.
Os parâmetros de sessão opcionais com suporte podem ser especificados em param=value. Alguns dos mais usados incluem:
- ansi_mode: uma cadeia de caracteres booliana. true para instruções de sessão para seguir as regras especificadas pela especificação do SQL ANSI. O padrão do sistema é falso.
- timezone: uma cadeia de caracteres, por exemplo, America/Los_Angeles. Define o fuso horário da sessão. O padrão do sistema é UTC.

Por exemplo, para um SQL warehouse:

token:dapi12345678901234567890123456789012@adb-1234567890123456.7.azuredatabricks.net:443/sql/1.0/endpoints/a1b234c5678901d2?catalog=hive_metastore&schema=example&maxRows=100&timeout=60&timezone=America/Sao_Paulo&ansi_mode=true

Conecte-se com a função `NewConnector`

Como alternativa, use sql.OpenDB() para criar um identificador de banco de dados por meio de um novo objeto de conector criado com dbsql.NewConnector() (conectar-se a clusters do Azure Databricks e SQL warehouses com um novo objeto de conector requer v1.0.0 ou superior do Driver SQL do SQL para Go). Por exemplo:

package main

import (
  "database/sql"
  "os"
  dbsql "github.com/databricks/databricks-sql-go"
)

func main() {
  connector, err := dbsql.NewConnector(
    dbsql.WithAccessToken(os.Getenv("DATABRICKS_ACCESS_TOKEN")),
    dbsql.WithServerHostname(os.Getenv("DATABRICKS_HOST")),
    dbsql.WithPort(443),
    dbsql.WithHTTPPath(os.Getenv("DATABRICKS_HTTP_PATH")),
  )
  if err != nil {
    panic(err)
  }

  db := sql.OpenDB(connector)
  defer db.Close()

  if err := db.Ping(); err != nil {
    panic(err)
  }
}

Para especificar o conjunto correto de configurações NewConnector, confira os exemplos em Autenticação.

Observação

Como melhor prática de segurança, você não deve codificar suas configurações NewConnector em seu código Go. Em vez disso, recupere esses valores de um local seguro. Por exemplo, o código anterior usa variáveis de ambiente.

Algumas das opções funcionais usadas com mais frequência incluem:

WithAccessToken(<access-token>): o token de acesso pessoal do Azure Databricks dos requisitos. Obrigatório string.
WithServerHostname(<server-hostname>): o valor do Nome do host do servidor nos requisitos. Obrigatório string.
WithPort(<port>): o número da porta do servidor, normalmente, 443. Obrigatório int.
WithHTTPPath(<http-path>): o valor do Caminho HTTP dos requisitos. Obrigatório string.
WithInitialNamespace(<catalog>, <schema>): o nome do esquema e do catálogo na sessão. string, string opcional.
WithMaxRows(<max-rows>): o número máximo de linhas buscadas por solicitação. O padrão é 10000.. Opcional int.
WithSessionParams(<params-map>): os parâmetros de sessão, incluindo "fuso horário" e "ansi_mode". map[string]string opcional.
WithTimeout(<timeout>). O tempo limite (em time.Duration) para execução da consulta do servidor. O padrão é não ter um tempo limite. Opcional.
WithUserAgentEntry(<isv-name-plus-product-name>). Usado para identificar parceiros. Para obter mais informações, consulte a documentação de seu parceiro. string opcional.

Por exemplo:

connector, err := dbsql.NewConnector(
  dbsql.WithAccessToken(os.Getenv("DATABRICKS_ACCESS_TOKEN")),
  dbsql.WithServerHostname(os.Getenv("DATABRICKS_HOST")),
  dbsql.WithPort(443),
  dbsql.WithHTTPPath(os.Getenv("DATABRICKS_HTTP_PATH")),
  dbsql.WithInitialNamespace("samples", "nyctaxi"),
  dbsql.WithMaxRows(100),
  dbsql.SessionParams(map[string]string{"timezone": "America/Sao_Paulo", "ansi_mode": "true"}),
  dbsql.WithTimeout(time.Minute),
  dbsql.WithUserAgentEntry("example-user"),
)

Autenticação

O Driver do SQL do Databricks para Go dá suporte para os seguintes tipos de autenticação do Azure Databricks:

Autenticação de token de acesso pessoal do Databricks
Autenticação de token do Microsoft Entra ID
Autenticação U2M (usuário para computador) do OAuth
Autenticação OAuth máquina a máquina (M2M)

O Driver SQL do Databricks para Go ainda não dá suporte para os seguintes tipos de autenticação do Azure Databricks:

Autenticação de token de acesso pessoal do Databricks

Para usar o Driver SQL do Databricks para Go com autenticação de token de acesso pessoal do Azure Databricks, primeiro você deve criar um token de acesso pessoal do Azure Databricks. Para obter detalhes sobre esta etapa, consulte Tokens de acesso pessoal do Azure Databricks para usuários do workspace.

Para autenticar o Driver do Databricks SQL para Go com uma cadeia de conexão DSN e o exemplo de código em Conectar com uma cadeia de conexão DSN, use a seguinte sintaxe de cadeia de conexão DSN, na qual:

<personal-access-token> é o token de acesso pessoal do Azure Databricks dos requisitos.
<server-hostname> pelo valor do Nome do host do servidor nos requisitos.
<port-number> é o valor Porta dos requisitos, que normalmente é 443.
<http-path> é o valor do Caminho HTTP obtido nos requisitos.

Você também pode acrescentar um ou mais parâmetros Opcionais listados anteriormente neste artigo.

token:<personal-access-token>@<server-hostname>:<port-number>/<http-path>

Para autenticar o Driver do Databricks SQL para Go com a função NewConnector, use o seguinte trecho de código e o exemplo de código em Conectar com a função NewConnector, que pressupõe que você tenha definido as variáveis de ambiente a seguir:

DATABRICKS_SERVER_HOSTNAMEdefinido como o valor Nome do Host do Servidor do seu cluster ou SQL Warehouse.
DATABRICKS_HTTP_PATH, definido para o valor do Caminho HTTP para seu cluster ou SQL Warehouse.
DATABRICKS_TOKEN, definido como o token de acesso pessoal do Azure Databricks.

Para definir variáveis de ambiente, confira a documentação do sistema operacional.

connector, err := dbsql.NewConnector(
  dbsql.WithServerHostname(os.Getenv("DATABRICKS_SERVER_HOSTNAME")),
  dbsql.WithHTTPPath(os.Getenv("DATABRICKS_HTTP_PATH")),
  dbsql.WithPort(443),
  dbsql.WithAccessToken(os.Getenv("DATABRICKS_TOKEN")),
)

Autenticação de token do Microsoft Entra ID

O Driver do SQL do Databricks para Go dá suporte a tokens do Microsoft Entra ID para um usuário do Azure Databricks ou uma entidade de serviço do Microsoft Entra ID.

Para criar um token de acesso do Microsoft Entra ID, faça o seguinte:

Para um usuário do Azure Databricks, você pode usar a CLI do Azure. Confira Obter tokens do Microsoft Entra ID para usuários usando a CLI do Azure.
- Para obter uma entidade de serviço do Microsoft Entra ID, confira Obter um token de acesso do Microsoft Entra ID com a CLI do Azure. Para criar uma entidade de serviço gerenciada do Microsoft Entra ID, consulte Gerenciar entidades de serviço.
Os tokens do Microsoft Entra ID têm um tempo de vida padrão de cerca de 1 hora. Para criar um novo token do Microsoft Entra ID, repita esse processo.

Para autenticar o Driver do Databricks SQL para Go com uma cadeia de conexão DSN e o exemplo de código em Conectar com uma cadeia de conexão DSN, use a seguinte sintaxe de cadeia de conexão DSN, na qual:
- <microsoft-entra-id-token> é seu token do Microsoft Entra ID.
- <server-hostname> pelo valor do Nome do host do servidor nos requisitos.
- <port-number> é o valor Porta dos requisitos, que normalmente é 443.
- <http-path> é o valor do Caminho HTTP obtido nos requisitos.
Você também pode acrescentar um ou mais parâmetros Opcionais listados anteriormente neste artigo.
```
token:<microsoft-entra-id-token>@<server-hostname>:<port-number>/<http-path>
```
Para autenticar o Driver do Databricks SQL para Go com a função NewConnector, use o seguinte trecho de código e o exemplo de código em Conectar com a função NewConnector, que pressupõe que você tenha definido as variáveis de ambiente a seguir:
- DATABRICKS_SERVER_HOSTNAMEdefinido como o valor Nome do Host do Servidor do seu cluster ou SQL Warehouse.
- DATABRICKS_HTTP_PATH, definido para o valor do Caminho HTTP para seu cluster ou SQL Warehouse.
- DATABRICKS_TOKEN, definido como seu token do Microsoft Entra ID.
Para definir variáveis de ambiente, confira a documentação do sistema operacional.
```
connector, err := dbsql.NewConnector(
  dbsql.WithServerHostname(os.Getenv("DATABRICKS_SERVER_HOSTNAME")),
  dbsql.WithHTTPPath(os.Getenv("DATABRICKS_HTTP_PATH")),
  dbsql.WithPort(443),
  dbsql.WithAccessToken(os.Getenv("DATABRICKS_TOKEN")),
)
```

Autenticação U2M (usuário para computador) do OAuth

O Databricks SQL Driver for Go versões 1.5.0 e posteriores dão suporte a autenticação U2M (usuário para computador) do OAuth.

Para usar o Driver do SQL do Databricks para Go com uma cadeia de conexão DSN e o exemplo de código em Conectar com uma cadeia de conexão DSN, use a seguinte sintaxe de cadeia de conexão DSN, na qual:

<server-hostname> pelo valor do Nome do host do servidor nos requisitos.
<port-number> é o valor Porta dos requisitos, que normalmente é 443.
<http-path> é o valor do Caminho HTTP obtido nos requisitos.

Você também pode acrescentar um ou mais parâmetros Opcionais listados anteriormente neste artigo.

<server-hostname>:<port-number>/<http-path>?authType=OauthU2M

Para autenticar o Driver do Databricks SQL para Go com a função NewConnector, você deve primeiro adicionar o seguinte à sua declaração import:

"github.com/databricks/databricks-sql-go/auth/oauth/u2m"

Em seguida, use o seguinte trecho de código e o exemplo de código em Conectar com a função NewConnector, que pressupõe que você tenha definido as seguintes variáveis de ambiente:

DATABRICKS_SERVER_HOSTNAMEdefinido como o valor Nome do Host do Servidor do seu cluster ou SQL Warehouse.
DATABRICKS_HTTP_PATH, definido para o valor do Caminho HTTP para seu cluster ou SQL Warehouse.

Para definir variáveis de ambiente, confira a documentação do sistema operacional.

authenticator, err := u2m.NewAuthenticator(os.Getenv("DATABRICKS_SERVER_HOSTNAME"), 1*time.Minute)
if err != nil {
  panic(err)
}

connector, err := dbsql.NewConnector(
  dbsql.WithServerHostname(os.Getenv("DATABRICKS_SERVER_HOSTNAME")),
  dbsql.WithHTTPPath(os.Getenv("DATABRICKS_HTTP_PATH")),
  dbsql.WithPort(443),
  dbsql.WithAuthenticator(authenticator),
)

Autenticação M2M (de computador para computador) do OAuth

O Databricks SQL Driver for Go versões 1.5.2 e posteriores dão suporte a autenticação M2M (computador para computador) do OAuth.

Para usar o Driver do SQL do Databricks para Go com a autenticação OAuth M2M, você deve fazer o seguinte:

Crie uma entidade de serviço do Azure Databricks em seu workspace do Azure Databricks e crie um segredo OAuth para essa entidade de serviço.

Para criar a entidade de serviço e seu segredo OAuth, consulte Autenticar o acesso ao Azure Databricks com uma entidade de serviço usando OAuth (OAuth M2M). Anote o valor do UUID ou da ID do aplicativo da entidade de serviço e o valor do Segredo do segredo OAuth da entidade de serviço.
Dê a essa entidade de serviço acesso ao cluster ou ao warehouse.

Para conceder acesso à entidade de serviço no seu cluster ou warehouse, confira Permissões de computação ou Gerenciar um SQL warehouse.

<server-hostname> pelo valor do Nome do host do servidor nos requisitos.
<port-number> é o valor Porta dos requisitos, que normalmente é 443.
<http-path> é o valor do Caminho HTTP obtido nos requisitos.
<client-id> é o valor da UUID da entidade de serviço ou da ID do aplicativo.
<client-secret> é o valor do Segredo para o segredo do OAuth da entidade de serviço.

Você também pode acrescentar um ou mais parâmetros Opcionais listados anteriormente neste artigo.

<server-hostname>:<port-number>/<http-path>?authType=OAuthM2M&clientID=<client-id>&clientSecret=<client-secret>

Para autenticar o Driver do Databricks SQL para Go com a função NewConnector, você deve primeiro adicionar o seguinte à sua declaração import:

"github.com/databricks/databricks-sql-go/auth/oauth/m2m"

Em seguida, use o seguinte trecho de código e o exemplo de código em Conectar com a função NewConnector, que pressupõe que você tenha definido as seguintes variáveis de ambiente:

DATABRICKS_SERVER_HOSTNAMEdefinido como o valor Nome do Host do Servidor do seu cluster ou SQL Warehouse.
DATABRICKS_HTTP_PATH, definido para o valor do Caminho HTTP para seu cluster ou SQL Warehouse.
DATABRICKS_CLIENT_ID, definido como o valor do UUID ou da ID do aplicativo da entidade de serviço.
DATABRICKS_CLIENT_SECRET, definido como o valor do Segredo para o segredo OAuth da entidade de serviço.

Para definir variáveis de ambiente, confira a documentação do sistema operacional.

authenticator := m2m.NewAuthenticator(
  os.Getenv("DATABRICKS_CLIENT_ID"),
  os.Getenv("DATABRICKS_CLIENT_SECRET"),
  os.Getenv("DATABRICKS_SERVER_HOSTNAME"),
)

connector, err := dbsql.NewConnector(
  dbsql.WithServerHostname(os.Getenv("DATABRICKS_SERVER_HOSTNAME")),
  dbsql.WithHTTPPath(os.Getenv("DATABRICKS_HTTP_PATH")),
  dbsql.WithPort(443),
  dbsql.WithAuthenticator(authenticator),
)

Consultar dados

O exemplo de código a seguir demonstra como chamar o Driver de SQL do Databricks para Go para executar uma consulta SQL básica em um recurso de computação do Azure Databricks. Esse comando retorna as duas primeiras linhas da tabela trips no esquema nyctaxi do catálogo samples.

Este exemplo de código recupera a cadeia de conexão DSN de uma variável de ambiente chamada DATABRICKS_DSN.

package main

import (
  "database/sql"
  "fmt"
  "os"
  "time"

  _ "github.com/databricks/databricks-sql-go"
)

func main() {
  dsn := os.Getenv("DATABRICKS_DSN")

  if dsn == "" {
    panic("No connection string found." +
          "Set the DATABRICKS_DSN environment variable, and try again.")
  }

  db, err := sql.Open("databricks", dsn)
  if err != nil {
    panic(err)
  }

  defer db.Close()

  var (
    tpep_pickup_datetime  time.Time
    tpep_dropoff_datetime time.Time
    trip_distance         float64
    fare_amount           float64
    pickup_zip            int
    dropoff_zip           int
  )

  rows, err := db.Query("SELECT * FROM samples.nyctaxi.trips LIMIT 2")
  if err != nil {
    panic(err)
  }

  defer rows.Close()

  fmt.Print("tpep_pickup_datetime,",
    "tpep_dropoff_datetime,",
    "trip_distance,",
    "fare_amount,",
    "pickup_zip,",
    "dropoff_zip\n")

  for rows.Next() {
    err := rows.Scan(&tpep_pickup_datetime,
      &tpep_dropoff_datetime,
      &trip_distance,
      &fare_amount,
      &pickup_zip,
      &dropoff_zip)
    if err != nil {
      panic(err)
    }

    fmt.Print(tpep_pickup_datetime, ",",
      tpep_dropoff_datetime, ",",
      trip_distance, ",",
      fare_amount, ",",
      pickup_zip, ",",
      dropoff_zip, "\n")
  }

  err = rows.Err()
  if err != nil {
    panic(err)
  }
}

Gerenciar arquivos em volumes do Catálogo do Unity

O driver do Databricks SQL permite gravar arquivos locais em volumes do Catálogo do Unity, baixar arquivos de volumes e excluir arquivos de volumes, conforme mostrado no seguinte exemplo:

package main

import (
  "context"
  "database/sql"
  "os"

  _ "github.com/databricks/databricks-sql-go"
  "github.com/databricks/databricks-sql-go/driverctx"
)

func main() {
  dsn := os.Getenv("DATABRICKS_DSN")

  if dsn == "" {
    panic("No connection string found." +
      "Set the DATABRICKS_DSN environment variable, and try again.")
  }

  db, err := sql.Open("databricks", dsn)
  if err != nil {
    panic(err)
  }
  defer db.Close()

  // For writing local files to volumes and downloading files from volumes,
  // you must first specify the path to the local folder that contains the
  // files to be written or downloaded.
  // For multiple folders, add their paths to the following string array.
  // For deleting files in volumes, this string array is ignored but must
  // still be provided, so in that case its value can be set for example
  // to an empty string.
  ctx := driverctx.NewContextWithStagingInfo(
    context.Background(),
    []string{"/tmp/"},
  )

  // Write a local file to the path in the specified volume.
  // Specify OVERWRITE to overwrite any existing file in that path.
  db.ExecContext(ctx, "PUT '/tmp/my-data.csv' INTO '/Volumes/main/default/my-volume/my-data.csv' OVERWRITE")

  // Download a file from the path in the specified volume.
  db.ExecContext(ctx, "GET '/Volumes/main/default/my-volume/my-data.csv' TO '/tmp/my-downloaded-data.csv'")

  // Delete a file from the path in the specified volume.
  db.ExecContext(ctx, "REMOVE '/Volumes/main/default/my-volume/my-data.csv'")

  db.Close()
}

Logging

Use github.com/databricks/databricks-sql-go/logger para registrar mensagens que o Databricks SQL Driver for Go emite. O exemplo de código a seguir usa sql.Open() para criar um identificador de banco de dados por meio de uma cadeia de conexão DSN. Este exemplo de código recupera a cadeia de conexão DSN de uma variável de ambiente chamada DATABRICKS_DSN. Todas as mensagens de log emitidas no nível debug e abaixo são gravadas no arquivo results.log.

package main

import (
  "database/sql"
  "io"
  "log"
  "os"

  _ "github.com/databricks/databricks-sql-go"
  dbsqllog "github.com/databricks/databricks-sql-go/logger"
)

func main() {
  dsn := os.Getenv("DATABRICKS_DSN")

  // Use the specified file for logging messages to.
  file, err := os.Create("results.log")
  if err != nil {
    log.Fatal(err)
  }
  defer file.Close()

  writer := io.Writer(file)

  // Log messages at the debug level and below.
  if err := dbsqllog.SetLogLevel("debug"); err != nil {
    log.Fatal(err)
  }

  // Log messages to the file.
  dbsqllog.SetLogOutput(writer)

  if dsn == "" {
    panic("Error: Cannot connect. No connection string found. " +
      "Set the DATABRICKS_DSN environment variable, and try again.")
  }

  db, err := sql.Open("databricks", dsn)
  if err != nil {
    panic(err)
  }
  defer db.Close()

  if err := db.Ping(); err != nil {
    panic(err)
  }
}

Testando

Para testar seu código, use estruturas de teste do Go, como a biblioteca padrão de teste. Para testar seu código em condições simuladas sem chamar pontos de extremidade da API REST do Azure Databricks ou alterar o estado de suas contas ou workspaces do Azure Databricks, use bibliotecas de simulação do Go, como Testify.

Por exemplo, dado o seguinte arquivo chamado helpers.go que contém uma função GetDBWithDSNPAT que retorna uma conexão de workspace do Azure Databricks, uma função GetNYCTaxiTrips que retorna dados da tabela trips no catálogo samples no esquema nyctaxi e um PrintNYCTaxiTrips que imprime os dados retornados:

package main

import (
  "database/sql"
  "fmt"
  "strconv"
  "time"
)

func GetDBWithDSNPAT(dsn string) (*sql.DB, error) {
  db, err := sql.Open("databricks", dsn)
  if err != nil {
    return nil, err
  }
  return db, nil
}

func GetNYCTaxiTrips(db *sql.DB, numRows int) (*sql.Rows, error) {
  rows, err := db.Query("SELECT * FROM samples.nyctaxi.trips LIMIT " + strconv.Itoa(numRows))
  if err != nil {
    return nil, err
  }
  return rows, nil
}

func PrintNYCTaxiTrips(rows *sql.Rows) {
  var (
    tpep_pickup_datetime  time.Time
    tpep_dropoff_datetime time.Time
    trip_distance         float64
    fare_amount           float64
    pickup_zip            int
    dropoff_zip           int
  )

  fmt.Print(
    "tpep_pickup_datetime,",
    "tpep_dropoff_datetime,",
    "trip_distance,",
    "fare_amount,",
    "pickup_zip,",
    "dropoff_zip\n",
  )

  for rows.Next() {
    err := rows.Scan(
      &tpep_pickup_datetime,
      &tpep_dropoff_datetime,
      &trip_distance,
      &fare_amount,
      &pickup_zip,
      &dropoff_zip,
    )
    if err != nil {
      panic(err)
    }

    fmt.Print(
      tpep_pickup_datetime, ",",
      tpep_dropoff_datetime, ",",
      trip_distance, ",",
      fare_amount, ",",
      pickup_zip, ",",
      dropoff_zip, "\n",
    )
  }

  err := rows.Err()
  if err != nil {
    panic(err)
  }
}

E dado o seguinte arquivo chamado main.go que chama essas funções:

package main

import (
  "os"
)

func main() {
  db, err := GetDBWithDSNPAT(os.Getenv("DATABRICKS_DSN"))
  if err != nil {
    panic(err)
  }

  rows, err := GetNYCTaxiTrips(db, 2)
  if err != nil {
    panic(err)
  }

  PrintNYCTaxiTrips(rows)
}

O arquivo nomeado helpers_test.go a seguir testa se a função GetNYCTaxiTrips retorna a resposta esperada. Em vez de criar uma conexão real com o workspace de destino, esse teste simula um objeto sql.DB. O teste também simula alguns dados que estão em conformidade com o esquema e os valores que estão nos dados reais. O teste retorna os dados simulados por meio da conexão simulada e verifica se um dos valores das linhas de dados simuladas corresponde ao valor esperado.

package main

import (
  "database/sql"
  "testing"

  "github.com/stretchr/testify/assert"
  "github.com/stretchr/testify/mock"
)

// Define an interface that contains a method with the same signature
// as the real GetNYCTaxiTrips function that you want to test.
type MockGetNYCTaxiTrips interface {
  GetNYCTaxiTrips(db *sql.DB, numRows int) (*sql.Rows, error)
}

// Define a struct that represents the receiver of the interface's method
// that you want to test.
type MockGetNYCTaxiTripsObj struct {
  mock.Mock
}

// Define the behavior of the interface's method that you want to test.
func (m *MockGetNYCTaxiTripsObj) GetNYCTaxiTrips(db *sql.DB, numRows int) (*sql.Rows, error) {
  args := m.Called(db, numRows)
  return args.Get(0).(*sql.Rows), args.Error(1)
}

func TestGetNYCTaxiTrips(t *testing.T) {
  // Instantiate the receiver.
  mockGetNYCTaxiTripsObj := new(MockGetNYCTaxiTripsObj)

  // Define how the mock function should be called and what it should return.
  // We're not concerned with whether the actual database is connected to--just
  // what is returned.
  mockGetNYCTaxiTripsObj.On("GetNYCTaxiTrips", mock.Anything, mock.AnythingOfType("int")).Return(&sql.Rows{}, nil)

  // Call the mock function that you want to test.
  rows, err := mockGetNYCTaxiTripsObj.GetNYCTaxiTrips(nil, 2)

  // Assert that the mock function was called as expected.
  mockGetNYCTaxiTripsObj.AssertExpectations(t)

  // Assert that the mock function returned what you expected.
  assert.NotNil(t, rows)
  assert.Nil(t, err)
}

Como a função GetNYCTaxiTrips contém uma instrução SELECT e, portanto, não altera o estado da tabela trips, a simulação não é absolutamente necessária neste exemplo. No entanto, a simulação permite que você execute rapidamente seus testes sem esperar que uma conexão real seja feita com o workspace. Além disso, a simulação permite executar testes simulados várias vezes para funções que podem alterar o estado de uma tabela, como INSERT INTO, UPDATE e DELETE FROM.

Recursos adicionais

O repositório Databricks SQL Driver for Go no GitHub
A página inicial do pacote de banco de dados/sql
Os exemplos do Driver SQL do Databricks para Go no GitHub

Compartilhar via

Driver do Databricks SQL para Go

Requisitos

Introdução ao Driver do Databricks SQL para Go

Conectar-se com uma cadeia de conexão DSN

Parâmetros opcionais

Conecte-se com a função `NewConnector`

Autenticação

Autenticação de token de acesso pessoal do Databricks

Autenticação de token do Microsoft Entra ID

Autenticação U2M (usuário para computador) do OAuth

Autenticação M2M (de computador para computador) do OAuth

Consultar dados

Gerenciar arquivos em volumes do Catálogo do Unity

Logging

Testando

Recursos adicionais

Comentários

Recursos adicionais

Compartilhar via

Driver do Databricks SQL para Go

Requisitos

Introdução ao Driver do Databricks SQL para Go

Conectar-se com uma cadeia de conexão DSN

Parâmetros opcionais

Conecte-se com a função NewConnector

Autenticação

Autenticação de token de acesso pessoal do Databricks

Autenticação de token do Microsoft Entra ID

Autenticação U2M (usuário para computador) do OAuth

Autenticação M2M (de computador para computador) do OAuth

Consultar dados

Gerenciar arquivos em volumes do Catálogo do Unity

Logging

Testando

Recursos adicionais

Comentários

Recursos adicionais

Conecte-se com a função `NewConnector`