Databricks SQL-drivrutin för Go

Databricks SQL Driver for Go är ett Go-bibliotek som gör att du kan använda Go-kod för att köra SQL-kommandon på Azure Databricks-beräkningsresurser. Den här artikeln kompletterar Databricks SQL-drivrutinen för Go README, API-referens och exempel.

Krav

Komma igång med Databricks SQL Driver for Go

  1. På utvecklingsdatorn med Go 1.20 eller senare redan installerat och ett befintligt Go-kodprojekt som redan har skapats skapar du en go.mod fil för att spåra Go-kodens beroenden genom att köra go mod init kommandot, till exempel:

    go mod init sample
    
  2. Ta ett beroende av Databricks SQL Driver for Go-paketet genom att köra go mod edit -require kommandot och ersätta v1.5.2 med den senaste versionen av Databricks SQL Driver for Go-paketet enligt beskrivningen i versionerna:

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

    Filen go.mod bör nu se ut så här:

    module sample
    
    go 1.20
    
    require github.com/databricks/databricks-sql-go v1.5.2
    
  3. I projektet skapar du en Go-kodfil som importerar Databricks SQL-drivrutinen för Go. I följande exempel, i en fil med namnet main.go med följande innehåll, visas alla kluster på din Azure Databricks-arbetsyta:

    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. Lägg till eventuella modulberoenden som saknas genom att go mod tidy köra kommandot:

    go mod tidy
    

    Kommentar

    Om du får felet go: warning: "all" matched no packageshar du glömt att lägga till en Go-kodfil som importerar Databricks SQL-drivrutinen för Go.

  5. Gör kopior av alla paket som behövs för att stödja versioner och tester av paket i modulen main genom att go mod vendor köra kommandot:

    go mod vendor
    
  6. Ändra koden efter behov för att ange DATABRICKS_DSN miljövariabeln för Azure Databricks-autentisering. Se även Anslut med en DSN-anslutningssträng.

  7. Kör din Go-kodfil, förutsatt att en fil med namnet main.go, genom att go run köra kommandot:

    go run main.go
    
  8. Om inga fel returneras har du autentiserat Databricks SQL Driver for Go med din Azure Databricks-arbetsyta och anslutit till ditt Azure Databricks-kluster eller SQL-lager som körs på den arbetsytan.

Anslut med en DSN-anslutningssträng

Om du vill komma åt kluster och SQL-lager använder du sql.Open() för att skapa en databasreferens via ett DSN-anslutningssträng. Det här kodexemplet hämtar DSN-anslutningssträng från en miljövariabel med namnet 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)
  }
}

Information om hur du anger DSN-anslutningssträng i rätt format finns i DSN-anslutningssträng exempel i Autentisering. För personlig åtkomsttokenautentisering i Azure Databricks använder du till exempel följande syntax, där:

  • <personal-access-token> är din personliga åtkomsttoken för Azure Databricks från kraven.
  • <server-hostname> är värdet servervärdnamn från kraven.
  • <port-number>är portvärdet från kraven, vilket vanligtvis 443är .
  • <http-path> är värdet för HTTP-sökvägen från kraven.
  • <paramX=valueX> är en eller flera valfria parametrar som anges senare i den här artikeln.
token:<personal-access-token>@<server-hostname>:<port-number>/<http-path>?<param1=value1>&<param2=value2>

Till exempel för ett kluster:

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

Till exempel för ett SQL-lager:

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

Kommentar

Som bästa säkerhet bör du inte hårdkoda den här DSN-anslutningssträng i Din Go-kod. I stället bör du hämta DSN-anslutningssträng från en säker plats. Kodexemplet tidigare i den här artikeln använde till exempel en miljövariabel.

Valfria parametrar

  • Valfria anslutningsparametrar som stöds kan anges i <param=value>. Några av de vanligaste är:
    • catalog: Anger det första katalognamnet i sessionen.
    • schema: Anger det första schemanamnet i sessionen.
    • maxRows: Konfigurerar det maximala antalet rader som hämtas per begäran. Standardvärdet är 10000.
    • timeout: Lägger till tidsgränsen (i sekunder) för serverfrågekörningen. Standardvärdet är ingen tidsgräns.
    • userAgentEntry: Används för att identifiera partner. Mer information finns i din partners dokumentation.
  • Valfria sessionsparametrar som stöds kan anges i param=value. Några av de vanligaste är:
    • ansi_mode: En boolesk sträng. true för sessionsinstruktioner för att följa regler som anges i ANSI SQL-specifikationen. Systemstandarden är false.
    • timezone: En sträng, till exempel America/Los_Angeles. Anger tidszonen för sessionen. Systemstandarden är UTC.

Till exempel för ett SQL-lager:

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

Anslut med NewConnector funktionen

Du kan också använda sql.OpenDB() för att skapa en databasreferens via ett nytt anslutningsobjekt som skapas med dbsql.NewConnector() (anslutning till Azure Databricks-kluster och SQL-lager med ett nytt anslutningsobjekt kräver v1.0.0 eller senare av Databricks SQL Driver for Go). Till exempel:

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

Information om hur du anger rätt uppsättning NewConnector inställningar finns i exemplen i Autentisering.

Kommentar

Som bästa säkerhet bör du inte hårdkoda NewConnector inställningarna i Go-koden. I stället bör du hämta dessa värden från en säker plats. I föregående kod används till exempel miljövariabler.

Några av de mer använda funktionsalternativen är:

  • WithAccessToken(<access-token>): Din personliga Åtkomsttoken för Azure Databricks från kraven. Krävs string.
  • WithServerHostname(<server-hostname>): Värdet servervärdnamn från kraven. Krävs string.
  • WithPort(<port>): Serverns portnummer, vanligtvis 443. Krävs int.
  • WithHTTPPath(<http-path>): VÄRDET FÖR HTTP-sökväg från kraven. Krävs string.
  • WithInitialNamespace(<catalog>, <schema>):Katalog- och schemanamnet i sessionen. Valfrittstring, string.
  • WithMaxRows(<max-rows>): Det maximala antalet rader som hämtas per begäran. Standardvärdet är 10000. Valfritt int.
  • WithSessionParams(<params-map>): Sessionsparametrarna inklusive "tidszon" och "ansi_mode". Valfrittmap[string]string.
  • WithTimeout(<timeout>). Tidsgränsen (i time.Duration) för serverfrågekörningen. Standardvärdet är ingen tidsgräns. Valfritt.
  • WithUserAgentEntry(<isv-name-plus-product-name>). Används för att identifiera partner. Mer information finns i din partners dokumentation. Valfrittstring.

Till exempel:

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

Autentisering

Databricks SQL Driver for Go stöder följande Azure Databricks-autentiseringstyper:

Databricks SQL Driver for Go stöder ännu inte följande Azure Databricks-autentiseringstyper:

Autentisering med personlig åtkomsttoken för Databricks

Om du vill använda Databricks SQL Driver for Go med personlig åtkomsttokenautentisering i Azure Databricks måste du först skapa en personlig åtkomsttoken för Azure Databricks enligt följande:

  1. I din Azure Databricks-arbetsyta klickar du på ditt Användarnamn för Azure Databricks i det övre fältet och väljer sedan Inställningar i listrutan.
  2. Klicka på Utvecklare.
  3. Bredvid Åtkomsttoken klickar du på Hantera.
  4. Klicka på Generera ny token.
  5. (Valfritt) Ange en kommentar som hjälper dig att identifiera den här token i framtiden och ändra tokens standardlivslängd på 90 dagar. Om du vill skapa en token utan livslängd (rekommenderas inte) lämnar du rutan Livslängd (dagar) tom (tom).
  6. Klicka på Generera.
  7. Kopiera den visade token till en säker plats och klicka sedan på Klar.

Kommentar

Se till att spara den kopierade token på en säker plats. Dela inte din kopierade token med andra. Om du förlorar den kopierade token kan du inte återskapa exakt samma token. I stället måste du upprepa den här proceduren för att skapa en ny token. Om du förlorar den kopierade token eller om du tror att token har komprometterats rekommenderar Databricks starkt att du omedelbart tar bort den token från arbetsytan genom att klicka på papperskorgsikonen (Återkalla) bredvid token på sidan Åtkomsttoken .

Om du inte kan skapa eller använda token på din arbetsyta kan det bero på att arbetsyteadministratören har inaktiverat token eller inte har gett dig behörighet att skapa eller använda token. Se din arbetsyteadministratör eller följande:

Om du vill autentisera Databricks SQL Driver for Go med en DSN-anslutningssträng och kodexemplet i Anslut med en DSN-anslutningssträng använder du följande DSN-anslutningssträng syntax, där:

  • <personal-access-token> är din personliga åtkomsttoken för Azure Databricks från kraven.
  • <server-hostname> är värdet servervärdnamn från kraven.
  • <port-number>är portvärdet från kraven, vilket vanligtvis 443är .
  • <http-path> är värdet för HTTP-sökvägen från kraven.

Du kan också lägga till en eller flera valfria parametrar som anges tidigare i den här artikeln.

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

Om du vill autentisera Databricks SQL Driver for Go med NewConnector funktionen använder du följande kodfragment och kodexemplet i Anslut med funktionen New Anslut or, som förutsätter att du har angett följande miljövariabler:

  • DATABRICKS_SERVER_HOSTNAMEange värdet servervärdnamn för klustret eller SQL-lagret.
  • DATABRICKS_HTTP_PATHanger du till HTTP-sökvägsvärde för klustret eller SQL-lagret.
  • DATABRICKS_TOKEN, inställt på den personliga åtkomsttoken för Azure Databricks.

Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

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

Tokenautentisering för Microsoft Entra-ID (tidigare Azure Active Directory)

Databricks SQL Driver for Go stöder Microsoft Entra ID-token (tidigare Azure Active Directory) för en Azure Databricks-användare eller ett Microsoft Entra ID-tjänsthuvudnamn.

Gör följande för att skapa en Microsoft Entra ID-åtkomsttoken:

  • För en Azure Databricks-användare kan du använda Azure CLI. Se Hämta Microsoft Entra-ID-token (tidigare Azure Active Directory) för användare med hjälp av Azure CLI.

    Microsoft Entra-ID-token har en standardlivslängd på cirka 1 timme. Om du vill skapa en ny Microsoft Entra-ID-token upprepar du den här processen.

    Om du vill autentisera Databricks SQL Driver for Go med en DSN-anslutningssträng och kodexemplet i Anslut med en DSN-anslutningssträng använder du följande DSN-anslutningssträng syntax, där:

    • <microsoft-entra-id-token> är din Microsoft Entra ID-token.
    • <server-hostname> är värdet servervärdnamn från kraven.
    • <port-number>är portvärdet från kraven, vilket vanligtvis 443är .
    • <http-path> är värdet för HTTP-sökvägen från kraven.

    Du kan också lägga till en eller flera valfria parametrar som anges tidigare i den här artikeln.

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

    Om du vill autentisera Databricks SQL Driver for Go med NewConnector funktionen använder du följande kodfragment och kodexemplet i Anslut med funktionen New Anslut or, som förutsätter att du har angett följande miljövariabler:

    • DATABRICKS_SERVER_HOSTNAMEange värdet servervärdnamn för klustret eller SQL-lagret.
    • DATABRICKS_HTTP_PATHanger du till HTTP-sökvägsvärde för klustret eller SQL-lagret.
    • DATABRICKS_TOKEN, ange till din Microsoft Entra-ID-token.

    Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

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

OAuth-autentisering från användare till dator (U2M)

Databricks SQL Driver for Go version 1.5.0 och senare stöder OAuth-autentisering från användare till dator (U2M).

Om du vill använda Databricks SQL Driver for Go med en DSN-anslutningssträng och kodexemplet i Anslut med en DSN-anslutningssträng använder du följande DSN-anslutningssträng syntax, där:

  • <server-hostname> är värdet servervärdnamn från kraven.

    • <port-number>är portvärdet från kraven, vilket vanligtvis 443är .
    • <http-path> är värdet för HTTP-sökvägen från kraven.

    Du kan också lägga till en eller flera valfria parametrar som anges tidigare i den här artikeln.

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

    Om du vill autentisera Databricks SQL Driver for Go med NewConnector funktionen måste du först lägga till följande i import deklarationen:

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

    Använd sedan följande kodfragment och kodexemplet i Anslut med funktionen New Anslut or, som förutsätter att du har angett följande miljövariabler:

    • DATABRICKS_SERVER_HOSTNAMEange värdet servervärdnamn för klustret eller SQL-lagret.
    • DATABRICKS_HTTP_PATHanger du till HTTP-sökvägsvärde för klustret eller SQL-lagret.

    Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

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

OAuth-autentisering från dator till dator (M2M)

Databricks SQL Driver för Go-versionerna 1.5.2 och senare stöder OAuth-autentisering från dator till dator (M2M).

Om du vill använda Databricks SQL Driver for Go med OAuth M2M-autentisering följer du installationsstegen i M2M-autentisering (machine-to-machine).

Om du vill autentisera Databricks SQL Driver for Go med en DSN-anslutningssträng och kodexemplet i Anslut med en DSN-anslutningssträng använder du följande DSN-anslutningssträng syntax, där:

  • <server-hostname> är värdet servervärdnamn från kraven.

    • <port-number>är portvärdet från kraven, vilket vanligtvis 443är .
    • <http-path> är värdet för HTTP-sökvägen från kraven.
    • <client-id> är tjänstens huvudnamns program-ID-värde (klient).
    • <client-secret>är hemlighetsvärdet för tjänstens huvudnamns OAuth-hemlighet. (Microsoft Entra ID-hemligheter stöds inte för OAuth M2M-autentisering.)

    Du kan också lägga till en eller flera valfria parametrar som anges tidigare i den här artikeln.

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

    Om du vill autentisera Databricks SQL Driver for Go med NewConnector funktionen måste du först lägga till följande i import deklarationen:

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

    Använd sedan följande kodfragment och kodexemplet i Anslut med funktionen New Anslut or, som förutsätter att du har angett följande miljövariabler:

    • DATABRICKS_SERVER_HOSTNAMEange värdet servervärdnamn för klustret eller SQL-lagret.
    • DATABRICKS_HTTP_PATHanger du till HTTP-sökvägsvärde för klustret eller SQL-lagret.
    • DATABRICKS_CLIENT_ID, inställt på tjänstens huvudnamns program-ID (klient)-värde.
    • DATABRICKS_CLIENT_SECRET, ange värdet Hemlig för tjänstens huvudnamns OAuth-hemlighet. (Microsoft Entra ID-hemligheter stöds inte för OAuth M2M-autentisering.)

    Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

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

Fråga efter data

Följande kodexempel visar hur du anropar Databricks SQL Driver for Go för att köra en grundläggande SQL-fråga på en Azure Databricks-beräkningsresurs. Det här kommandot returnerar de två första raderna trips från tabellen i samples katalogens nyctaxi schema.

Det här kodexemplet hämtar DSN-anslutningssträng från en miljövariabel med namnet 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)
  }
}

Utdata:

tpep_pickup_datetime,tpep_dropoff_datetime,trip_distance,fare_amount,pickup_zip,dropoff_zip
2016-02-14 16:52:13 +0000 UTC,2016-02-14 17:16:04 +0000 UTC,4.94,19,10282,10171
2016-02-04 18:44:19 +0000 UTC,2016-02-04 18:46:00 +0000 UTC,0.28,3.5,10110,10110

Ytterligare exempel finns i exempelmappen i databricks/databricks-sql-go-lagringsplatsen på GitHub.

Loggning

Används github.com/databricks/databricks-sql-go/logger för att logga meddelanden som Databricks SQL Driver for Go genererar. I följande kodexempel används sql.Open() för att skapa en databasreferens via en DSN-anslutningssträng. Det här kodexemplet hämtar DSN-anslutningssträng från en miljövariabel med namnet DATABRICKS_DSN. Alla loggmeddelanden som genereras på debug nivån och nedan skrivs results.log till filen.

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

Ytterligare resurser