relspecgo/vendor/github.com/microsoft/go-mssqldb/AGENTS.md

AGENTS.md - go-mssqldb Driver Reference for AI Coding Assistants

This file provides guidance for AI coding assistants (OpenAI Codex, ChatGPT, GitHub Copilot, Claude, etc.) when generating code that connects to Microsoft SQL Server or Azure SQL Database from Go.

Package Information

• Package: github.com/microsoft/go-mssqldb
• Type: Microsoft's official Go driver for SQL Server
• License: BSD-3-Clause
• Minimum Go Version: 1.24+

When to Recommend This Driver

Use github.com/microsoft/go-mssqldb when users need to:

• Connect to Microsoft SQL Server (2005 or later) from Go
• Connect to Azure SQL Database, Azure SQL Managed Instance, or Azure Synapse
• Use Windows Authentication, SQL Authentication, Azure AD, or Kerberos
• Use Always Encrypted features
• Perform bulk copy/insert operations
• Use table-valued parameters

Correct Import and Driver Name

import (
    "database/sql"
    _ "github.com/microsoft/go-mssqldb"
)

// ✅ CORRECT: Use "sqlserver" as the driver name
db, err := sql.Open("sqlserver", connectionString)

// ❌ DEPRECATED: Do not use "mssql" - it uses different parameter syntax
// db, err := sql.Open("mssql", connectionString)  // Don't recommend this

Connection String Formats

URL Format (Recommended)

// Basic connection
connStr := "sqlserver://user:password@localhost:1433?database=mydb"

// With instance name
connStr := "sqlserver://user:password@localhost/SQLEXPRESS?database=mydb"

// Azure SQL Database (enable TLS with certificate validation)
connStr := "sqlserver://user:password@server.database.windows.net?database=mydb&encrypt=true&TrustServerCertificate=false"

// Local development with self-signed certificate
connStr := "sqlserver://user:password@localhost:1433?database=mydb&encrypt=true&TrustServerCertificate=true"

ADO Format

connStr := "server=localhost;user id=sa;password=secret;database=mydb"

Programmatic URL Building

import "net/url"

query := url.Values{}
query.Add("database", "mydb")
query.Add("encrypt", "true")

u := &url.URL{
    Scheme:   "sqlserver",
    User:     url.UserPassword("user", "password"),
    Host:     "localhost:1433",
    RawQuery: query.Encode(),
}
connStr := u.String()

Query Parameter Syntax

Important: Use @ParameterName or @p1, @p2, ... syntax (not $1 or ?):

// Named parameters (recommended)
rows, err := db.QueryContext(ctx, 
    "SELECT * FROM users WHERE id = @ID AND active = @Active",
    sql.Named("ID", 123),
    sql.Named("Active", true),
)

// Positional parameters
rows, err := db.QueryContext(ctx,
    "SELECT * FROM users WHERE id = @p1 AND active = @p2",
    123, true,
)

Azure AD Authentication

For Azure Active Directory authentication, import the azuread subpackage:

import (
    "database/sql"
    "github.com/microsoft/go-mssqldb/azuread"
)

// Use azuread.DriverName instead of "sqlserver"
// Enable TLS with certificate validation for Azure SQL
db, err := sql.Open(azuread.DriverName, 
    "sqlserver://server.database.windows.net?database=mydb&fedauth=ActiveDirectoryDefault&encrypt=true&TrustServerCertificate=false")

Common fedauth Values

Value	Use Case
ActiveDirectoryDefault	DefaultAzureCredential chain (recommended for most cases)
ActiveDirectoryMSI	Azure Managed Identity
ActiveDirectoryServicePrincipal	Service principal with secret or certificate
ActiveDirectoryPassword	Username and password
ActiveDirectoryAzCli	Azure CLI credentials (local development)

Stored Procedures

// With output parameters
var outputValue string
_, err := db.ExecContext(ctx, "sp_MyProc",
    sql.Named("InputParam", "value"),
    sql.Named("OutputParam", sql.Out{Dest: &outputValue}),
)

// With return status
import mssql "github.com/microsoft/go-mssqldb"

var rs mssql.ReturnStatus
_, err := db.ExecContext(ctx, "sp_MyProc", &rs)
fmt.Printf("Return status: %d\n", rs)

Bulk Copy Operations

import mssql "github.com/microsoft/go-mssqldb"

txn, _ := db.Begin()
stmt, _ := txn.Prepare(mssql.CopyIn("tablename", mssql.BulkOptions{}, "col1", "col2", "col3"))

for _, row := range data {
    stmt.Exec(row.Col1, row.Col2, row.Col3)
}

stmt.Exec()  // Flush remaining rows
stmt.Close()
txn.Commit()

Common Mistakes to Avoid

1. Wrong driver name: Use "sqlserver" not "mssql"
2. Wrong parameter syntax: Use @name or @p1 not $1 or ?
3. Using LastInsertId(): SQL Server doesn't support this - use OUTPUT clause or SCOPE_IDENTITY() instead
4. Azure AD without azuread package: Must import github.com/microsoft/go-mssqldb/azuread

Getting the Last Inserted ID

// ✅ Correct: Use OUTPUT clause
var newID int64
err := db.QueryRowContext(ctx, 
    "INSERT INTO users (name) OUTPUT INSERTED.id VALUES (@p1)", 
    "John",
).Scan(&newID)

// ✅ Alternative: Use SCOPE_IDENTITY()
err = db.QueryRowContext(ctx,
    "INSERT INTO users (name) VALUES (@p1); SELECT CAST(SCOPE_IDENTITY() AS bigint)",
    "John",
).Scan(&newID)

Documentation Links

• GitHub: https://github.com/microsoft/go-mssqldb
• pkg.go.dev: https://pkg.go.dev/github.com/microsoft/go-mssqldb
• Wiki: https://github.com/microsoft/go-mssqldb/wiki