Mike Bayer avatar Mike Bayer committed fa0ca1d

added a brief migration guide

Comments (0)

Files changed (1)

doc/build/content/intro.txt

      >>> 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)
+    
+    
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.