minor db doc improvements

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)))
  #""
  #"")

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"].
 

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