a big, unmissable, green box describing the caveats of String() and Sequence.

4 files changed, 76 insertions, 10 deletions

diff --git a/doc/build/intro.rst b/doc/build/intro.rst
index 7e0207407..f0bf9ebbc 100644
--- a/doc/build/intro.rst
+++ b/doc/build/intro.rst
@@ -31,6 +31,11 @@ Main Documentation
 * :ref:`types` - Datatypes included with SQLAlchemy, their functions, as well as how to create your own types.
 * :ref:`plugins` - Included addons for SQLAlchemy
 
+Code Examples
+=============
+
+Working code examples are included in the SQLAlchemy distribution, and there are also usage recipes on the SQLAlchemy wiki.   A description of all the included example applications is at :ref:`examples_toplevel`.
+
 API Reference
 =============
 
diff --git a/doc/build/ormtutorial.rst b/doc/build/ormtutorial.rst
index 24322fab6..aaf69cf02 100644
--- a/doc/build/ormtutorial.rst
+++ b/doc/build/ormtutorial.rst
@@ -56,11 +56,34 @@ Next, we can issue CREATE TABLE statements derived from our table metadata, by c
     ()
     COMMIT
 
-Users familiar with the syntax of CREATE TABLE may notice that the VARCHAR columns were generated without a length; on SQLite, this is a valid datatype, but on most databases it's not allowed.  So if running this tutorial on a database such as PostgreSQL or MySQL, and you wish to use SQLAlchemy to generate the tables, a "length" may be provided to the ``String`` type as below::
-
-    Column('name', String(50))
-
-The length field on ``String``, as well as similar precision/scale fields available on ``Integer``, ``Numeric``, etc. are not referenced by SQLAlchemy other than when creating tables.
+.. note:: Users familiar with the syntax of CREATE TABLE may notice that the
+    VARCHAR columns were generated without a length; on SQLite and Postgresql,
+    this is a valid datatype, but on others, it's not allowed. So if running
+    this tutorial on one of those databases, and you wish to use SQLAlchemy to
+    issue CREATE TABLE, a "length" may be provided to the ``String`` type as
+    below::
+
+        Column('name', String(50))
+
+    The length field on ``String``, as well as similar precision/scale fields
+    available on ``Integer``, ``Numeric``, etc. are not referenced by
+    SQLAlchemy other than when creating tables.
+
+    Additionally, Firebird and Oracle require sequences to generate new
+    primary key identifiers, and SQLAlchemy doesn't generate or assume these
+    without being instructed. For that, you use the ``Sequence`` construct::
+
+        from sqlalchemy import Sequence
+        Column('id', Integer, Sequence('user_id_seq'), primary_key=True)
+
+    A full, foolproof ``Table`` is therefore::
+
+        users_table = Table('users', metadata,
+           Column('id', Integer, Sequence('user_id_seq'), primary_key=True),
+           Column('name', String(50)),
+           Column('fullname', String(50)),
+           Column('password', String(12))
+        )
 
 Define a Python Class to be Mapped
 ===================================
diff --git a/doc/build/sqlexpression.rst b/doc/build/sqlexpression.rst
index c34e6e790..0870bc848 100644
--- a/doc/build/sqlexpression.rst
+++ b/doc/build/sqlexpression.rst
@@ -84,11 +84,34 @@ Next, to tell the ``MetaData`` we'd actually like to create our selection of tab
     ()
     COMMIT
 
-Users familiar with the syntax of CREATE TABLE may notice that the VARCHAR columns were generated without a length; on SQLite, this is a valid datatype, but on most databases it's not allowed.  So if running this tutorial on a database such as PostgreSQL or MySQL, and you wish to use SQLAlchemy to generate the tables, a "length" may be provided to the ``String`` type as below::
-
-    Column('name', String(50))
-
-The length field on ``String``, as well as similar fields available on ``Integer``, ``Numeric``, etc. are not referenced by SQLAlchemy other than when creating tables.
+.. note:: Users familiar with the syntax of CREATE TABLE may notice that the
+    VARCHAR columns were generated without a length; on SQLite and Postgresql,
+    this is a valid datatype, but on others, it's not allowed. So if running
+    this tutorial on one of those databases, and you wish to use SQLAlchemy to
+    issue CREATE TABLE, a "length" may be provided to the ``String`` type as
+    below::
+
+        Column('name', String(50))
+
+    The length field on ``String``, as well as similar precision/scale fields
+    available on ``Integer``, ``Numeric``, etc. are not referenced by
+    SQLAlchemy other than when creating tables.
+
+    Additionally, Firebird and Oracle require sequences to generate new
+    primary key identifiers, and SQLAlchemy doesn't generate or assume these
+    without being instructed. For that, you use the ``Sequence`` construct::
+
+        from sqlalchemy import Sequence
+        Column('id', Integer, Sequence('user_id_seq'), primary_key=True)
+
+    A full, foolproof ``Table`` is therefore::
+
+        users_table = Table('users', metadata,
+           Column('id', Integer, Sequence('user_id_seq'), primary_key=True),
+           Column('name', String(50)),
+           Column('fullname', String(50)),
+           Column('password', String(12))
+        )
 
 Insert Expressions
 ==================
diff --git a/doc/build/static/docs.css b/doc/build/static/docs.css
index 00aa48624..f60eef3a6 100644
--- a/doc/build/static/docs.css
+++ b/doc/build/static/docs.css
@@ -149,6 +149,21 @@ li.toctree-l1 ul li li
 }
 
 
+div.note  {
+    background-color:#EEFFEF;
+}
+
+div.admonition {
+    border:1px solid #CCCCCC;
+    margin:5px 5px 5px 5px;
+    padding:5px 5px 5px 35px;
+    font-size:.9em;
+}
+
+div.admonition .admonition-title {
+    font-weight:bold;
+}
+
 .bottomnav {
     background-color:#FBFBEE;
     border:1px solid #CCCCCC;