feat: add native JSON type support for SQL Server 2025

Author: dlevy-msft-sql

CHANGELOG.md

@@ -3,6 +3,7 @@
 
 ### Features
 
+* Add native JSON type support for SQL Server 2025 Preview. The driver now negotiates JSON support during TDS login and properly handles the new JSON data type (0xF4). JSON data is decoded using the NVARCHAR string path and returned as `string`; it can be scanned into `string`, `[]byte`, `mssql.NullJSON`, or types implementing `sql.Scanner`.
 * Added new `serverCertificate` connection parameter for byte-for-byte certificate validation, matching Microsoft.Data.SqlClient behavior. This parameter skips hostname validation, chain validation, and expiry checks, only verifying that the server's certificate exactly matches the provided file. This is useful when the server's hostname doesn't match the certificate CN/SAN. (#304)
 * The existing `certificate` parameter maintains backward compatibility with traditional X.509 chain validation including hostname checks, expiry validation, and chain-of-trust verification.
 * `serverCertificate` cannot be used with `certificate` or `hostnameincertificate` parameters to prevent conflicting validation methods.

README.md

@@ -492,6 +492,8 @@ are supported:
 
 * string -> nvarchar
 * mssql.VarChar -> varchar
+* mssql.JSON -> json (SQL Server 2025+) or nvarchar(max) (older versions)
+* mssql.NullJSON -> json (nullable, SQL Server 2025+) or nvarchar(max) (older versions)
 * time.Time -> datetimeoffset or datetime (TDS version dependent)
 * mssql.DateTime1 -> datetime
 * mssql.DateTimeOffset -> datetimeoffset
@@ -515,6 +517,41 @@ db.QueryContext(ctx, `select * from t2 where user_name = @p1;`, mssql.VarChar(na
 // Note: Mismatched data types on table and parameter may cause long running queries
 ```
 
+### JSON Type
+
+The driver provides `mssql.JSON` and `mssql.NullJSON` types for working with JSON data. These types work seamlessly across all supported SQL Server versions with automatic fallback behavior.
+
+**Server Compatibility:**
+- **SQL Server 2025+ / Azure SQL Database**: Uses the native JSON data type (type ID 0xF4) for optimal performance and type safety
+- **SQL Server 2016-2022**: Automatically falls back to `nvarchar(max)` parameter declaration, allowing JSON data to work with the built-in JSON functions (JSON_VALUE, JSON_QUERY, ISJSON, etc.)
+
+The driver automatically detects server capabilities during connection and chooses the appropriate behavior. You can use the same `mssql.JSON` and `mssql.NullJSON` types regardless of the SQL Server version - no code changes required.
+
+**Note:** Native JSON *columns* (using the JSON data type in CREATE TABLE) require SQL Server 2025+ or Azure SQL Database. On older versions, store JSON in `nvarchar(max)` columns.
+
+```go
+// Insert JSON data
+jsonData := json.RawMessage(`{"name":"John","age":30,"active":true}`)
+_, err := db.ExecContext(ctx, "INSERT INTO users (profile) VALUES (@p1)", mssql.JSON(jsonData))
+
+// Insert nullable JSON
+nullableJSON := mssql.NullJSON{JSON: json.RawMessage(`{"key":"value"}`), Valid: true}
+_, err = db.ExecContext(ctx, "INSERT INTO users (metadata) VALUES (@p1)", nullableJSON)
+
+// Insert NULL JSON value
+nullJSON := mssql.NullJSON{Valid: false}
+_, err = db.ExecContext(ctx, "INSERT INTO users (metadata) VALUES (@p1)", nullJSON)
+
+// Read JSON data
+var result mssql.NullJSON
+err = db.QueryRowContext(ctx, "SELECT metadata FROM users WHERE id = @p1", 1).Scan(&result)
+if result.Valid {
+    fmt.Println("JSON data:", result.JSON)
+} else {
+    fmt.Println("JSON is NULL")
+}
+```
+
 ## Using Always Encrypted
 
 The protocol and cryptography details for AE are [detailed elsewhere](https://learn.microsoft.com/sql/relational-databases/security/encryption/always-encrypted-database-engine?view=sql-server-ver16).
@@ -590,6 +627,7 @@ Constrain the provider to an allowed list of key vaults by appending vault host
 * Can be used with Microsoft Azure SQL Database
 * Can be used on all go supported platforms (e.g. Linux, Mac OS X and Windows)
 * Supports new date/time types: date, time, datetime2, datetimeoffset
+* Supports JSON data with automatic fallback (SQL Server 2016+, native JSON type in 2025+)
 * Supports string parameters longer than 8000 characters
 * Supports encryption using SSL/TLS
 * Supports SQL Server and Windows Authentication
@@ -647,6 +685,8 @@ More information: <http://support.microsoft.com/kb/2653857>
 
 * Bulk copy does not yet support encrypting column values using Always Encrypted. Tracked in [#127](https://github.com/microsoft/go-mssqldb/issues/127)
 
+* The JSON data type is not supported with Always Encrypted. This is a SQL Server limitation - the JSON type is not included in the list of [supported data types for Always Encrypted](https://learn.microsoft.com/en-us/sql/relational-databases/security/encryption/always-encrypted-cryptography).
+
 # Contributing
 This project is a fork of [https://github.com/denisenkom/go-mssqldb](https://github.com/denisenkom/go-mssqldb) and welcomes new and previous contributors. For more informaton on contributing to this project, please see [Contributing](./CONTRIBUTING.md).
 

examples/channel_binding/tsql.go

@@ -14,23 +14,23 @@ import (
 
 	"github.com/google/uuid"
 	mssqldb "github.com/microsoft/go-mssqldb"
-	"github.com/microsoft/go-mssqldb/msdsn"
 	_ "github.com/microsoft/go-mssqldb/integratedauth/krb5"
+	"github.com/microsoft/go-mssqldb/msdsn"
 )
 
 func main() {
 	var (
-		userid   = flag.String("U", "", "login_id")
-		password = flag.String("P", "", "password")
-		server   = flag.String("S", "localhost", "server_name[\\instance_name]")
-		port     = flag.Uint64("p", 1433, "server port")
-		keyLog   = flag.String("K", "tlslog.log", "path to sslkeylog file")
-		database = flag.String("d", "", "db_name")
-		spn      = flag.String("spn", "", "SPN")
-		auth = flag.String("a", "ntlm", "Authentication method: ntlm, krb5 or winsspi")
-		epa = flag.Bool("epa", true, "EPA enabled: true, false")
-		encrypt = flag.String("e", "required", "encrypt mode: required, disabled, strict, optional")
-		query = flag.String("q", "", "query to execute")
+		userid        = flag.String("U", "", "login_id")
+		password      = flag.String("P", "", "password")
+		server        = flag.String("S", "localhost", "server_name[\\instance_name]")
+		port          = flag.Uint64("p", 1433, "server port")
+		keyLog        = flag.String("K", "tlslog.log", "path to sslkeylog file")
+		database      = flag.String("d", "", "db_name")
+		spn           = flag.String("spn", "", "SPN")
+		auth          = flag.String("a", "ntlm", "Authentication method: ntlm, krb5 or winsspi")
+		epa           = flag.Bool("epa", true, "EPA enabled: true, false")
+		encrypt       = flag.String("e", "required", "encrypt mode: required, disabled, strict, optional")
+		query         = flag.String("q", "", "query to execute")
 		tlsMinVersion = flag.String("tlsmin", "1.1", "TLS minimum version: 1.0, 1.1, 1.2, 1.3")
 		tlsMaxVersion = flag.String("tlsmax", "1.3", "TLS maximum version: 1.0, 1.1, 1.2, 1.3")
 	)
@@ -61,7 +61,7 @@ func main() {
 		Password:       *password,
 		ChangePassword: "",
 		AppName:        "go-mssqldb",
-		ServerSPN: *spn,
+		ServerSPN:      *spn,
 		TLSConfig: &tls.Config{
 			InsecureSkipVerify:          true, // adjust for your case
 			ServerName:                  *server,
@@ -70,11 +70,11 @@ func main() {
 			MinVersion:                  tlsMinVersionNum,
 			MaxVersion:                  tlsMaxVersionNum,
 		},
-		Encryption:         encryption,
+		Encryption: encryption,
 		Parameters: map[string]string{
-			"authenticator": *auth,
+			"authenticator":      *auth,
 			"krb5-credcachefile": os.Getenv("KRB5_CCNAME"),
-			"krb5-configfile": os.Getenv("KRB5_CONFIG"),
+			"krb5-configfile":    os.Getenv("KRB5_CONFIG"),
 		},
 		ProtocolParameters: map[string]interface{}{},
 		Protocols: []string{
@@ -87,7 +87,7 @@ func main() {
 		DialTimeout: time.Second * 5,
 		ConnTimeout: time.Second * 10,
 		KeepAlive:   time.Second * 30,
-		EpaEnabled: *epa,
+		EpaEnabled:  *epa,
 	}
 
 	activityid, uerr := uuid.NewRandom()
@@ -116,7 +116,7 @@ func main() {
 		fmt.Println("Cannot connect: ", err.Error())
 		return
 	}
-	
+
 	if *query != "" {
 		err = exec(db, *query)
 		if err != nil {
@@ -222,4 +222,4 @@ func parseEncrypt(encrypt string) (msdsn.Encryption, error) {
 	default:
 		return msdsn.EncryptionOff, fmt.Errorf("invalid encrypt '%s'", encrypt)
 	}
-}
+}

integratedauth/auth_test.go

@@ -14,10 +14,10 @@ type stubAuth struct {
 	user string
 }
 
-func (s *stubAuth) InitialBytes() ([]byte, error)    { return nil, nil }
-func (s *stubAuth) NextBytes([]byte) ([]byte, error) { return nil, nil }
-func (s *stubAuth) Free()                            {}
-func (s *stubAuth) SetChannelBinding(*ChannelBindings)          {}
+func (s *stubAuth) InitialBytes() ([]byte, error)      { return nil, nil }
+func (s *stubAuth) NextBytes([]byte) ([]byte, error)   { return nil, nil }
+func (s *stubAuth) Free()                              {}
+func (s *stubAuth) SetChannelBinding(*ChannelBindings) {}
 
 func getAuth(config msdsn.Config) (IntegratedAuthenticator, error) {
 	return &stubAuth{config.User}, nil

integratedauth/channel_binding.go

@@ -14,11 +14,12 @@ type AuthenticatorWithEPA interface {
 }
 
 type ChannelBindingsType uint32
+
 const (
-	ChannelBindingsTypeTLSExporter = 0
-	ChannelBindingsTypeTLSUnique   = 1
+	ChannelBindingsTypeTLSExporter       = 0
+	ChannelBindingsTypeTLSUnique         = 1
 	ChannelBindingsTypeTLSServerEndPoint = 2
-	ChannelBindingsTypeEmpty = 3
+	ChannelBindingsTypeEmpty             = 3
 )
 
 const (
@@ -34,7 +35,7 @@ const (
 // gss_channel_bindings_struct: https://docs.oracle.com/cd/E19683-01/816-1331/overview-52/index.html
 // gss_buffer_desc: https://docs.oracle.com/cd/E19683-01/816-1331/reference-21/index.html
 type ChannelBindings struct {
-	Type ChannelBindingsType
+	Type              ChannelBindingsType
 	InitiatorAddrType uint32
 	InitiatorAddress  []byte
 	AcceptorAddrType  uint32
@@ -56,7 +57,7 @@ type SEC_CHANNEL_BINDINGS struct {
 }
 
 var EmptyChannelBindings = &ChannelBindings{
-	Type: ChannelBindingsTypeEmpty,
+	Type:              ChannelBindingsTypeEmpty,
 	InitiatorAddrType: 0,
 	InitiatorAddress:  nil,
 	AcceptorAddrType:  0,
@@ -175,7 +176,7 @@ func GenerateCBTFromTLSUnique(tlsUnique []byte) (*ChannelBindings, error) {
 		return nil, fmt.Errorf("tlsUnique is empty")
 	}
 	return &ChannelBindings{
-		Type: ChannelBindingsTypeTLSUnique,
+		Type:              ChannelBindingsTypeTLSUnique,
 		InitiatorAddrType: 0,
 		InitiatorAddress:  nil,
 		AcceptorAddrType:  0,
@@ -212,7 +213,7 @@ func GenerateCBTFromTLSExporter(exporterKey []byte) (*ChannelBindings, error) {
 	}
 
 	return &ChannelBindings{
-		Type: ChannelBindingsTypeTLSExporter,
+		Type:              ChannelBindingsTypeTLSExporter,
 		InitiatorAddrType: 0,
 		InitiatorAddress:  nil,
 		AcceptorAddrType:  0,
@@ -247,7 +248,7 @@ func GenerateCBTFromServerCert(cert *x509.Certificate) *ChannelBindings {
 	_, _ = h.Write(cert.Raw)
 	certHash = h.Sum(nil)
 	return &ChannelBindings{
-		Type: ChannelBindingsTypeTLSServerEndPoint,
+		Type:              ChannelBindingsTypeTLSServerEndPoint,
 		InitiatorAddrType: 0,
 		InitiatorAddress:  nil,
 		AcceptorAddrType:  0,

integratedauth/channel_binding_test.go

@@ -35,4 +35,4 @@ func TestAsSSPI_SEC_CHANNEL_BINDINGS(t *testing.T) {
 			t.Errorf("Expected %s, but got %s for input %s", expected, hex.EncodeToString(winsspiCB), input)
 		}
 	}
-}
+}

integratedauth/winsspi/provider.go

@@ -1,3 +1,4 @@
+//go:build windows
 // +build windows
 
 package winsspi
@@ -12,4 +13,4 @@ func init() {
 	if err != nil {
 		panic(err)
 	}
-}
+}

integratedauth/winsspi/winsspi.go

@@ -1,3 +1,4 @@
+//go:build windows
 // +build windows
 
 package winsspi
@@ -141,10 +142,10 @@ func getAuth(config msdsn.Config) (integratedauth.IntegratedAuthenticator, error
 	}
 	domainUser := strings.SplitN(config.User, "\\", 2)
 	return &Auth{
-		Domain:   domainUser[0],
-		UserName: domainUser[1],
-		Password: config.Password,
-		Service:  config.ServerSPN,
+		Domain:         domainUser[0],
+		UserName:       domainUser[1],
+		Password:       config.Password,
+		Service:        config.ServerSPN,
 		channelBinding: nil,
 	}, nil
 }
@@ -243,7 +244,7 @@ func (auth *Auth) NextBytes(bytes []byte) ([]byte, error) {
 	// Second buffer: channel bindings (if present)
 	if auth.channelBinding != nil {
 		channelBindingBytes := auth.channelBinding.ToBytes()
-		in_desc_buffers[bufferCount].BufferType = SECBUFFER_CHANNEL_BINDINGS 
+		in_desc_buffers[bufferCount].BufferType = SECBUFFER_CHANNEL_BINDINGS
 		in_desc_buffers[bufferCount].pvBuffer = &channelBindingBytes[0]
 		in_desc_buffers[bufferCount].cbBuffer = uint32(len(channelBindingBytes))
 		bufferCount++