I'm confident that SQLAlchemy has the potential to be the best database abstraction layer out there. However, I found the docs impervious and frustrating. Some of the examples are given in a way that's quite unhelpful - they could be constructed to distinguish the way it works from other assumptions you could make and generally they're not. When things break, the error messages are unhelpful.

I eventually got to the stage where I had a product built on top of it, working, but I still didn't feel like I knew the framework fluently. I've never been in that position before. Frustating, because it means if I do more work on that codebase I'll either have to struggle through again or else throw it away and write on top of something else.

ORM is supposed to be good for nailing the right schema and then abstracting it away without a performance hit. That's what I get with Cayenne. I found the opposite with sqlalchemy - it's more difficult than it would have been for me to have just written the queries inline, or rolled my own simple ORM. I think it's because it's just too thick - unusual for a python framework - usually they're the opposite.

It's been a year since I looked at it so I'm a bit vague above, but I gave it a go for over two years on and off.

I am also confident that SQLAlchemy is the best ORM out there (though I'd like to try LINQ). The documentation has been improving rapidly, you should give the .5 branch a try.

I agree that it needs to be improved, but that's largely because the product is so powerful and complex, writing sufficient documentation is a herculean effort in and of itself.

thanks, I agree with you on all your points. I just assumed all ORMs were like that :)

"SQLAlchemy: How is it inaccessible? Are you referring to the docs which even after a year of using I find frustrating? "

If you have significant experience with Hibernate, you can pick up SQLAlchemy very fast. One of my friends wanted to switch from Django ORM to SQLAlchemy but was being frustrated by lack of SA documents. I had him build a couple of throwaway systems (just domain model and databse - no web framework gymnastics - which are very painful in Java) with Hibernate and also read through Martin Fowler's "Enterprise Patterns" book to pick up some of the terminology (e.g:- Unit Of Work). This seemed to work. Just throwing it out there, fwiw.