I am leaving up the link to 0.2.7 in addition to this one, since 0.2.8 has a series of major behavioral changes. these changes should be backwards compatible, but its very possible that some applications might need adjustment or that some of the new features might have undiscovered bugs. While there are some people using these features out of SVN, i feel like until a whole lot of people get on the new features we're not totally going to know what might come up (hence the release...).
The major changes are: - casing/quoting. while 0.2.7 had the "quote=True" flag, it became apparent that this really didnt go far enough for many scenarios where SA just has to be more on top of when quoting should be applied, including query generation and also table reflection. So 0.2.8 will, in most normal cases, apply quoting to identifiers that are known SQL identifiers (like "desc", "order", etc.), and will also apply quoting to any identifier that contains uppercase letters (or MixedCase). As it turns out this was a little complicated because the quoting also has to extend out into automatically generated column labels and table alias names. Postgres seems to be the most sensitive to these issues, since PG automatically folds all non- quoted identifiers to all lowercase, and when identifiers are suddenly quoted its essentially a whole new set of names. The docs include information on how you can affect the quoting. It is hoped that in most cases developers wont have to care about quoting at all, it will just happen automatically as needed. To turn most quoting off, specify "case_sensitive=False" at the MetaData, Table, or Column level. to force quoting for a particular column or tablename, specify "quote=True". To specify case sensitivity for an all-lowercase identifier name, use "case_sensitive=True". The "case_sensitive" flag defaults to whether or not the identifer contains any uppercase characters. - orphan detection. The unit of work is now going to be more aggressive in detecting "orphan" items in the session when it flushes. An "orphan" only occurs when a relationship has been set up with a cascade that includes "delete-orphan". If you create a new instance of an object and save it to the session, and the object is not attached to a parent object which specifies the "delete-orphan" cascade rule, youll get an error on flush, which will specify the parent class name and the name of the attribute to which the orphan should be attached. Of significance here is that you can no longer set the "delete- orphan" cascade rule on a self-referential relationship; note that this includes anywhere you might be using the old "private=True" flag. If you do, it raises an error upon configuration. The reason for this is somewhat obvious; if you create a root object that points to a set of child objects, and that relationship has "delete-orphan" on it, the root is by definition an "orphan". If you are actually using a self-referential mapper where all instances are always circularly linked, well congratulations on getting SA to do that, and im sure you can work around the lack of "delete-orphan" in that case as well :). - lazy loads only occur for persistent objects. this was already sort of the standard documented behavior, however there was a "bug" where a lazy loader would still fire off if you constructed a new object and set its primary key identifier manually. I have a strong suspicion that people might be relying on this behavior, since questions related to it have come up a lot. In fact this breaks the bi-directional relationship handling, and in light of the more aggressive orphan detection, its more important that bi-directional relationships work correctly, else the unit of work starts deleting things. I am trying to come up with a set of specific reasons why i dont like the idea of "setting foo_id on an object should automatically load/attach the corresponding object" and am collecting my thoughts on this at http://www.sqlalchemy.org/trac/wiki/ WhyDontForeignKeysLoadData . - improvements to how to send custom connect arguments to DBAPI. OK, I lied, there is some slight API breakage here. If you have connect arguments you want to send to the DBAPI's connect() function, they can as usual be query strings on the url (i.e. dbtype://url? param1=foo¶m2=bar), or in python they can be sent via a dictionary called "create_args", so that they do not conflict with the keyword arguments being sent to the underlying dialect. for those of you using custom connection creator functions, you can also specify the "creator" keyword argument directly to create_engine now. The options are documented in the database engine chapter under "Custom DBAPI keyword arguments" and "Database Engine Options". - major connection pool enhancements. Hopefully, this shouldnt affect anyone. But the connection pool, being the one place in SA where we have to deal with extensive threading and garbage collection issues, has always been thorny. This connection pool should now be "smart" enough to automatically reconnect to the database if the database has been stopped and started again. It also includes a very important parameter "recycle", which is sent to create_engine as "pool_recycle". this is a time limit whereby a connection will be automatically closed and reconnected. it defaults to 3600 seconds or one hour. this also gives some protection against crashing databases, and it is absolutely needed for MySQL where connections are automatically closed after 8 hours of inactivity. So, ive tested it, added new unit tests, and it should "just work", but in case it "just doesnt work", drop back to 0.2.7 and post some tickets on trac. - postgres uses pg_schema tables instead of information_schema for reflection. this seems to work OK, also fixed the unit tests to not break on PG8.1. heres the changes.... 0.2.8 - cleanup on connection methods + documentation. custom DBAPI arguments specified in query string, 'connect_args' argument to 'create_engine', or custom creation function via 'creator' function to 'create_engine'. - added "recycle" argument to Pool, is "pool_recycle" on create_engine, defaults to 3600 seconds; connections after this age will be closed and replaced with a new one, to handle db's that automatically close stale connections [ticket:274] - changed "invalidate" semantics with pooled connection; will instruct the underlying connection record to reconnect the next time its called. "invalidate" will also automatically be called if any error is thrown in the underlying call to connection.cursor(). this will hopefully allow the connection pool to reconnect to a database that had been stopped and started without restarting the connecting application [ticket:121] - eesh ! the tutorial doctest was broken for quite some time. - add_property() method on mapper does a "compile all mappers" step in case the given property references a non-compiled mapper (as it did in the case of the tutorial !) - [ticket:277] check for pg sequence already existing before create - if a contextual session is established via MapperExtension.get_session (as it is using the sessioncontext plugin, etc), a lazy load operation will use that session by default if the parent object is not persistent with a session already. - lazy loads will not fire off for an object that does not have a database identity (why? see http://www.sqlalchemy.org/trac/wiki/WhyDontForeignKeysLoadData) - unit-of-work does a better check for "orphaned" objects that are part of a "delete-orphan" cascade, for certain conditions where the parent isnt available to cascade from. - mappers can tell if one of their objects is an "orphan" based on interactions with the attribute package. this check is based on a status flag maintained for each relationship when objects are attached and detached from each other. - it is now invalid to declare a self-referential relationship with "delete-orphan" (as the abovementioned check would make them impossible to save) - improved the check for objects being part of a session when the unit of work seeks to flush() them as part of a relationship.. - [ticket:280] statement execution supports using the same BindParam object more than once in an expression; simplified handling of positional parameters. nice job by Bill Noon figuring out the basic idea. - postgres reflection moved to use pg_schema tables, can be overridden with use_information_schema=True argument to create_engine [ticket:60], [ticket:71] - added case_sensitive argument to MetaData, Table, Column, determines itself automatically based on if a parent schemaitem has a non-None setting for the flag, or if not, then whether the identifier name is all lower case or not. when set to True, quoting is applied to identifiers with mixed or uppercase identifiers. quoting is also applied automatically in all cases to identifiers that are known to be reserved words or contain other non- standard characters. various database dialects can override all of this behavior, but currently they are all using the default behavior. tested with postgres, mysql, sqlite, oracle. needs more testing with firebird, ms-sql. part of the ongoing work with [ticket:155] - unit tests updated to run without any pysqlite installed; pool test uses a mock DBAPI - urls support escaped characters in passwords [ticket:281] - added limit/offset to UNION queries (though not yet in oracle) - added "timezone=True" flag to DateTime and Time types. postgres so far will convert this to "TIME[STAMP] (WITH|WITHOUT) TIME ZONE", so that control over timezone presence is more controllable (psycopg2 returns datetimes with tzinfo's if available, which can create confusion against datetimes that dont). - fix to using query.count() with distinct, **kwargs with SelectResults count() [ticket:287] - deregister Table from MetaData when autoload fails; [ticket:289] - import of py2.5s sqlite3 [ticket:293] - unicode fix for startswith()/endswith() [ticket:296] ------------------------------------------------------------------------- Using Tomcat but need to do more? Need to support web services, security? Get stuff done quickly with pre-integrated technology to make your job easier Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642 _______________________________________________ Sqlalchemy-users mailing list Sqlalchemy-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/sqlalchemy-users
