Ovladač SQL Databricks pro Go

Ovladač SQL Databricks pro Go je knihovna Go, která umožňuje spouštět příkazy SQL na výpočetních prostředcích Azure Databricks pomocí kódu Go. Tento článek doplňuje ovladač SQL Databricks pro go README, reference k rozhraní API a příklady.

Požadavky

• Vývojový počítač s Go verze 1.20 nebo novější. Pokud chcete vytisknout nainstalovanou verzi Jazyka Go, spusťte příkaz go version. Stáhněte a nainstalujte Go.
• Existující cluster nebo SQL Warehouse.
• Název hostitele serveru, port a cesta HTTP pro existující cluster nebo SQL Warehouse.
  • Získejte tyto hodnoty pro cluster.
  • Získejte tyto hodnoty pro SQL Warehouse.

Začínáme s ovladačem SQL Databricks for Go

1. Na vývojovém počítači s go 1.20 nebo novějším nainstalovaným a již vytvořeným existujícím projektem kódu Go vytvořte go.mod soubor pro sledování závislostí kódu Go spuštěním go mod init příkazu, například:

   go mod init sample
   

2. Spuštěním příkazu zapněte go mod edit -require závislost na balíčku Databricks SQL Driver for Go a nahraďte v1.5.2 nejnovější verzí balíčku Databricks SQL Driver for Go, jak je uvedeno v vydaných verzích:

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

   Soubor go.mod by teď měl vypadat takto:

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

3. V projektu vytvořte soubor kódu Go, který importuje ovladač SQL Databricks pro Go. Následující příklad v souboru s následujícím main.go obsahem obsahuje seznam všech clusterů v pracovním prostoru 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. Spuštěním go mod tidy příkazu přidejte všechny chybějící závislosti modulu:

   go mod tidy
   

   Poznámka:

   Pokud se zobrazí chyba go: warning: "all" matched no packages, zapomněli jste přidat soubor kódu Go, který importuje ovladač SQL Databricks pro Go.

5. Spuštěním go mod vendor příkazu vytvořte kopie všech balíčků potřebných k podpoře sestavení a testů balíčků v main modulu:

   go mod vendor
   

6. Upravte kód podle potřeby a nastavte DATABRICKS_DSN proměnnou prostředí pro ověřování Azure Databricks. Viz také Připojení k připojovací řetězec DSN.

7. Spuštěním příkazu spusťte soubor kódu Go za předpokladugo run, že soubor s názvem main.go:

   go run main.go
   

8. Pokud se nevrátí žádné chyby, úspěšně jste ověřili ovladač SQL Databricks pro Go s pracovním prostorem Azure Databricks a připojili jste se ke spuštěném clusteru Azure Databricks nebo SQL Warehouse v daném pracovním prostoru.

Připojení pomocí připojovací řetězec DSN

Pokud chcete získat přístup ke clusterům a skladům SQL, použijte sql.Open() k vytvoření popisovače databáze prostřednictvím názvu zdroje dat (DSN) připojovací řetězec. Tento příklad kódu načte připojovací řetězec DSN z proměnné prostředí s názvemDATABRICKS_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)
  }
}

Pokud chcete zadat připojovací řetězec DSN ve správném formátu, přečtěte si připojovací řetězec příklady dsN v části Ověřování. Například pro ověřování osobního přístupového tokenu Azure Databricks použijte následující syntaxi, kde:

• <personal-access-token> je váš osobní přístupový token Azure Databricks z požadavků.
• <server-hostname>je hodnota názvu hostitele serveru z požadavků.
• <port-number>je hodnota portu z požadavků, což je obvykle 443.
• <http-path>je hodnota cesty HTTP z požadavků.
• <paramX=valueX> je jeden nebo více volitelných parametrů uvedených dále v tomto článku.

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

Například pro cluster:

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

Například pro SQL Warehouse:

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

Poznámka:

Jako osvědčený postup zabezpečení byste neměli pevně kódovat tento dsN připojovací řetězec do kódu Go. Místo toho byste měli tento dsN načíst připojovací řetězec ze zabezpečeného umístění. Například příklad kódu dříve v tomto článku použil proměnnou prostředí.

Volitelné parametry

• Podporované volitelné parametry připojení lze zadat v <param=value>. Mezi nejčastěji používané patří:
  • catalog: Nastaví počáteční název katalogu v relaci.
  • schema: Nastaví počáteční název schématu v relaci.
  • maxRows: Nastaví maximální počet řádků načtených na požadavek. Výchozí hodnota je 10000.
  • timeout: Přidá časový limit (v sekundách) pro spuštění dotazu serveru. Výchozí hodnota není vypršení časového limitu.
  • userAgentEntry: Slouží k identifikaci partnerů. Další informace najdete v dokumentaci partnera.
• Podporované volitelné parametry relace lze zadat v param=value. Mezi nejčastěji používané patří:
  • ansi_mode: Logický řetězec. true pro příkazy relace, aby dodržovaly pravidla určená specifikací ANSI SQL. Výchozí hodnota systému je false.
  • timezone: Řetězec, například America/Los_Angeles. Nastaví časové pásmo relace. Výchozí hodnota systému je UTC.

Například pro 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

Připojení pomocí NewConnector funkce

Alternativně můžete použít sql.OpenDB() k vytvoření popisovače databáze prostřednictvím nového objektu konektoru vytvořeného pomocí dbsql.NewConnector() (připojení ke clusterům Azure Databricks a skladům SQL s novým objektem konektoru vyžaduje v1.0.0 nebo vyšší ovladač Databricks SQL pro Go). Příklad:

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

Pokud chcete zadat správnou sadu NewConnector nastavení, podívejte se na příklady v části Ověřování.

Poznámka:

Jako osvědčený postup zabezpečení byste neměli pevně zakódovat nastavení NewConnector do kódu Go. Místo toho byste tyto hodnoty měli načíst ze zabezpečeného umístění. Například předchozí kód používá proměnné prostředí.

Mezi často používané funkční možnosti patří:

• WithAccessToken(<access-token>): Osobní přístupový token Azure Databricks z požadavků. Povinné string.
• WithServerHostname(<server-hostname>): Hodnota názvu hostitele serveru z požadavků. Povinné string.
• WithPort(<port>): Číslo portu serveru, obvykle 443. Povinné int.
• WithHTTPPath(<http-path>): Hodnota cesty HTTP z požadavků. Povinné string.
• WithInitialNamespace(<catalog>, <schema>):Název katalogu a schématu v relaci. Volitelnéstring, string.
• WithMaxRows(<max-rows>): Maximální počet řádků načtených na požadavek. Výchozí hodnota je 10000. Nepovinná int.
• WithSessionParams(<params-map>): Parametry relace, včetně "časového pásma" a "ansi_mode". Volitelnémap[string]string.
• WithTimeout(<timeout>). Časový limit (in time.Duration) pro spuštění dotazu serveru. Výchozí hodnota není vypršení časového limitu. Nepovinné.
• WithUserAgentEntry(<isv-name-plus-product-name>). Slouží k identifikaci partnerů. Další informace najdete v dokumentaci partnera. Volitelnéstring.

Příklad:

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

Ověřování

Ovladač SQL Databricks pro Go podporuje následující typy ověřování Azure Databricks:

• Ověřování osobního přístupového tokenu Databricks
• Ověřování tokenu Microsoft Entra ID
• Ověřování uživatele OAuth na počítač (U2M)
• Ověřování OAuth mezi počítači (M2M)

Ovladač SQL Databricks pro Go zatím nepodporuje následující typy ověřování Azure Databricks:

• Ověřování spravovaných identit Azure
• Ověřování instančního objektu MS Entra
• Ověřování přes Azure CLI

Ověřování osobního přístupového tokenu Databricks

Pokud chcete použít ovladač SQL Databricks pro Go s ověřováním osobního přístupového tokenu Azure Databricks, musíte nejprve vytvořit osobní přístupový token Azure Databricks následujícím způsobem:

1. V pracovním prostoru Azure Databricks klikněte na své uživatelské jméno Azure Databricks v horním panelu a pak v rozevíracím seznamu vyberte Nastavení .
2. Klikněte na Vývojář.
3. Vedle přístupových tokenů klikněte na Spravovat.
4. Klikněte na Vygenerovat nový token.
5. (Volitelné) Zadejte komentář, který vám pomůže identifikovat tento token v budoucnu a změnit výchozí životnost tokenu na 90 dnů. Pokud chcete vytvořit token bez životnosti (nedoporučuje se), nechte pole Životnost (dny) prázdné (prázdné).
6. Klikněte na Vygenerovat.
7. Zkopírujte zobrazený token do zabezpečeného umístění a klikněte na tlačítko Hotovo.

Poznámka:

Nezapomeňte zkopírovaný token uložit do zabezpečeného umístění. Nesdílejte svůj zkopírovaný token s ostatními. Pokud ztratíte zkopírovaný token, nemůžete tento úplně stejný token znovu vygenerovat. Místo toho musíte tento postup zopakovat, abyste vytvořili nový token. Pokud ztratíte zkopírovaný token nebo se domníváte, že došlo k ohrožení zabezpečení tokenu, databricks důrazně doporučuje tento token okamžitě odstranit z pracovního prostoru kliknutím na ikonu koše (Odvolat) vedle tokenu na stránce Přístupové tokeny .

Pokud v pracovním prostoru nemůžete vytvářet nebo používat tokeny, může to být proto, že správce pracovního prostoru zakázal tokeny nebo vám neudělil oprávnění k vytváření nebo používání tokenů. Projděte si správce pracovního prostoru nebo následující témata:

• Povolení nebo zakázání ověřování osobního přístupového tokenu pro pracovní prostor
• Oprávnění osobního přístupového tokenu

Pokud chcete ověřit ovladač SQL Databricks pro Go pomocí připojovací řetězec DSN a příklad kódu v příkazu Connect with a DSN připojovací řetězec, použijte následující syntaxi dsN připojovací řetězec, kde:

• <personal-access-token> je váš osobní přístupový token Azure Databricks z požadavků.
• <server-hostname>je hodnota názvu hostitele serveru z požadavků.
• <port-number>je hodnota portu z požadavků, což je obvykle 443.
• <http-path>je hodnota cesty HTTP z požadavků.

Můžete také připojit jeden nebo více volitelných parametrů uvedených dříve v tomto článku.

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

K ověření ovladače SQL Databricks pro Go pomocí NewConnector funkce použijte následující fragment kódu a příklad kódu ve funkci Connect with the NewConnector, která předpokládá, že jste nastavili následující proměnné prostředí:

• DATABRICKS_SERVER_HOSTNAMEna hodnotu Název hostitele serveru pro váš cluster nebo SQL Warehouse.
• DATABRICKS_HTTP_PATH, nastavte hodnotu cesty HTTP pro váš cluster nebo SQL Warehouse.
• DATABRICKS_TOKEN, nastavte na osobní přístupový token Azure Databricks.

Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

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

Ověřování tokenu Microsoft Entra ID

Ovladač SQL Databricks pro Go podporuje tokeny ID Microsoft Entra pro uživatele Azure Databricks nebo instanční objekt Microsoft Entra ID.

Pokud chcete vytvořit přístupový token Microsoft Entra ID, postupujte takto:

• Pro uživatele Azure Databricks můžete použít Azure CLI. Viz Získání tokenů ID Microsoft Entra pro uživatele pomocí Azure CLI.

  • Instanční objekt Microsoft Entra ID najdete v tématu Získání přístupového tokenu Microsoft Entra ID pomocí Azure CLI. Informace o vytvoření spravovaného instančního objektu Microsoft Entra ID najdete v tématu Správa instančních objektů.

  Tokeny MICROSOFT Entra ID mají výchozí životnost přibližně 1 hodinu. Pokud chcete vytvořit nový token ID Microsoft Entra, opakujte tento proces.

  Pokud chcete ověřit ovladač SQL Databricks pro Go pomocí připojovací řetězec DSN a příklad kódu v příkazu Connect with a DSN připojovací řetězec, použijte následující syntaxi dsN připojovací řetězec, kde:

  • <microsoft-entra-id-token> je váš token ID Microsoft Entra.
  • <server-hostname>je hodnota názvu hostitele serveru z požadavků.
  • <port-number>je hodnota portu z požadavků, což je obvykle 443.
  • <http-path>je hodnota cesty HTTP z požadavků.

  Můžete také připojit jeden nebo více volitelných parametrů uvedených dříve v tomto článku.

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

  K ověření ovladače SQL Databricks pro Go pomocí NewConnector funkce použijte následující fragment kódu a příklad kódu ve funkci Connect with the NewConnector, která předpokládá, že jste nastavili následující proměnné prostředí:

  • DATABRICKS_SERVER_HOSTNAMEna hodnotu Název hostitele serveru pro váš cluster nebo SQL Warehouse.
  • DATABRICKS_HTTP_PATH, nastavte hodnotu cesty HTTP pro váš cluster nebo SQL Warehouse.
  • DATABRICKS_TOKEN, nastavte na token Microsoft Entra ID.

  Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

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

Ověřování uživatele OAuth na počítač (U2M)

Ovladač SQL Databricks pro Go verze 1.5.0 a vyšší podporují ověřování uživatele a počítače OAuth (U2M).

Pokud chcete použít ovladač SQL Databricks pro Go s připojovací řetězec DSN a příklad kódu v nástroji Connect with a DSN připojovací řetězec, použijte následující syntaxi DSN připojovací řetězec, kde:

• <server-hostname>je hodnota názvu hostitele serveru z požadavků.
• <port-number>je hodnota portu z požadavků, což je obvykle 443.
• <http-path>je hodnota cesty HTTP z požadavků.

Můžete také připojit jeden nebo více volitelných parametrů uvedených dříve v tomto článku.

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

Pokud chcete ověřit ovladač SQL Databricks pro Go pomocí NewConnector funkce, musíte nejprve do deklarace import přidat následující:

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

Pak použijte následující fragment kódu a příklad kódu ve funkci Connect s funkcí NewConnector, která předpokládá, že jste nastavili následující proměnné prostředí:

• DATABRICKS_SERVER_HOSTNAMEna hodnotu Název hostitele serveru pro váš cluster nebo SQL Warehouse.
• DATABRICKS_HTTP_PATH, nastavte hodnotu cesty HTTP pro váš cluster nebo SQL Warehouse.

Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

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

Ověřování M2M (machine-to-machine) OAuth

Ovladač SQL Databricks pro Go verze 1.5.2 a vyšší podporují ověřování M2M (machine-to-machine) OAuth.

Pokud chcete použít ovladač SQL Databricks pro Go s ověřováním OAuth M2M, musíte udělat toto:

1. V pracovním prostoru Azure Databricks vytvořte instanční objekt Azure Databricks a vytvořte pro tento instanční objekt tajný klíč OAuth.

   Pokud chcete vytvořit instanční objekt a jeho tajný klíč OAuth, přečtěte si téma Ověřování přístupu k Azure Databricks pomocí instančního objektu pomocí OAuth (OAuth M2M). Poznamenejte si hodnotu UUID nebo ID aplikace instančního objektu a hodnotu Secret pro tajný klíč OAuth instančního objektu.

2. Dejte danému instančnímu objektu přístup ke clusteru nebo skladu.

   Pokud chcete instančnímu objektu udělit přístup ke clusteru nebo skladu, přečtěte si informace o oprávněních výpočetních prostředků nebo správě služby SQL Warehouse.

Pokud chcete ověřit ovladač SQL Databricks pro Go pomocí připojovací řetězec DSN a příklad kódu v příkazu Connect with a DSN připojovací řetězec, použijte následující syntaxi dsN připojovací řetězec, kde:

• <server-hostname>je hodnota názvu hostitele serveru z požadavků.
• <port-number>je hodnota portu z požadavků, což je obvykle 443.
• <http-path>je hodnota cesty HTTP z požadavků.
• <client-id>je hodnota UUID nebo ID aplikace instančního objektu.
• <client-secret>je hodnota Secret pro tajný klíč OAuth instančního objektu.

Můžete také připojit jeden nebo více volitelných parametrů uvedených dříve v tomto článku.

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

Pokud chcete ověřit ovladač SQL Databricks pro Go pomocí NewConnector funkce, musíte nejprve do deklarace import přidat následující:

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

Pak použijte následující fragment kódu a příklad kódu ve funkci Connect s funkcí NewConnector, která předpokládá, že jste nastavili následující proměnné prostředí:

• DATABRICKS_SERVER_HOSTNAMEna hodnotu Název hostitele serveru pro váš cluster nebo SQL Warehouse.
• DATABRICKS_HTTP_PATH, nastavte hodnotu cesty HTTP pro váš cluster nebo SQL Warehouse.
• DATABRICKS_CLIENT_ID, nastavte na hodnotu UUID nebo ID aplikace instančního objektu.
• DATABRICKS_CLIENT_SECRET, nastavte na hodnotu Secret pro tajný klíč OAuth instančního objektu.

Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

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

Zadávání dotazů na data

Následující příklad kódu ukazuje, jak volat ovladač SQL Databricks pro Go ke spuštění základního dotazu SQL na výpočetní prostředek Azure Databricks. Tento příkaz vrátí první dva řádky z trips tabulky ve schématu samples katalogu nyctaxi .

Tento příklad kódu načte dsN připojovací řetězec z proměnné prostředí s názvem 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)
  }
}

Správa souborů ve svazcích katalogu Unity

Ovladač SQL Databricks umožňuje zapisovat místní soubory do svazků katalogu Unity, stahovat soubory ze svazků a odstraňovat soubory ze svazků, jak je znázorněno v následujícím příkladu:

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

Protokolování

Slouží github.com/databricks/databricks-sql-go/logger k protokolování zpráv, které generuje ovladač SQL Databricks for Go. Následující příklad kódu používá sql.Open() k vytvoření popisovače databáze prostřednictvím dsN připojovací řetězec. Tento příklad kódu načte připojovací řetězec DSN z proměnné prostředí s názvem DATABRICKS_DSN. Všechny zprávy protokolu, které se vygenerují na debug úrovni a níže, se zapíšou results.log do souboru.

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

Testování

K otestování kódu použijte testovací architektury Go, jako je testovací standardní knihovna. K otestování kódu za simulovaných podmínek bez volání koncových bodů rozhraní REST API služby Azure Databricks nebo změny stavu účtů nebo pracovních prostorů Azure Databricks použijte knihovny napodobení Go, jako je testfify.

Například vzhledem k následujícímu souboru s názvem helpers.go obsahujícím GetDBWithDSNPAT funkci, která vrací připojení pracovního prostoru Azure Databricks, GetNYCTaxiTrips vrátí funkce, která vrací data z trips tabulky ve schématu samples katalogu nyctaxi a PrintNYCTaxiTrips která vytiskne vrácená data:

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

A vzhledem k následujícímu souboru, main.go který volá tyto funkce:

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

Následující soubor s názvem helpers_test.go testuje, zda GetNYCTaxiTrips funkce vrátí očekávanou odpověď. Místo vytvoření skutečného připojení k cílovému pracovnímu prostoru tento test napodobí sql.DB objekt. Test také napodobí některá data, která odpovídají schématu a hodnotám, které jsou ve skutečných datech. Test vrátí napodobená data prostřednictvím napodobeného připojení a pak zkontroluje, jestli jedna z hodnot napodobených řádků dat odpovídá očekávané hodnotě.

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

Vzhledem k tomu, že GetNYCTaxiTrips funkce obsahuje SELECT příkaz, a proto nemění stav trips tabulky, není v tomto příkladu napodobování zcela vyžadováno. Napodobování ale umožňuje rychle spouštět testy bez čekání na skutečné připojení k pracovnímu prostoru. Také napodobení umožňuje spustit simulované testy vícekrát pro funkce, které mohou změnit stav tabulky, například INSERT INTO, UPDATEa DELETE FROM.

Další materiály

• Úložiště Databricks SQL Driver for Go na GitHubu
• Domovská stránka databáze nebo balíčku SQL
• Příklady ovladače SQL Databricks pro Go na GitHubu