Sterownik Microsoft go-mssqldb dla SQL Server

Sterownik go-mssqldb jest oficjalnym sterownikiem Microsoft Go dla Microsoft SQL. To czysta implementacja Go protokołu TDS (Tabular Data Stream), która korzysta ze standardowego database/sql interfejsu. Nie wymaga ODBC ani innych bibliotek C.

Sterownik łączy aplikacje Go ze wszystkimi obsługiwanymi wersjami SQL Server, Azure SQL Database, Azure SQL Managed Instance, bazą danych SQL w Fabric, Fabric Data Warehouse oraz Azure Synapse Analytics na Windows, Linux i macOS.

Wybieranie punktu początkowego

• Aby szybko uruchomić lokalną przykładową instancję programu SQL Server w systemie Windows, zacznij od Quickstart: Connect and query.
• Aby połączyć się z usługą Azure SQL przy użyciu uwierzytelniania bezhasłowego, zacznij od Azure SQL Database i uwierzytelniania Microsoft Entra ID.
• Aby przeprowadzić migrację z PostgreSQL lub MySQL, zacznij od sekcji Migracja z innych sterowników.
• Aby efektywnie przenosić duże ilości danych, przejdź do Operacji masowych lub parametrów tabelowych.
• Aby rozwiązać problemy z TLS, certyfikatami lub logowaniem, przejdź do Szyfrowanie i certyfikaty oraz Rozwiązywanie problemów.

Plan bazowy produkcji dla Azure SQL

Użyj tego przykładu jako punktu wyjścia do produkcyjnego połączenia Azure SQL. Łączy tożsamość zarządzaną, jawne ustawienia TLS, ustawienia ograniczeń puli, limity czasu dla poszczególnych żądań, logikę ponawiania prób dla błędów przejściowych z losowym rozproszeniem opóźnień oraz strukturalne logowanie.

package main

import (
	"context"
	"database/sql"
	"errors"
	"fmt"
	"log/slog"
	"math/rand"
	"net/url"
	"os"
	"time"

	mssql "github.com/microsoft/go-mssqldb"
	_ "github.com/microsoft/go-mssqldb/azuread"
)

const (
	maxAttempts    = 4
	baseBackoff    = 200 * time.Millisecond
	maxBackoff     = 3 * time.Second
	queryTimeout   = 2 * time.Second
	startupTimeoutDefault = 30 * time.Second
)

func main() {
	baseLogger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
		Level: slog.LevelInfo,
	}))

	server, ok := getenvRequired("SQL_SERVER")
	if !ok {
		baseLogger.Error("invalid configuration", "error", "missing SQL_SERVER")
		os.Exit(1)
	}

	database, ok := getenvRequired("SQL_DATABASE")
	if !ok {
		baseLogger.Error("invalid configuration", "error", "missing SQL_DATABASE")
		os.Exit(1)
	}

	fedAuth := getenvOrDefault("SQL_FEDAUTH", "ActiveDirectoryManagedIdentity")
	appName := getenvOrDefault("SQL_APP_NAME", "go-mssqldb-example")
	startupTimeout := getenvDurationOrDefault("SQL_STARTUP_TIMEOUT", startupTimeoutDefault)
	logger := baseLogger.With(
		slog.String("server", server),
		slog.String("database", database),
		slog.String("fedauth", fedAuth),
		slog.String("appName", appName),
	)

	connString := buildConnString(server, database, appName, fedAuth)

	db, err := sql.Open("azuresql", connString)
	if err != nil {
		logger.Error("open database", "error", err)
		os.Exit(1)
	}
	defer db.Close()

	db.SetMaxOpenConns(20)
	db.SetMaxIdleConns(10)
	db.SetConnMaxIdleTime(2 * time.Minute)
	db.SetConnMaxLifetime(5 * time.Minute)

	rootCtx := context.Background()

	startupCtx, cancel := context.WithTimeout(rootCtx, startupTimeout)
	defer cancel()
	err = withRetry(startupCtx, logger, func(ctx context.Context) error {
		return db.PingContext(ctx)
	})
	if err != nil {
		logger.Error("ping database", "error", err)
		os.Exit(1)
	}

	var databaseName string
	err = withRetry(rootCtx, logger, func(ctx context.Context) error {
		queryCtx, cancel := context.WithTimeout(ctx, queryTimeout)
		defer cancel()

		return db.QueryRowContext(queryCtx, "SELECT DB_NAME()").Scan(&databaseName)
	})
	if err != nil {
		logger.Error("query database", "error", err)
		os.Exit(1)
	}

	logger.Info("database ready", "database", databaseName)
}

func withRetry(ctx context.Context, logger *slog.Logger, fn func(context.Context) error) error {
	var lastErr error

	for attempt := 1; attempt <= maxAttempts; attempt++ {
		lastErr = fn(ctx)
		if lastErr == nil {
			return nil
		}

		if !isTransient(lastErr) || attempt == maxAttempts {
			return lastErr
		}

		delay := backoffWithJitter(baseBackoff, maxBackoff, attempt)
		logger.WarnContext(ctx, "transient SQL error; retrying",
			"attempt", attempt,
			"delay", delay.String(),
			"error", lastErr,
		)

		timer := time.NewTimer(delay)
		select {
		case <-ctx.Done():
			timer.Stop()
			return ctx.Err()
		case <-timer.C:
		}
	}

	return lastErr
}

func backoffWithJitter(baseDelay, maxDelay time.Duration, attempt int) time.Duration {
	delay := baseDelay * time.Duration(1<<(attempt-1))
	if delay > maxDelay {
		delay = maxDelay
	}

	jitterFraction := 0.20
	multiplier := (1 - jitterFraction) + rand.Float64()*(2*jitterFraction)
	return time.Duration(float64(delay) * multiplier)
}

func buildConnString(server, database, appName, fedAuth string) string {
	query := url.Values{
		"database":               []string{database},
		"fedauth":                []string{fedAuth},
		"encrypt":                []string{"true"},
		"TrustServerCertificate": []string{"false"},
		"app name":               []string{appName},
		"log":                    []string{"1"},
	}

	return fmt.Sprintf("sqlserver://%s?%s", server, query.Encode())
}

func getenvRequired(key string) (string, bool) {
	value := os.Getenv(key)
	if value == "" {
		return "", false
	}
	return value, true
}

func getenvOrDefault(key, defaultValue string) string {
	value, ok := getenvRequired(key)
	if !ok {
		return defaultValue
	}
	return value
}

func getenvDurationOrDefault(key string, defaultValue time.Duration) time.Duration {
	value := os.Getenv(key)
	if value == "" {
		return defaultValue
	}

	parsed, err := time.ParseDuration(value)
	if err != nil {
		return defaultValue
	}

	return parsed
}

func isTransient(err error) bool {
	var sqlErr mssql.Error
	if !errors.As(err, &sqlErr) {
		return false
	}

	switch sqlErr.Number {
	case
		// Connection-establishment and transport transient errors.
		64, 233, 4060, 4221,
		10053, 10054,
		10928, 10929,

		// Azure SQL failover, throttling, and availability errors.
		40020, 40143, 40166,
		40197, 40501, 40540, 40613,
		42108, 42109,
		49918, 49919, 49920,

		// Common retryable statement-level contention errors.
		1205, 1222:
		return true
	default:
		return false
	}
}

Ten przykład wymaga zmiennych środowiskowych SQL_SERVER i SQL_DATABASE.

Opcjonalne zmienne środowiskowe:

• SQL_FEDAUTH (domyślnie: ActiveDirectoryManagedIdentity)
• SQL_APP_NAME (domyślnie: go-mssqldb-example)
• SQL_STARTUP_TIMEOUT (domyślnie: 30s, analizowane przy użyciu time.ParseDuration)

Więcej informacji o każdej części tego przykładu można znaleźć w Azure SQL Database, puli połączeń, obsłudze błędów i wzorcach powtórek oraz logowaniu i diagnoscie.

Kluczowe funkcje

• Pure Go: Nie wymaga CGo ani zewnętrznych zależności C.
• Trzy formaty parametry połączenia: URL (sqlserver://), ADO (key=value) oraz ODBC (odbc:key=value).
• Uwierzytelnianie Microsoft Entra ID: Wiele typów poświadczeń dostępnych za pośrednictwem pakietu azuread, w tym tożsamość zarządzana, jednostka usługi i tożsamość obciążenia roboczego.
• SQL Server i Windows authentication: Obsługuje uwierzytelnianie SQL, NTLM, Kerberos oraz jednorazowe logowanie (SSO) na Windows.
• Zawsze szyfrowane: szyfrowanie po stronie klienta z lokalnym certyfikatem, dostawcami kluczy Windows Certificate Store oraz Azure Key Vault.
• Kopia masowa: Wysokowydajne operacje masowego wstawiania.
• Parametry o wartości tabelarycznej (TVP): Przekazuj dane strukturyzowane do procedur przechowywanych.
• Wiele protokołów: TCP, potoki nazwane, pamięć współdzielona i dedykowane połączenie administratora (DAC).
• Szyfrowanie TDS 8.0: szyfrowanie end-to-end w trybie ścisłym.

Wprowadzenie

Konfigurowanie połączeń

Praca z danymi

Wdrażanie i obsługa

Przewodniki po platformach i protokołach

Prośba o funkcję

Aby zażądać funkcji, otwórz problem w repozytorium go-mssqldb GitHub.

Treści powiązane

• go-mssqldb Ograniczenia
• Co nowego w go-mssqldb
• Wsparcie i cykl życia go-mssqldb
• go-mssqldb na GitHub
• Dokumentacja API go-mssqldb w serwisie pkg.go.dev
• moduły połączeń dla usługi Microsoft SQL Database
• Szybki start: wykonywanie zapytań względem bazy danych w usłudze Azure SQL Database lub Azure SQL Managed Instance za pomocą języka Golang