mssql: update docs, rename ResetSQL to SessionInitSQL and document

Author: kardianos

README.md

@@ -68,7 +68,7 @@ Other supported formats are listed below.
   * `sqlserver://username:password@host:port?param1=value&param2=value`
   * `sqlserver://sa@localhost/SQLExpress?database=master&connection+timeout=30` // `SQLExpress instance.
   * `sqlserver://sa:mypass@localhost?database=master&connection+timeout=30`     // username=sa, password=mypass.
-  * `sqlserver://sa:mypass@localhost:1234?database=master&connection+timeout=30"` // port 1234 on localhost.
+  * `sqlserver://sa:mypass@localhost:1234?database=master&connection+timeout=30` // port 1234 on localhost.
   * `sqlserver://sa:my%7Bpass@somehost?connection+timeout=30` // password is "my{pass"
 
   A string of this format can be constructed using the `URL` type in the `net/url` package.
@@ -126,6 +126,21 @@ the sql query to be in the form of either `@Name` or `@p1` to `@pN` (ordinal pos
 db.QueryContext(ctx, `select * from t where ID = @ID and Name = @p2;`, sql.Named("ID", 6), "Bob")
 ```
 
+## Important Notes
+
+ * [LastInsertId](https://golang.org/pkg/database/sql/#Result.LastInsertId) should
+    not be used with this driver (or SQL Server) due to how the TDS protocol
+	works. Please use the [OUTPUT Clause](https://docs.microsoft.com/en-us/sql/t-sql/queries/output-clause-transact-sql)
+	or add a `select ID = convert(bigint, SCOPE_IDENTITY());` to the end of your
+	query (ref [SCOPE_IDENTITY](https://docs.microsoft.com/en-us/sql/t-sql/functions/scope-identity-transact-sql)).
+	This will ensure you are getting the correct ID and will prevent a network round trip.
+ * [NewConnector](https://godoc.org/github.com/denisenkom/go-mssqldb#NewConnector)
+    may be used with [OpenDB](https://golang.org/pkg/database/sql/#OpenDB).
+ * [Connector.SessionInitSQL](https://godoc.org/github.com/denisenkom/go-mssqldb#Connector.SessionInitSQL)
+	may be set to set any driver specific session settings after the session
+	has been reset. If empty the session will still be reset but use the database
+	defaults in Go1.10+.
+
 ## Features
 
 * Can be used with SQL Server 2005 or newer

doc.go

@@ -1,12 +1,14 @@
 // package mssql implements the TDS protocol used to connect to MS SQL Server (sqlserver)
 // database servers.
 //
-// This package registers two drivers:
+// This package registers the driver:
 //    sqlserver: uses native "@" parameter placeholder names and does no pre-processing.
-//    mssql: expects identifiers to be prefixed with ":" and pre-processes queries.
 //
 // If the ordinal position is used for query parameters, identifiers will be named
 // "@p1", "@p2", ... "@pN".
 //
-// Please refer to the README for the format of the DSN.
+// Please refer to the README for the format of the DSN. There are multiple DSN
+// formats accepted: ADO style, ODBC style, and URL style. The following is an
+// example of a URL style DSN:
+//    sqlserver://sa:mypass@localhost:1234?database=master&connection+timeout=30
 package mssql

mssql.go

@@ -72,6 +72,20 @@ func (d *Driver) SetLogger(logger Logger) {
 	d.log = optionalLogger{logger}
 }
 
+// NewConnector creates a new connector from a DSN.
+// The returned connector may be used with sql.OpenDB.
+func NewConnector(dsn string) (*Connector, error) {
+	params, err := parseConnectParams(dsn)
+	if err != nil {
+		return nil, err
+	}
+	c := &Connector{
+		params: params,
+		driver: driverInstanceNoProcess,
+	}
+	return c, nil
+}
+
 // Connector holds the parsed DSN and is ready to make a new connection
 // at any time.
 //
@@ -81,11 +95,12 @@ type Connector struct {
 	params connectParams
 	driver *Driver
 
-	// ResetSQL is executed after marking a given connection to be reset.
-	// When not present, the next query will be reset to the database
-	// defaults.
-	// When present the connection will immediately mark the connection to
-	// be reset, then execute the ResetSQL text to setup the session
+	// SessionInitSQL is executed after marking a given session to be reset.
+	// When not present, the next query will still reset the session to the
+	// database defaults.
+	//
+	// When present the connection will immediately mark the session to
+	// be reset, then execute the SessionInitSQL text to setup the session
 	// that may be different from the base database defaults.
 	//
 	// For Example, the application relies on the following defaults
@@ -96,9 +111,12 @@ type Connector struct {
 	//    SET ANSI_NULLS ON;
 	//    SET LOCK_TIMEOUT 10000;
 	//
-	// ResetSQL should not attempt to manually call sp_reset_connection.
+	// SessionInitSQL should not attempt to manually call sp_reset_connection.
 	// This will happen at the TDS layer.
-	ResetSQL string
+	//
+	// SessionInitSQL is optional. The session will be reset even if
+	// SessionInitSQL is empty.
+	SessionInitSQL string
 }
 
 type Conn struct {

mssql_go110.go

@@ -16,11 +16,11 @@ func (c *Conn) ResetSession(ctx context.Context) error {
 	}
 	c.resetSession = true
 
-	if c.connector == nil || len(c.connector.ResetSQL) == 0 {
+	if c.connector == nil || len(c.connector.SessionInitSQL) == 0 {
 		return nil
 	}
 
-	s, err := c.prepareContext(ctx, c.connector.ResetSQL)
+	s, err := c.prepareContext(ctx, c.connector.SessionInitSQL)
 	if err != nil {
 		return driver.ErrBadConn
 	}

queries_go110_test.go

@@ -8,7 +8,7 @@ import (
 	"testing"
 )
 
-func TestResetSQL(t *testing.T) {
+func TestSessionInitSQL(t *testing.T) {
 	checkConnStr(t)
 	SetLogger(testLogger{t})
 
@@ -17,7 +17,13 @@ func TestResetSQL(t *testing.T) {
 	if err != nil {
 		t.Fatal("unable to open connector", err)
 	}
-	connector.ResetSQL = `
+
+	// Do not use these settings in your application
+	// unless you know what they do.
+	// Thes are for this unit test only.
+	//
+	// Sessions will be reset even if SessionInitSQL is not set.
+	connector.SessionInitSQL = `
 SET XACT_ABORT ON; -- 16384
 SET ANSI_NULLS ON; -- 32
 SET ARITHIGNORE ON; -- 128