Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation for SetQueryNotification #524

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions doc/how-to-use-setquerynotification.md
Original file line number Diff line number Diff line change
@@ -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=<service-name>[;(local database=<database> | broker instance=<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)
4 changes: 4 additions & 0 deletions mssql.go
Original file line number Diff line number Diff line change
Expand Up @@ -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=<service-name>[;(local database=<database> | broker instance=<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 {
Expand Down
47 changes: 47 additions & 0 deletions setquerynotification_example_test.go
Original file line number Diff line number Diff line change
@@ -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()
}
}