From 52cc30f05c997cf422f396ac1fdc2b4f908463ec Mon Sep 17 00:00:00 2001
From: Ryan Culpepper <ryanc@racket-lang.org>
Date: Tue, 27 Aug 2013 16:14:41 -0400
Subject: [PATCH] minor db doc improvements

---
 .../db/scribblings/log-for-using-db.rktd      |  2 +-
 .../db-pkgs/db-doc/db/scribblings/query.scrbl |  4 ++--
 .../db-doc/db/scribblings/using-db.scrbl      | 20 +++++++++++++++++--
 3 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/pkgs/db-pkgs/db-doc/db/scribblings/log-for-using-db.rktd b/pkgs/db-pkgs/db-doc/db/scribblings/log-for-using-db.rktd
index 29efb11ca3..aa295d3815 100644
--- a/pkgs/db-pkgs/db-doc/db/scribblings/log-for-using-db.rktd
+++ b/pkgs/db-pkgs/db-doc/db/scribblings/log-for-using-db.rktd
@@ -22,7 +22,7 @@
  ((3) 0 () 0 () () (c values c (void)))
  #""
  #"")
-((query-exec pgc "insert into the_numbers values (2, 'company')")
+((query-exec pgc "insert into the_numbers values ($1, $2)" (+ 1 1) "company")
  ((3) 0 () 0 () () (c values c (void)))
  #""
  #"")
diff --git a/pkgs/db-pkgs/db-doc/db/scribblings/query.scrbl b/pkgs/db-pkgs/db-doc/db/scribblings/query.scrbl
index 55cf815b34..de90509531 100644
--- a/pkgs/db-pkgs/db-doc/db/scribblings/query.scrbl
+++ b/pkgs/db-pkgs/db-doc/db/scribblings/query.scrbl
@@ -73,7 +73,7 @@ future operations to block indefinitely. See also
 @secref["kill-safe"].
 
 
-@section{Statements}
+@section[#:tag "query-statements"]{Statements}
 
 All query functions require both a connection and a
 @deftech{statement}, which is one of the following:
@@ -93,7 +93,7 @@ queries}. The parameter values must be supplied when the statement is
 executed; the parameterized statement and parameter values are sent to
 the database back end, which combines them correctly and safely.
 
-Use parameters instead of Racket string interpolation (eg,
+Use parameters instead of Racket string operations (eg,
 @racket[format] or @racket[string-append]) to avoid
 @secref["dbsec-sql-injection"].
 
diff --git a/pkgs/db-pkgs/db-doc/db/scribblings/using-db.scrbl b/pkgs/db-pkgs/db-doc/db/scribblings/using-db.scrbl
index aff37328c7..97461b8072 100644
--- a/pkgs/db-pkgs/db-doc/db/scribblings/using-db.scrbl
+++ b/pkgs/db-pkgs/db-doc/db/scribblings/using-db.scrbl
@@ -52,10 +52,26 @@ Use @racket[query-exec] method to execute a SQL statement for effect.
   "insert into the_numbers values (0, 'nothing')")
 (query-exec pgc 
   "insert into the_numbers values (1, 'the loneliest number')")
-(query-exec pgc
-  "insert into the_numbers values (2, 'company')")
 ]
 
+When a query contains a SQL value that isn't constant, refer to it
+through a ``query parameter'' rather than by dynamically computing the
+SQL query string (see also @secref["dbsec-sql-injection"]). Just
+provide the parameter values after the SQL statement in the query
+function call:
+
+@interaction[#:eval the-eval
+(query-exec pgc
+  "insert into the_numbers values ($1, $2)"
+  (+ 1 1)
+  "company")
+]
+
+Every standard query function accepts query parameters. The SQL syntax
+for query parameters depends on the database system (see
+@secref["query-statements"]). Other options for running parameterized
+queries are discussed below.
+
 The @racket[query] function is a more general way to execute a
 statement. It returns a structure encapsulating information about the
 statement's execution. (But some of that information varies from