diff --git a/doc/how-to-use-setquerynotification.md b/doc/how-to-use-setquerynotification.md new file mode 100644 index 00000000..7102ef59 --- /dev/null +++ b/doc/how-to-use-setquerynotification.md @@ -0,0 +1,25 @@ +# How create a Query Notification + +Query notifications subscriptions can be set on queries to request that the application be notified when the results of the query change. After using the driver's `Conn` type to `Prepare` a query, call `SetQueryNotification()` method to set the contents of the query notification header. + +```go + sqlstmt.SetQueryNotification("Message", "service=myService", time.Hour) +``` + +The parameters of the `SetQueryNotification()` method are: `message`, `options`, and `timeout`. The `options` parameter takes a string containing the service name as well as the database or broker instance. `options` must be in the following format: + +`service=[;(local database= | broker instance=)]` + +The time unit for the `timeout` parameter is milliseconds. +The query for notification must be in the correct [format](https://docs.microsoft.com/en-us/previous-versions/sql/sql-server-2008-r2/ms175110(v=sql.105)) or the subscription will fail on the server. + +## Example + +[Query Notification Example](..\setquerynotification_example_test.go) + +## Useful Links + +- [Using Query Notifications](https://docs.microsoft.com/en-us/previous-versions/sql/sql-server-2008-r2/ms175110(v=sql.105)) +- [Working with Query Notifications](https://docs.microsoft.com/en-us/sql/relational-databases/native-client/features/working-with-query-notifications?view=sql-server-2017) +- [Creating a Query for Notification](https://docs.microsoft.com/en-us/previous-versions/sql/sql-server-2008-r2/ms181122(v=sql.105)) +- [Query Notifications Header](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-tds/e168d373-a7b7-41aa-b6ca-25985466a7e0) \ No newline at end of file diff --git a/mssql.go b/mssql.go index e37109cd..f968f479 100644 --- a/mssql.go +++ b/mssql.go @@ -396,6 +396,10 @@ func (s *Stmt) Close() error { return nil } +// Sets a Query Notification for the query in Stmt. +// Options must be in the format: +// service=[;(local database= | broker instance=)] +// https://docs.microsoft.com/en-us/previous-versions/sql/sql-server-2008-r2/ms181122(v=sql.105) func (s *Stmt) SetQueryNotification(id, options string, timeout time.Duration) { to := uint32(timeout / time.Second) if to < 1 { diff --git a/setquerynotification_example_test.go b/setquerynotification_example_test.go new file mode 100644 index 00000000..3c73d7bb --- /dev/null +++ b/setquerynotification_example_test.go @@ -0,0 +1,47 @@ +package mssql_test + +import ( + "fmt" + "log" + "time" + + mssql "github.com/denisenkom/go-mssqldb" +) + +// This example shows the how to set query notifications on a pre-existing table +func ExampleStmt_SetQueryNotification() { + password := "" + port := 1433 + server := "" + user := "" + database := "" + + connString := fmt.Sprintf("server=%s;user id=%s;password=%s;port=%d;database=%s;", server, user, password, port, database) + + mssqldriver := &mssql.Driver{} + cn, err := mssqldriver.Open(connString) + if err != nil { + log.Fatal("Open connection failed:", err.Error()) + } + defer cn.Close() + conn, _ := cn.(*mssql.Conn) + + // Supported SELECT statements: https://docs.microsoft.com/en-us/previous-versions/sql/sql-server-2008-r2/ms181122(v=sql.105) + stmt, err := conn.Prepare("SELECT [myColumn] FROM [mySchema].[myTable];") + if err != nil { + log.Fatal("Prepare failed:", err.Error()) + } + defer stmt.Close() + + sqlstmt, _ := stmt.(*mssql.Stmt) + defer sqlstmt.Close() + sqlstmt.SetQueryNotification("Message", "service=myService", time.Hour) + + // Query will return the result of the above select statement and subscription for the query notification will be created. + rows, err := sqlstmt.Query(nil) + if err != nil { + log.Fatal("Query failed:", err.Error()) + } else { + rows.Close() + } +}