Changeset 287 for trunk/docs


Ignore:
Timestamp:
May 7, 2006, 8:37:23 AM (13 years ago)
Author:
cito
Message:

Added escape/unescape functions for SQL strings and "bytea" conversion.

This has been already suggested with patches by Charlie Dyson and Kavous Bojnourdi a long time ago.

See: http://mailman.vex.net/pipermail/pygresql/2004-September/001336.html

Location:
trunk/docs
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • trunk/docs/changelog.txt

    r284 r287  
    66Version 3.8.1 (beta)
    77--------------------
     8- Added the functions escape_string() and escape/unescape_bytea()
     9  (as suggested by Charlie Dyson and Kavous Bojnourdi a long time ago).
    810- Reverted code in clear() method that set date to current.
    911- Added code for backwards compatibility in OID munging code.
    1012- Reorder attnames tests so that "interval" is checked for before "int."
    11 - If caller supplies key dictionary, make sure that all has a namespace
     13- If caller supplies key dictionary, make sure that all has a namespace.
    1214
    1315Version 3.8 (2006-02-17)
  • trunk/docs/future.txt

    r268 r287  
    1818----------------
    1919
    20 - ByteA support
    21   (http://mailman.vex.net/pipermail/pygresql/2004-September/001338.html)
    2220- Notice handling
    2321  (http://mailman.vex.net/pipermail/pygresql/2005-November/001530.html)
     
    2826
    2927- Make SQLSTATE error codes available.
     28- Make use of PQexecParams() and PQprepare(). This could speed up
     29  executemany() and allow retrieving binary data directly by setting
     30  the resultFormat parameter to one.
    3031- Users should be able to register their own types with _pg.
    3132- I would like a new method that returns a dictionary
  • trunk/docs/pg.txt

    r251 r287  
    8282
    8383Description:
    84   This method opens a connection to a specified database on a given
     84  This function opens a connection to a specified database on a given
    8585  PostgreSQL server. You can use keywords here, as described in the
    8686  Python tutorial. The names of the keywords are the name of the
     
    9595  con2 = pg.connect(dbname='testdb', host='localhost', user='bob')
    9696
    97 
    9897get_defhost, set_defhost - default server host [DV]
    9998---------------------------------------------------
     
    283282  `None` is supplied as parameter, environment variables will be used in
    284283  future connections. It returns the previous setting for default host.
     284
     285escape_string - escape a string for use within SQL
     286--------------------------------------------------
     287Syntax::
     288
     289  escape_string(string)
     290
     291Parameters:
     292  :string: the string that is to be escaped
     293
     294Return type:
     295  :str: the escaped string
     296
     297Exceptions raised:
     298  :TypeError: bad argument type, or too many arguments
     299
     300Description:
     301  This function escapes a string for use within an SQL command.
     302  This is useful when inserting data values as literal constants
     303  in SQL commands. Certain characters (such as quotes and backslashes)
     304  must be escaped to prevent them from being interpreted specially
     305  by the SQL parser. `escape_string` performs this operation.
     306
     307.. caution:: It is especially important to do proper escaping when
     308  handling strings that were received from an untrustworthy source.
     309  Otherwise there is a security risk: you are vulnerable to "SQL injection"
     310  attacks wherein unwanted SQL commands are fed to your database.
     311
     312Example::
     313
     314  name = raw_input("Name? ")
     315  phone = con.query("select phone from employees"
     316    " where name='%s'" % escape_string(name)).getresult()
     317
     318escape_bytea - escape binary data for use within SQL as type `bytea`
     319--------------------------------------------------------------------
     320Syntax::
     321
     322  escape_bytea(datastring)
     323
     324Parameters:
     325  :datastring: string containing the binary data that is to be escaped
     326
     327Return type:
     328  :str: the escaped string
     329
     330Exceptions raised:
     331  :TypeError: bad argument type, or too many arguments
     332
     333Description:
     334  Escapes binary data for use within an SQL command with the type `bytea`.
     335  As with `escape_string`, this is only used when inserting data directly
     336  into an SQL command string.
     337
     338Example::
     339
     340  picture = file('garfield.gif', 'rb').read()
     341  con.query("update pictures set img='%s' where name='Garfield'"
     342    % escape_bytea(picture))
     343
     344unescape_bytea -- unescape `bytea` data that has been retrieved as text
     345-----------------------------------------------------------------------
     346Syntax::
     347
     348  unescape_bytea(string)
     349
     350Parameters:
     351  :datastring: the `bytea` data string that has been retrieved as text
     352
     353Return type:
     354  :str: string containing the binary data
     355
     356Exceptions raised:
     357  :TypeError: bad argument type, or too many arguments
     358
     359Description:
     360  Converts an escaped string representation of binary data into binary
     361  data - the reverse of `escape_bytea`. This is needed when retrieving
     362  `bytea` data with the `getresult()` or `dictresult()` method.
     363
     364Example::
     365
     366  picture = unescape_bytea(con.query(
     367    "select img from pictures where name='Garfield'").getresult[0][0])
     368  file('garfield.gif', 'wb').write(picture)
    285369
    286370Module constants
     
    342426  (i.e., is not a some kind of SELECT statement), it returns `None`.
    343427  Otherwise, it returns a `pgqueryobject` that can be accessed via the
    344   getresult() or dictresult() method or simply printed.
     428  `getresult()` or `dictresult()` method or simply printed.
    345429
    346430reset - resets the connection
     
    817901  This method deletes the row from a table. It deletes based on the OID
    818902  as munged as described above.
     903
     904escape_string - escape a string for use within SQL
     905--------------------------------------------------
     906Syntax::
     907
     908  escape_string(string)
     909
     910Parameters:
     911  :string: the string that is to be escaped
     912
     913Return type:
     914  :str: the escaped string
     915
     916Description:
     917  See the module function with the same name.
     918
     919escape_bytea - escape binary data for use within SQL as type `bytea`
     920--------------------------------------------------------------------
     921Syntax::
     922
     923  escape_bytea(datastring)
     924
     925Parameters:
     926  :datastring: string containing the binary data that is to be escaped
     927
     928Return type:
     929  :str: the escaped string
     930
     931Description:
     932  See the module function with the same name.
     933
     934unescape_bytea -- unescape `bytea` data that has been retrieved as text
     935-----------------------------------------------------------------------
     936Syntax::
     937
     938  unescape_bytea(string)
     939
     940Parameters:
     941  :datastring: the `bytea` data string that has been retrieved as text
     942
     943Return type:
     944  :str: string containing the binary data
     945
     946Description:
     947  See the module function with the same name.
    819948
    820949
     
    11631292  The `oid` attribute is very interesting because it allow you reuse the OID
    11641293  later, creating the `pglarge` object with a `pgobject` getlo() method call.
    1165 
Note: See TracChangeset for help on using the changeset viewer.