Changeset 446 for trunk/docs


Ignore:
Timestamp:
Oct 2, 2012, 12:12:19 PM (7 years ago)
Author:
cito
Message:

Support positional parameters in the query() method.

Location:
trunk/docs
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/docs/changelog.txt

    r444 r446  
    77- Support the new PostgreSQL versions 9.0 and 9.1.
    88- Particularly, support PQescapeLiteral() and PQescapeIdentifier().
     9- The query method of the classic API now supports positional parameters.
     10  This an effective way to pass arbitrary or unknown data without worrying
     11  about SQL injection or syntax errors (contribution by Patrick TJ McPhee).
    912- The execute() and executemany() methods now return the cursor object,
    1013  so you can now write statements like "for row in cursor.execute(...)"
  • trunk/docs/pg.txt

    r445 r446  
    424424Syntax::
    425425
    426   query(command)
     426  query(command, [args])
    427427
    428428Parameters:
    429429  :command: SQL command (string)
     430  :args: optional positional arguments
    430431
    431432Return type:
     
    450451  or `dictresult()` method or simply printed. Otherwise, it returns `None`.
    451452
     453  The query may optionally contain positional parameters of the form `$1`,
     454  `$2`, etc instead of literal data, and the values supplied as a tuple.
     455  The values are substituted by the database in such a way that they don't
     456  need to be escaped, making this an effective way to pass arbitrary or
     457  unknown data without worrying about SQL injection or syntax errors.
     458
    452459  When the database could not process the query, a `pg.ProgrammingError` or
    453460  a `pg.InternalError` is raised. You can check the "SQLSTATE" code of this
    454461  error by reading its `sqlstate` attribute.
     462
     463Example::
     464
     465  name = raw_input("Name? ")
     466  phone = con.query("select phone from employees"
     467    " where name=$1", (name, )).getresult()
    455468
    456469reset - resets the connection
     
    10031016  either in the dictionary where the OID must be munged, or in the keywords
    10041017  where it can be simply the string "oid".
     1018
     1019query - executes a SQL command string
     1020-------------------------------------
     1021Syntax::
     1022
     1023  query(command, [arg1, [arg2, ...]])
     1024
     1025Parameters:
     1026  :command: SQL command (string)
     1027  :arg*: optional positional arguments
     1028
     1029Return type:
     1030  :pgqueryobject, None: result values
     1031
     1032Exceptions raised:
     1033  :TypeError: bad argument type, or too many arguments
     1034  :TypeError: invalid connection
     1035  :ValueError: empty SQL query or lost connection
     1036  :pg.ProgrammingError: error in query
     1037  :pg.InternalError: error during query processing
     1038
     1039Description:
     1040  Similar to the pgobject function with the same name, except that positional
     1041  arguments can be passed either as a single list or tuple, or as individual
     1042  positional arguments
     1043
     1044Example::
     1045
     1046  name = raw_input("Name? ")
     1047  phone = raw_input("Phone? "
     1048  rows = db.query("update employees set phone=$2"
     1049    " where name=$1", (name, phone)).getresult()[0][0]
     1050  # or
     1051  rows = db.query("update employees set phone=$2"
     1052    " where name=$1", name, phone).getresult()[0][0]
    10051053
    10061054clear - clears row values in memory
Note: See TracChangeset for help on using the changeset viewer.