From 178a84261faae68cc8b71e1a35389c7354e0f7b7 Mon Sep 17 00:00:00 2001 From: Jack Christensen Date: Sat, 23 Jul 2022 07:53:02 -0500 Subject: [PATCH] Improve Query docs --- conn.go | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/conn.go b/conn.go index 1a43a3ca..53004327 100644 --- a/conn.go +++ b/conn.go @@ -603,12 +603,16 @@ type QueryRewriter interface { RewriteQuery(ctx context.Context, conn *Conn, sql string, args []any) (newSQL string, newArgs []any) } -// Query executes sql with args. It is safe to attempt to read from the returned Rows even if an error is returned. The -// error will be the available in rows.Err() after rows are closed. So it is allowed to ignore the error returned from -// Query and handle it in Rows. +// Query sends a query to the server and returns a Rows to read the results. Only errors encountered sending the query +// and initializing Rows will be returned. Err() on the returned Rows must be checked after the Rows is closed to +// determine if the query executed successfully. // -// Err() on the returned Rows must be checked after the Rows is closed to determine if the query executed successfully -// as some errors can only be detected by reading the entire response. e.g. A divide by zero error on the last row. +// The returned Rows must be closed before the connection can be used again. It is safe to attempt to read from the +// returned Rows even if an error is returned. The error will be the available in rows.Err() after rows are closed. It +// is allowed to ignore the error returned from Query and handle it in Rows. +// +// An implementor of QueryRewriter may be passed as the first element of args. It can rewrite the sql and change or +// replace args. For example, NamedArgs is QueryRewriter that implements named arguments. // // For extra control over how the query is executed, the types QueryExecMode, QueryResultFormats, and // QueryResultFormatsByOID may be used as the first args to control exactly how the query is executed. This is rarely