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.

Sign up for GitHub

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

Add documentation for SetQueryNotification #524

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
3659894
Add godocs for SetQueryNotification
chris-rossi Sep 24, 2019
df965ee
add readme on setting up query notifications
chris-rossi Oct 30, 2019
947a6d7
update query notification example
chris-rossi Oct 30, 2019
47f1070
update comment
chris-rossi Oct 30, 2019
ebae179
remove old example
chris-rossi Oct 30, 2019
6f7b03e
add initialization variables to allow compile
chris-rossi Nov 7, 2019
8638508
change parameter declaration
chris-rossi Nov 7, 2019
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
61 changes: 61 additions & 0 deletions doc/mssql_examples_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
package main
Copy link
Contributor

@yukiwongky yukiwongky Sep 24, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only documentation (md files) should be in the doc folder. If this example test works as a standalone test, please put it in the root folder.

Since this example is targeting the SetQueryNotification, you should rename is to something like setquerynotification_example_text.go.

If you look at other *_examples_test.go files (e.g., datetimeoffset_example_test.go), you will see that instead of identifying is as package main, they use package mssql_test. That way if this file is in the root folder along with the src files, you will not get package clash (having 2 packages in the same directory). When godoc gets this example, they'll replace package mssql_test with package main so it looks like a proper test application.

Suggested change
package main
package mssql_test

It's also a good idea to add a .md file in the doc folder to show the users now this query notification feature works.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the function has "Example" prefixing it's name it won't be run as a test. I have moved it from the doc folder though.


import (
"flag"
"fmt"
"log"
"time"

mssql "github.com/denisenkom/go-mssqldb"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't need to explicitly set the alias. It is mssql by default.

Suggested change
mssql "github.com/denisenkom/go-mssqldb"
"github.com/denisenkom/go-mssqldb"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I kept it since it seems to be like this in other examples.

)

var (
debug = flag.Bool("debug", false, "enable debugging")
password = flag.String("password", "", "the database password")
port *int = flag.Int("port", 1433, "the database port")
server = flag.String("server", "", "the database server")
user = flag.String("user", "", "the database user")
database = flag.String("database", "", "the database name")
)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You will get redefinition errors here if this file is in package mssql_test, since these variables are already defined in newconnector_example_test.go. You can just remove this whole block of variables.


func ExampleSetQueryNotification() {
flag.Parse()

if *debug {
fmt.Printf(" password:%s\n", *password)
fmt.Printf(" port:%d\n", *port)
fmt.Printf(" server:%s\n", *server)
fmt.Printf(" user:%s\n", *user)
fmt.Printf(" database:%s\n", *database)
}

connString := fmt.Sprintf("server=%s;user id=%s;password=%s;port=%d;database=%s;", *server, *user, *password, *port, *database)
if *debug {
fmt.Printf(" connString:%s\n", connString)
}
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];")
Copy link
Contributor

@yukiwongky yukiwongky Sep 24, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any special setup needed for the Schema and Table for query notification to work? Perhaps add comments letting user know what setup is required?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is no special setup for the schema or table but query notifications must be setup on SQL Server for this example to work.

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)

rows, err := sqlstmt.Query(nil)
if err != nil {
log.Fatal("Query failed:", err.Error())
} else {
rows.Close()
Copy link
Contributor

@yukiwongky yukiwongky Sep 24, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does rows contain in this case? Perhaps add a comment letting user know what is the expected output?

}
}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add newline.

4 changes: 4 additions & 0 deletions mssql.go
View file
Open in desktop
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