Sterownik SQL usługi Databricks dla języka Go

Sterownik SQL usługi Databricks dla języka Go to biblioteka Go, która umożliwia uruchamianie poleceń SQL w zasobach obliczeniowych usługi Azure Databricks za pomocą kodu Go. Ten artykuł uzupełnia README sterownika SQL usługi Databricks dla języka Go, dokumentację interfejsu API i przykłady.

Wymagania

• Maszyna deweloperna z systemem Go w wersji 1.20 lub nowszej. Aby wydrukować zainstalowaną wersję języka Go, uruchom polecenie go version. Pobierz i zainstaluj język Go.
• Istniejący klaster lub magazyn danych SQL.
• Wartości Nazwa hosta serwera, Port i Ścieżka HTTP dla istniejącego klastra lub usługi SQL Warehouse.
  • Pobierz te wartości dla klastra.
  • Pobierz te wartości dla usługi SQL Warehouse.

Wprowadzenie do sterownika SQL usługi Databricks dla języka Go

1. Na maszynie deweloperskiej z już zainstalowanym programem Go w wersji 1.20 lub nowszej, a istniejący projekt kodu Języka Go został już utworzony, utwórz go.mod plik w celu śledzenia zależności kodu języka Go, uruchamiając go mod init polecenie, na przykład:

   go mod init sample
   

2. Zainstaluj zależność pakietu Databricks SQL Driver dla Go, uruchamiając polecenie go mod edit -require, zastępując v1.5.2 najnowszą wersją pakietu Databricks SQL Driver dla Go, jak wymieniono w wersjach.

   go mod edit -require github.com/databricks/databricks-sql-go@v1.5.2
   

   Plik go.mod powinien teraz wyglądać następująco:

   module sample
   
   go 1.20
   
   require github.com/databricks/databricks-sql-go v1.5.2
   

3. W projekcie utwórz plik kodu w języku Go, który importuje sterownik SQL Databricks dla języka Go. Poniższy przykład w pliku o nazwie o następującej main.go zawartości zawiera listę wszystkich klastrów w obszarze roboczym usługi 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)
     }
   }
   

4. Dodaj wszystkie brakujące zależności modułu go mod tidy , uruchamiając polecenie :

   go mod tidy
   

   Uwaga

   Jeśli wystąpi błąd go: warning: "all" matched no packages, zapomniałeś dodać plik kodu w języku Go, który importuje sterownik SQL dla usługi Databricks dla języka Go.

5. Utwórz kopie wszystkich pakietów wymaganych do obsługi kompilacji i testów pakietów w main module, uruchamiając go mod vendor polecenie :

   go mod vendor
   

6. Zmodyfikuj kod zgodnie z potrzebami, aby ustawić zmienną DATABRICKS_DSN środowiskową na potrzeby uwierzytelniania usługi Azure Databricks. Zobacz też Nawiązywanie połączenia za pomocą parametry połączenia DSN.

7. Uruchom plik kodu w języku Go, zakładając, że jego nazwa to main.go, wykonaj polecenie go run.

   go run main.go
   

8. Jeśli nie zostaną zwrócone żadne błędy, pomyślnie uwierzytelniono sterownik SQL usługi Databricks dla języka Go przy użyciu obszaru roboczego usługi Azure Databricks i nawiązano połączenie z uruchomionym klastrem usługi Azure Databricks lub usługą SQL Warehouse w tym obszarze roboczym.

Nawiązywanie połączenia za pomocą łańcucha połączenia DSN

Aby uzyskać dostęp do klastrów i magazynów SQL, użyj polecenia sql.Open() , aby utworzyć uchwyt bazy danych za pomocą łańcucha połączenia do nazwy źródła danych (DSN). Ten przykład kodu pobiera parametry połączenia DSN ze zmiennej środowiskowej o nazwie 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)
  }
}

Aby określić parametry połączenia DSN w poprawnym formacie, zobacz przykłady parametry połączenia DSN w temacie Authentication (Uwierzytelnianie). Na przykład w przypadku uwierzytelniania osobistego tokenu dostępu usługi Azure Databricks użyj następującej składni, gdzie:

• <personal-access-token> to osobisty token dostępu usługi Azure Databricks wzięty z wymagań.
• <server-hostname> Nazwa hosta serwera to wartość z wymagań.
• <port-number> to wartość Port z wymagań, czyli zazwyczaj 443.
• Wartością ścieżki HTTP z wymagań jest <http-path>.
• <paramX=valueX> jest co najmniej jednym parametrem opcjonalnym wymienionym w dalszej części tego artykułu.

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

Na przykład w przypadku klastra:

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

Na przykład w przypadku usługi SQL Warehouse:

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

Uwaga

Najlepszą praktyką w zakresie bezpieczeństwa jest unikanie zakodowania tego ciągu znaków DSN w kodzie Go. Zamiast tego należy pobrać ten ciąg połączenia DSN z bezpiecznej lokalizacji. Na przykład, wcześniejszy przykład kodu w tym artykule zastosował zmienną środowiskową.

Parametry opcjonalne

• Obsługiwane opcjonalne parametry połączenia można określić w pliku <param=value>. Niektóre z najczęściej używanych elementów to:
  • catalog: Ustawia początkową nazwę katalogu w sesji.
  • schema: Ustawia początkową nazwę schematu w sesji.
  • maxRows: Konfiguruje maksymalną liczbę wierszy pobranych na żądanie. Wartość domyślna to 10000.
  • timeout: dodaje limit czasu (w sekundach) dla wykonywania zapytania serwera. Wartość domyślna to brak limitu czasu.
  • userAgentEntry: służy do identyfikowania partnerów. Aby uzyskać więcej informacji, zobacz dokumentację partnera.
• Obsługiwane parametry sesji opcjonalnej można określić w pliku param=value. Niektóre z najczęściej używanych elementów to:
  • ansi_mode: ciąg typu Boolean. Aby instrukcje sesji były zgodne z regułami określonymi przez specyfikację ANSI SQL, należy przestrzegać tych zasad. Wartość domyślna systemu to false.
  • timezone: ciąg, na przykład America/Los_Angeles. Ustawia strefę czasową sesji. Domyślną wartością systemu jest UTC.
  • query_tags: Ciąg par klucz:wartość rozdzielanych przecinkami do dołączenia do zapytań SQL w celu śledzenia w system.query.history, na przykład team:engineering,dashboard:abc123. Ta funkcja jest dostępna w publicznej wersji testowej.

Na przykład w przypadku usługi 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&query_tags=team:engineering,env:prod

Nawiązywanie połączenia z funkcją NewConnector

Alternatywnie użyj sql.OpenDB(), aby utworzyć dojście bazy danych za pomocą nowego obiektu łącznika utworzonego za pomocą dbsql.NewConnector() (łączenie z klastrami Azure Databricks i magazynami SQL z nowym obiektem łącznika wymaga wersji 1.0.0 lub nowszej sterownika SQL Databricks dla języka Go). Na przykład:

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)
  }
}

Aby określić prawidłowy zestaw NewConnector ustawień, zobacz przykłady w temacie Authentication (Uwierzytelnianie).

Uwaga

Jako najlepszą praktykę w zakresie zabezpieczeń, nie powinieneś wprowadzać na stałe ustawień NewConnector w swoim kodzie Go. Zamiast tego należy pobrać te wartości z bezpiecznej lokalizacji. Na przykład powyższy kod używa zmiennych środowiskowych.

Niektóre z najczęściej używanych opcji funkcjonalnych to:

• WithAccessToken(<access-token>): Osobisty token dostępu usługi Azure Databricks z wymagań. Wymaganestring.
• WithServerHostname(<server-hostname>): wartość Nazwa hosta serwera z wymagań. Wymaganestring.
• WithPort(<port>): numer portu serwera, zazwyczaj 443. Wymaganeint.
• WithHTTPPath(<http-path>): wartość ścieżki HTTP z wymagań. Wymagane .string
• WithInitialNamespace(<catalog>, <schema>):Nazwa katalogu i schematu w sesji. Opcjonalnystring, string.
• WithMaxRows(<max-rows>): maksymalna liczba wierszy pobranych na żądanie. Wartość domyślna to 10000. Opcjonalne int.
• WithSessionParams(<params-map>): parametry sesji, w tym "strefa czasowa", "ansi_mode" i "query_tags". Opcjonalnymap[string]string.
• WithTimeout(<timeout>). Limit czasu (w time.Duration) dla wykonywania zapytania serwera. Wartość domyślna to brak limitu czasu. Opcjonalny.
• WithUserAgentEntry(<isv-name-plus-product-name>). Służy do identyfikowania partnerów. Aby uzyskać więcej informacji, zobacz dokumentację partnera. Opcjonalnystring.

Na przykład:

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", "query_tags": "team:analytics,project:reporting"}),
  dbsql.WithTimeout(time.Minute),
  dbsql.WithUserAgentEntry("example-user"),
)

Uwierzytelnianie

Sterownik SQL usługi Databricks dla języka Go obsługuje następujące typy uwierzytelniania usługi Azure Databricks:

• Uwierzytelnianie osobistego tokenu dostępu usługi Databricks
• Uwierzytelnianie za pomocą tokenu identyfikacyjnego Microsoft Entra ID
• Uwierzytelnianie typu użytkownik-komputer (U2M) OAuth
• Uwierzytelnianie OAuth między maszynami (M2M)

Sterownik SQL usługi Databricks dla języka Go nie obsługuje jeszcze następujących typów uwierzytelniania usługi Azure Databricks:

• Uwierzytelnianie za pomocą tożsamości zarządzanych platformy Azure
• Uwierzytelnianie za pomocą jednostek usługi Entra firmy Microsoft
• Uwierzytelnianie za pomocą interfejsu wiersza polecenia platformy Azure

Uwierzytelnianie osobistego tokenu dostępu usługi Databricks

Aby użyć sterownika SQL Databricks dla Go z uwierzytelnianiem za pomocą osobistego tokenu dostępu Azure Databricks, musisz najpierw utworzyć osobisty token dostępu Azure Databricks. Aby uzyskać szczegółowe informacje na temat tego kroku, zobacz Tworzenie osobistych tokenów dostępu dla użytkowników obszaru roboczego.

pl-PL: Aby uwierzytelnić sterownik SQL usługi Databricks dla języka Go przy użyciu ciągu połączenia DSN i przykładu kodu w temacie Nawiązywanie połączenia z użyciem ciągu DSN, użyj następującej składni ciągu połączenia DSN, gdzie:

• <personal-access-token> to osobisty token dostępu usługi Azure Databricks wzięty z wymagań.
• <server-hostname> to wartość 'Nazwa hosta serwera' z wymagań.
• <port-number> to jest wartość portu z wymagań, która zazwyczaj wynosi 443.
• <http-path> jest wartością ścieżki HTTP z wymagań.

Możesz również dołączyć jeden lub więcej parametrów opcjonalnych wymienionych wcześniej w tym artykule.

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

Aby uwierzytelnić sterownik SQL usługi Databricks dla języka Go za pomocą funkcji NewConnector, użyj następującego fragmentu kodu oraz przykładu kodu w sekcji Połącz z funkcją NewConnector, która zakłada, że ustawiono następujące zmienne środowiskowe:

• DATABRICKS_SERVER_HOSTNAMEustaw wartość Nazwa hosta serwera dla klastra lub usługi SQL Warehouse.
• DATABRICKS_HTTP_PATH, ustaw wartość Ścieżka HTTP dla klastra lub magazynu SQL.
• DATABRICKS_TOKEN, ustawiono jako osobisty token dostępu w Azure Databricks.

Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

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")),
)

Uwierzytelnianie tokenu Microsoft Entra ID

Sterownik SQL usługi Databricks dla języka Go obsługuje tokeny identyfikatora Entra firmy Microsoft dla użytkownika usługi Azure Databricks lub jednostki usługi Microsoft Entra ID.

Aby utworzyć token dostępu microsoft Entra ID, wykonaj następujące czynności:

• W przypadku użytkownika usługi Azure Databricks lub jednostki usługi Microsoft Entra ID użyj Azure CLI. Zobacz Pobieranie ręczne tokenów Microsoft Entra ID. Aby utworzyć zarządzaną jednostkę usługi Microsoft Entra ID, zapoznaj się z Jednostkami usługi.

  Tokeny identyfikatora Entra firmy Microsoft mają domyślny okres istnienia około 1 godziny. Aby utworzyć nowy token identyfikatora Entra firmy Microsoft, powtórz ten proces.

  pl-PL: Aby uwierzytelnić sterownik SQL usługi Databricks dla języka Go przy użyciu ciągu połączenia DSN i przykładu kodu w temacie Nawiązywanie połączenia z użyciem ciągu DSN, użyj następującej składni ciągu połączenia DSN, gdzie:

  • <microsoft-entra-id-token> to twój token identyfikatora Entra firmy Microsoft.
  • <server-hostname> wartość Nazwa hosta serwera wymagań.
  • <port-number> jest wartością Port z wymagań, która zazwyczaj wynosi 443.
  • <http-path> jest wartością ścieżki HTTP z wymagań.

  Możesz również dołączyć jeden lub więcej parametrów opcjonalnych wymienionych wcześniej w tym artykule.

  token:<microsoft-entra-id-token>@<server-hostname>:<port-number>/<http-path>
  

  Aby uwierzytelnić sterownik SQL usługi Databricks dla języka Go za pomocą funkcji NewConnector, użyj następującego fragmentu kodu oraz przykładu kodu w sekcji Połącz z funkcją NewConnector, która zakłada, że ustawiono następujące zmienne środowiskowe:

  • DATABRICKS_SERVER_HOSTNAMEustaw wartość Nazwa hosta serwera dla klastra lub usługi SQL Warehouse.
  • DATABRICKS_HTTP_PATH, ustaw wartość Ścieżka HTTP dla klastra lub SQL Warehouse.
  • DATABRICKS_TOKEN, ustaw wartość tokenu identyfikatora Entra firmy Microsoft.

  Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

  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")),
  )
  

Uwierzytelnianie OAuth typu użytkownik-maszyna (U2M)

Sterownik SQL usługi Databricks dla języka Go w wersji 1.5.0 lub nowszej obsługuje uwierzytelnianie OAuth typu użytkownik-maszyna (U2M).

Aby użyć sterownika SQL usługi Databricks dla języka Go z ciągiem połączenia DSN i przykładem kodu w artykule Nawiązywanie połączenia za pomocą ciągu połączenia DSN, użyj następującej składni ciągu połączenia DSN, gdzie:

• <server-hostname> jest wartością nazwy hosta serwera z wymagań.
• <port-number> to wartość portu zgodna z wymaganiami, która zazwyczaj wynosi 443.
• <http-path> jest wartością ścieżki HTTP z wymagań.

Możesz również dołączyć jeden lub więcej parametrów opcjonalnych wymienionych wcześniej w tym artykule.

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

Aby uwierzytelnić sterownik SQL Databricks dla języka Go za pomocą funkcji NewConnector, należy najpierw dodać poniższy kod do deklaracji import.

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

Następnie użyj następującego fragmentu kodu i przykładu kodu w sekcji Connect with the NewConnector function (Połącz z funkcją), która zakłada, że ustawiono następujące zmienne środowiskowe:

• DATABRICKS_SERVER_HOSTNAMEustaw wartość Nazwa hosta serwera dla klastra lub usługi SQL Warehouse.
• DATABRICKS_HTTP_PATH, ustaw na wartość ścieżki HTTP dla klastra lub magazynu SQL.

Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

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),
)

Maszynowe uwierzytelnianie OAuth (M2M)

Sterownik SQL usługi Databricks dla języka Go w wersji 1.5.2 lub nowszej obsługuje uwierzytelnianie między maszynami OAuth (M2M).

Aby użyć sterownika SQL usługi Databricks dla języka Go z uwierzytelnianiem OAuth M2M, należy wykonać następujące czynności:

1. Utwórz wchód główny usługi Azure Databricks w obszarze roboczym Azure Databricks i utwórz tajemnicę OAuth dla tego wchodu głównego.

   Aby utworzyć główną jednostkę usługi i jej tajny klucz OAuth, zobacz Autoryzowanie dostępu głównej jednostki usługi do usługi Azure Databricks przy użyciu protokołu OAuth. Zanotuj wartość UUID lub Identyfikator aplikacji dla jednostki usługowej oraz wartość Tajna jako tajne OAuth dla tej jednostki.

2. Nadaj jednostce usługi dostęp do klastra lub magazynu.

   Aby udzielić jednostce usługi dostępu do klastra lub magazynu, zobacz Uprawnienia dostępu obliczeniowego lub Zarządzaj magazynem SQL.

pl-PL: Aby uwierzytelnić sterownik SQL usługi Databricks dla języka Go przy użyciu ciągu połączenia DSN i przykładu kodu w temacie Nawiązywanie połączenia z użyciem ciągu DSN, użyj następującej składni ciągu połączenia DSN, gdzie:

• <server-hostname> Nazwa hosta serwera to wartość z wymagań.
• <port-number> to wartość Port z wymagań, czyli zazwyczaj 443.
• Wartością ścieżki HTTP z wymagań jest <http-path>.
• <client-id> to wartość UUID lub Identyfikator aplikacji głównej usługi.
• <client-secret> to tajna wartość OAuth dla wpisu tajnego jednostki usługi.

Możesz również dołączyć jeden lub więcej parametrów opcjonalnych wymienionych wcześniej w tym artykule.

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

Aby uwierzytelnić sterownik Databricks SQL dla języka Go za pomocą funkcji NewConnector, najpierw należy dodać następujący kod do deklaracji import:

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

Następnie użyj następującego fragmentu kodu i przykładu kodu w sekcji Connect with the NewConnector function (Połącz z funkcją), która zakłada, że ustawiono następujące zmienne środowiskowe:

• DATABRICKS_SERVER_HOSTNAMEustaw wartość Nazwa hosta serwera dla klastra lub usługi SQL Warehouse.
• DATABRICKS_HTTP_PATH, ustaw wartość Ścieżka HTTP dla klastra lub SQL Warehouse.
• DATABRICKS_CLIENT_ID, przypisz do wartości UUID jednostki głównej usługi lub Identyfikator aplikacji.
• DATABRICKS_CLIENT_SECRET, ustaw wartość tajnego klucza dla tajnego klucza OAuth głównego obiektu usługi.

Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

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),
)

Zapytanie danych

W poniższym przykładzie kodu pokazano, jak wywołać sterownik SQL usługi Databricks dla języka Go, aby uruchomić podstawowe zapytanie SQL w zasobie obliczeniowym usługi Azure Databricks. To polecenie zwraca dwa pierwsze wiersze z tabeli trips w schemacie samples katalogu nyctaxi.

Ten przykładowy kod pobiera parametry połączenia DSN ze zmiennej środowiskowej o nazwie 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)
  }
}

Zarządzanie plikami w woluminach Unity Catalog

Sterownik Databricks SQL umożliwia zapisywanie plików lokalnych w woluminach Unity Catalog, pobieranie plików z woluminów i usuwanie plików z woluminów, jak pokazano w poniższym przykładzie:

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()
}

Rejestrowanie

Użyj github.com/databricks/databricks-sql-go/logger do rejestrowania komunikatów, które emituje sterownik SQL Databricks dla Go. W poniższym przykładzie kodu użyto sql.Open() do utworzenia dojścia bazy danych poprzez ciąg znaków połączenia DSN. Ten przykład kodu pobiera parametry połączenia DSN ze zmiennej środowiskowej o nazwie DATABRICKS_DSN. Wszystkie komunikaty dziennika, które są emitowane na debug poziomie i poniżej, są zapisywane w results.log pliku.

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)
  }
}

Testowanie

Aby przetestować kod, użyj platform testowych Języka Go, takich jak biblioteka standardowa testowania. Aby przetestować kod w symulowanych warunkach bez wywoływania punktów końcowych interfejsu API REST usługi Azure Databricks ani zmiany stanu kont lub obszarów roboczych usługi Azure Databricks, użyj bibliotek do pozorowania dla języka Go, takich jak testfify.

Na przykład, biorąc pod uwagę następujący plik o nazwie helpers.go, zawierający funkcję GetDBWithDSNPAT zwracającą połączenie z obszarem roboczym usługi Azure Databricks, funkcję GetNYCTaxiTrips zwracającą dane z tabeli trips w schemacie samples katalogu nyctaxi, oraz funkcję PrintNYCTaxiTrips, która wyświetla zwrócone dane:

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 ?", 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)
  }
}

I biorąc pod uwagę następujący plik o nazwie main.go, który wywołuje te funkcje:

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)
}

Poniższy plik o nazwie helpers_test.go testuje, czy GetNYCTaxiTrips funkcja zwraca oczekiwaną odpowiedź. Zamiast tworzyć rzeczywiste połączenie z docelowym obszarem roboczym, ten test symuluje obiekt sql.DB. Test wyśmiewa również niektóre dane zgodne ze schematem i wartościami, które znajdują się w rzeczywistych danych. Test zwraca dane próbne za pośrednictwem udawanego połączenia, a następnie sprawdza, czy jedna z wartości wierszy danych próbnych jest zgodna z oczekiwaną wartością.

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)
}

GetNYCTaxiTrips Ponieważ funkcja zawiera instrukcję SELECT i dlatego nie zmienia stanu trips tabeli, pozorowanie nie jest absolutnie wymagane w tym przykładzie. Jednak pozorowanie umożliwia szybkie uruchamianie testów bez oczekiwania na rzeczywiste połączenie z obszarem roboczym. Ponadto wyśmiewanie umożliwia wielokrotne uruchamianie symulowanych testów dla funkcji, które mogą zmienić stan tabeli, takie jak INSERT INTO, UPDATEi DELETE FROM.

Dodatkowe zasoby

• Repozytorium Sql Driver for Go usługi Databricks w witrynie GitHub
• Strona główna pakietu bazy danych/sql
• Przykłady sterownika SQL usługi Databricks dla języka Go na GitHub