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
- En utvecklingsdator som kör Go version 1.20 eller senare. Om du vill skriva ut den installerade versionen av Go kör du kommandot
go version
. Ladda ned och installera Go. - Ett befintligt kluster eller SQL-lager.
- Värden för servervärdnamn, port och HTTP-sökväg för det befintliga klustret eller SQL-lagret.
Komma igång med Databricks SQL Driver for Go
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örago mod init
kommandot, till exempel:go mod init sample
Ta ett beroende av Databricks SQL Driver for Go-paketet genom att köra
go mod edit -require
kommandot och ersättav1.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
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) } }
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 packages
har du glömt att lägga till en Go-kodfil som importerar Databricks SQL-drivrutinen för Go.Gör kopior av alla paket som behövs för att stödja versioner och tester av paket i modulen
main
genom attgo mod vendor
köra kommandot:go mod vendor
Ä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.Kör din Go-kodfil, förutsatt att en fil med namnet
main.go
, genom attgo run
köra kommandot:go run main.go
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 vanligtvis443
ä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 är10000
.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 exempelAmerica/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ävsstring
.WithServerHostname(<server-hostname>)
: Värdet servervärdnamn från kraven. Krävsstring
.WithPort(<port>)
: Serverns portnummer, vanligtvis443
. Krävsint
.WithHTTPPath(<http-path>)
: VÄRDET FÖR HTTP-sökväg från kraven. Krävsstring
.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 är10000.
Valfrittint
.WithSessionParams(<params-map>)
: Sessionsparametrarna inklusive "tidszon" och "ansi_mode". Valfrittmap[string]string
.WithTimeout(<timeout>)
. Tidsgränsen (itime.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:
- Autentisering med personlig åtkomsttoken för Databricks
- Tokenautentisering för Microsoft Entra-ID (tidigare Azure Active Directory)
- OAuth-autentisering från användare till dator (U2M)
- OAuth-autentisering från dator till dator (M2M)
Databricks SQL Driver for Go stöder ännu inte följande Azure Databricks-autentiseringstyper:
- Azure-hanterad identitetsautentisering
- Autentisering med tjänstens huvudnamn i Microsoft Entra ID
- Azure CLI-autentisering
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:
- 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.
- Klicka på Utvecklare.
- Bredvid Åtkomsttoken klickar du på Hantera.
- Klicka på Generera ny token.
- (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).
- Klicka på Generera.
- 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 vanligtvis443
ä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_HOSTNAME
ange värdet servervärdnamn för klustret eller SQL-lagret.DATABRICKS_HTTP_PATH
anger 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.
- Ett microsoft entra-ID-tjänsthuvudnamn finns i Hämta en Microsoft Entra ID-åtkomsttoken med Azure CLI. Information om hur du skapar ett microsoft entra-ID för hanterad tjänsthuvudnamn finns i Hantera tjänstens huvudnamn.
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 vanligtvis443
ä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_HOSTNAME
ange värdet servervärdnamn för klustret eller SQL-lagret.DATABRICKS_HTTP_PATH
anger 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 vanligtvis443
ä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 iimport
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_HOSTNAME
ange värdet servervärdnamn för klustret eller SQL-lagret.DATABRICKS_HTTP_PATH
anger 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 vanligtvis443
ä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 iimport
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_HOSTNAME
ange värdet servervärdnamn för klustret eller SQL-lagret.DATABRICKS_HTTP_PATH
anger 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
- Databricks SQL Driver for Go-lagringsplatsen på GitHub
- Startsidan för databas-/sql-paket
- Databricks SQL Driver for Go-exempel på GitHub