From cce281e05671c8b026470927e4e64784aa4ce2d6 Mon Sep 17 00:00:00 2001
From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sun, 12 Aug 2007 16:19:52 +0000
Subject: [PATCH] added a brief migration guide

---
 doc/build/content/intro.txt | 80 +++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/doc/build/content/intro.txt b/doc/build/content/intro.txt
index 9c57a6163c..b28e399eab 100644
--- a/doc/build/content/intro.txt
+++ b/doc/build/content/intro.txt
@@ -77,4 +77,84 @@ This documentation covers SQLAlchemy version 0.4.  If you're working on a system
      >>> sqlalchemy.__version__ # doctest: +SKIP
      0.4.0
 
+## 0.3 to 0.4 Migration {@name=migration}
 
+From version 0.3 to version 0.4 of SQLAlchemy, some conventions have changed.  Most of these conventions are available in the most recent releases of the 0.3 series starting with version 0.3.9, so that you can make a 0.3 application compatible with 0.4 in most cases.
+
+This section will detail only those things that have changed in a backwards-incompatible manner.  For a full overview of everything that's new and changed, see [WhatsNewIn04](http://www.sqlalchemy.org/trac/wiki/WhatsNewIn04).
+
+### ORM Package is now sqlalchemy.orm {@name=imports}
+
+All symbols related to the SQLAlchemy Object Relational Mapper, i.e. names like `mapper()`, `relation()`, `backref()`, `create_session()` `synonym()`, `eagerload()`, etc. are now only in the `sqlalchemy.orm` package, and **not** in `sqlalchemy`.  So if you were previously importing everything on an asterisk:
+
+    {python}
+    from sqlalchemy import *
+    
+You should now import separately from orm:
+
+    {python}
+    from sqlalchemy import *
+    from sqlalchemy.orm import *
+    
+Or more commonly, just pull in the names you'll need:
+
+    {python}
+    from sqlalchemy import create_engine, MetaData, Table, Column, types
+    from sqlalchemy.orm import mapper, relation, backref, create_session()
+
+### BoundMetaData is now MetaData {@name=metadata}
+
+The `BoundMetaData` name is removed.  Now, you just use `MetaData`.  Additionally, the `engine` parameter/attribute is now called `bind`, and `connect()` is deprecated:
+
+    {python}
+    # plain metadata
+    meta = MetaData()
+    
+    # metadata bound to an engine
+    meta = MetaData(engine)
+    
+    # bind metadata to an engine later
+    meta.bind = engine
+    
+Additionally, `DynamicMetaData` is now known as `ThreadLocalMetaData`.
+
+### Some existing select() methods become genreative {@name=generative}
+
+The methods `correlate()`, `order_by()`, and `group_by()` on the `select()` construct now return a **new** select object, and do not change the original one.  Additionally, the generative methods `where()`, `column()`, `distinct()`, and several others have been added:
+
+    {python}
+    s = table.select().order_by(table.c.id).where(table.c.x==7)
+    result = engine.execute(s)
+
+### collection_class behavior is changed {@name=collection}
+
+If you've been using the `collection_class` option on `mapper()`, the requirements for instrumented collections have changed.  For an overview, see [advdatamapping_relation_collections](rel:advdatamapping_relation_collections).
+
+### All "engine", "bind_to", "connectable" Keyword Arguments Changed to "bind" {@name=bind}
+
+This is for create/drop statements, sessions, SQL constructs, metadatas:
+
+    {python}
+    myengine = create_engine('sqlite://')
+
+    meta = MetaData(myengine)
+
+    meta2 = MetaData()
+    meta2.bind = myengine
+
+    session = create_session(bind=myengine)
+
+    statement = select([table], bind=myengine)
+    
+    meta.create_all(bind=myengine)
+    
+### All "type" Keyword Arguments Changed to "type_" {@name=type}
+
+This mostly applies to SQL constructs where you pass a type in:
+
+    {python}
+    s = select([mytable], mytable.c.x=bindparam(y, type_=DateTime))
+    
+    func.now(type_=DateTime)
+    
+    
\ No newline at end of file
-- 
2.47.3