driver go-mssqldb di Microsoft per SQL Server

Il go-mssqldb driver è il driver ufficiale di Microsoft Go per Microsoft SQL. È un'implementazione puramente Go del protocollo TDS (Tabular Data Stream) che utilizza l'interfaccia standard database/sql . Non richiede ODBC né altre librerie C.

Il driver collega le applicazioni Go a tutte le versioni supportate di SQL Server, database SQL di Azure, Istanza gestita di SQL di Azure, SQL in Fabric, Fabric Data Warehouse e Azure Synapse Analytics su Windows, Linux e macOS.

Scegliere il punto di partenza

• Per far funzionare rapidamente un esempio locale di SQL Server su Windows, inizia con Quickstart: Connetti e interroga.
• Per connetterti ad Azure SQL con autenticazione senza password, inizia con database SQL di Azure e l'autenticazione Microsoft Entra ID.
• Per migrare da PostgreSQL o MySQL, inizia da Migrazione da altri driver.
• Per spostare grandi volumi di dati in modo efficiente, vai a Operazioni in blocco o Parametri a valori di tabella.
• Per risolvere problemi di TLS, certificati o login, vai su Crittografia e certificati e Risoluzione dei problemi.

Baseline di produzione per Azure SQL

Usa questo esempio come punto di partenza per una connessione Azure SQL orientata alla produzione. Combina identità gestita, impostazioni TLS esplicite, impostazioni del pool con limiti definiti, timeout definiti per richiesta, logica di ritentativi transitori con jitter e logging strutturato.

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

Questo esempio richiede le variabili di ambiente SQL_SERVER e SQL_DATABASE.

Variabili ambientali opzionali:

• SQL_FEDAUTH (predefinito: ActiveDirectoryManagedIdentity)
• SQL_APP_NAME (predefinito: go-mssqldb-example)
• SQL_STARTUP_TIMEOUT (predefinito: 30s, analizzato con time.ParseDuration)

Per ulteriori informazioni su ciascuna parte di questo esempio, consulta database SQL di Azure, pooling delle connessioni, gestione degli errori e modelli di ripetizione dei tentativi e registrazione e diagnostica.

Funzionalità principali

• Pure Go: Non richiede CGo né dipendenze esterne in C.
• Tre formati di stringa di connessione: URL (sqlserver://), ADO (key=value) e ODBC (odbc:key=value).
• Autenticazione di Microsoft Entra ID: Più tipi di credenziali tramite il pacchetto azuread, tra cui identità gestita, entità servizio e identità del carico di lavoro.
• SQL Server e autenticazione di Windows: Supporta autenticazione SQL, NTLM, Kerberos e single sign-on (SSO) su Windows.
• Always Encrypted: crittografia lato client con provider di chiavi per certificato locale, Windows Certificate Store e Azure Key Vault.
• Copia in massa: operazioni di inserimento in blocco ad alte prestazioni.
• Parametri a valori di tabella (TVP): Passano dati strutturati alle stored procedure.
• Protocolli multipli: TCP, pipe nominati, memoria condivisa e Dedicated Administrator Connection (DAC).
• Crittografia TDS 8.0: Crittografia end-to-end con modalità rigorosa.

Per iniziare

Configurare le connessioni

Uso dei dati

Distribuire e gestire

Guide a piattaforme e protocolli

Reference

Contenuti correlati

• go-mssqldb su GitHub
• Documentazione di riferimento dell'API go-mssqldb su pkg.go.dev
• Librerie di connessione SQL
• Quickstart: Usa Golang per interrogare database SQL di Azure