- postgres docstring

- insert/update/delete are documented generatively
- values({}) is no longer deprecated, thus enabling
unicode/Columns as keys

2 files changed, 102 insertions, 23 deletions

diff --git a/lib/sqlalchemy/databases/oracle.py b/lib/sqlalchemy/databases/oracle.py
index d71b129d1..72a0bb265 100644
--- a/lib/sqlalchemy/databases/oracle.py
+++ b/lib/sqlalchemy/databases/oracle.py
@@ -8,39 +8,44 @@
 Oracle version 8 through current (11g at the time of this writing) are supported.
 
 Driver
+------
 
 The Oracle dialect uses the cx_oracle driver, available at 
-http://python.net/crew/atuining/cx_Oracle/ .   The dialect has several behaviors 
+http://cx-oracle.sourceforge.net/ .   The dialect has several behaviors 
 which are specifically tailored towards compatibility with this module.
 
 Connecting
+----------
 
 Connecting with create_engine() uses the standard URL approach of 
-oracle://user:pass@host:port/dbname[?key=value&key=value...].  If dbname is present, the 
+``oracle://user:pass@host:port/dbname[?key=value&key=value...]``.  If dbname is present, the 
 host, port, and dbname tokens are converted to a TNS name using the cx_oracle 
-makedsn() function.  Otherwise, the host token is taken directly as a TNS name.
+:func:`makedsn()` function.  Otherwise, the host token is taken directly as a TNS name.
 
 Additional arguments which may be specified either as query string arguments on the
-URL, or as keyword arguments to create_engine() include:
+URL, or as keyword arguments to :func:`~sqlalchemy.create_engine()` are:
 
-   mode - This is given the string value of SYSDBA or SYSOPER, or alternatively an
-   integer value.  This value is only available as a URL query string argument.
+* *allow_twophase* - enable two-phase transactions.  Defaults to ``True``.
 
-   allow_twophase - enable two-phase transactions.  This feature is not yet supported.
+* *auto_convert_lobs* - defaults to True, see the section on LOB objects.
 
-   threaded - defaults to True with SQLAlchemy, enable multithreaded access to 
-   cx_oracle connections.
+* *auto_setinputsizes* - the cx_oracle.setinputsizes() call is issued for all bind parameters.
+  This is required for LOB datatypes but can be disabled to reduce overhead.  Defaults
+  to ``True``.
 
-   use_ansi - defaults to True, use ANSI JOIN constructs (see the section on Oracle 8).
+* *mode* - This is given the string value of SYSDBA or SYSOPER, or alternatively an
+  integer value.  This value is only available as a URL query string argument.
 
-   auto_convert_lobs - defaults to True, see the section on LOB objects.
+* *threaded* - enable multithreaded access to cx_oracle connections.  Defaults
+  to ``True``.  Note that this is the opposite default of cx_oracle itself.
 
-   auto_setinputsizes - the cx_oracle.setinputsizes() call is issued for all bind parameters.
-   This is required for LOB datatypes but can be disabled to reduce overhead.
+* *use_ansi* - Use ANSI JOIN constructs (see the section on Oracle 8).  Defaults
+  to ``True``.  If ``False``, Oracle-8 compatible constructs are used for joins.
 
-   optimize_limits - defaults to False, see the section on LIMIT/OFFSET.
+* *optimize_limits* - defaults to ``False``. see the section on LIMIT/OFFSET.
 
 Auto Increment Behavior
+-----------------------
 
 SQLAlchemy Table objects which include integer primary keys are usually assumed to have
 "autoincrementing" behavior, meaning they can generate their own primary key values upon
@@ -63,6 +68,7 @@ This step is also required when using table reflection, i.e. autoload=True::
   ) 
 
 LOB Objects
+-----------
 
 cx_oracle presents some challenges when fetching LOB objects.  A LOB object in a result set
 is presented by cx_oracle as a cx_oracle.LOB object which has a read() method.  By default, 
@@ -84,6 +90,7 @@ without raising cursor errors.  The conversion of LOB in all cases, as well as t
 of LOB objects, can be disabled using auto_convert_lobs=False.  
 
 LIMIT/OFFSET Support
+--------------------
 
 Oracle has no support for the LIMIT or OFFSET keywords.  Whereas previous versions of SQLAlchemy
 used the "ROW NUMBER OVER..." construct to simulate LIMIT/OFFSET, SQLAlchemy 0.5 now uses 
@@ -94,18 +101,20 @@ this was stepping into the bounds of optimization that is better left on the DBA
 prefix can be added by enabling the optimize_limits=True flag on create_engine().
 
 Two Phase Transaction Support
+-----------------------------
 
-Two Phase transactions are partially implemented using XA transactions but at the time of this
-writing have not been successfully tested.  The author of cx_oracle also stated that he's never
-seen them work so this may be a cx_oracle issue.
+Two Phase transactions are implemented using XA transactions.  Success has been reported of them
+working successfully but this should be regarded as an experimental feature.
 
 Oracle 8 Compatibility
+----------------------
 
 When using Oracle 8, a "use_ansi=False" flag is available which converts all
 JOIN phrases into the WHERE clause, and in the case of LEFT OUTER JOIN
 makes use of Oracle's (+) operator.
 
 Synonym/DBLINK Reflection
+-------------------------
 
 When using reflection with Table objects, the dialect can optionally search for tables
 indicated by synonyms that reference DBLINK-ed tables by passing the flag 
diff --git a/lib/sqlalchemy/databases/postgres.py b/lib/sqlalchemy/databases/postgres.py
index 57620c007..320c749bc 100644
--- a/lib/sqlalchemy/databases/postgres.py
+++ b/lib/sqlalchemy/databases/postgres.py
@@ -6,17 +6,87 @@
 
 """Support for the PostgreSQL database.
 
-PostgreSQL supports partial indexes. To create them pass a posgres_where
+Driver
+------
+
+The psycopg2 driver is supported, available at http://pypi.python.org/pypi/psycopg2/ .
+The dialect has several behaviors  which are specifically tailored towards compatibility 
+with this module.
+
+Note that psycopg1 is **not** supported.
+
+Connecting
+----------
+
+URLs are of the form `postgres://user@password@host:port/dbname[?key=value&key=value...]`.
+
+Postgres-specific keyword arguments which are accepted by :func:`~sqlalchemy.create_engine()` are:
+
+* *server_side_cursors* - Enable the usage of "server side cursors" for SQL statements which support
+  this feature.  What this essentially means from a psycopg2 point of view is that the cursor is 
+  created using a name, e.g. `connection.cursor('some name')`, which has the effect that result rows
+  are not immediately pre-fetched and buffered after statement execution, but are instead left 
+  on the server and only retrieved as needed.    SQLAlchemy's :class:`~sqlalchemy.engine.base.ResultProxy`
+  uses special row-buffering behavior when this feature is enabled, such that groups of 100 rows 
+  at a time are fetched over the wire to reduce conversational overhead.
+
+Sequences/SERIAL
+----------------
+
+Postgres supports sequences, and SQLAlchemy uses these as the default means of creating
+new primary key values for integer-based primary key columns.   When creating tables, 
+SQLAlchemy will issue the ``SERIAL`` datatype for integer-based primary key columns, 
+which generates a sequence corresponding to the column and associated with it based on
+a naming convention.
+
+To specify a specific named sequence to be used for primary key generation, use the
+:func:`~sqlalchemy.schema.Sequence` construct::
+
+    Table('sometable', metadata, 
+            Column('id', Integer, Sequence('some_id_seq'), primary_key=True)
+        )
+
+Currently, when SQLAlchemy issues a single insert statement, to fulfill the contract of
+having the "last insert identifier" available, the sequence is executed independently
+beforehand and the new value is retrieved, to be used in the subsequent insert.  Note
+that when an :func:`~sqlalchemy.sql.expression.insert()` construct is executed using 
+"executemany" semantics, the sequence is not pre-executed and normal PG SERIAL behavior
+is used.
+
+Postgres 8.3 supports an ``INSERT...RETURNING`` syntax which SQLAlchemy supports 
+as well.  A future release of SQLA will use this feature by default in lieu of 
+sequence pre-execution in order to retrieve new primary key values, when available.
+
+INSERT/UPDATE...RETURNING
+-------------------------
+
+The dialect supports PG 8.3's ``INSERT..RETURNING`` and ``UPDATE..RETURNING`` syntaxes, 
+but must be explicitly enabled on a per-statement basis::
+
+    # INSERT..RETURNING
+    result = table.insert(postgres_returning=[table.c.col1, table.c.col2]).\\
+        values(name='foo')
+    print result.fetchall()
+    
+    # UPDATE..RETURNING
+    result = table.update(postgres_returning=[table.c.col1, table.c.col2]).\\
+        where(table.c.name=='foo').values(name='bar')
+    print result.fetchall()
+
+Indexes
+-------
+
+PostgreSQL supports partial indexes. To create them pass a postgres_where
 option to the Index constructor::
 
   Index('my_index', my_table.c.id, postgres_where=tbl.c.value > 10)
 
-PostgreSQL 8.2+ supports returning a result set from inserts and updates.
-To use this pass the column/expression list to the postgres_returning
-parameter when creating the queries::
+Transactions
+------------
+
+The Postgres dialect fully supports SAVEPOINT and two-phase commit operations.
+
 
-  raises = tbl.update(empl.c.sales > 100, values=dict(salary=empl.c.salary * 1.1),
-    postgres_returning=[empl.c.id, empl.c.salary]).execute().fetchall()
 """
 
 import decimal, random, re, string