I’ve been wanting to start doing some book reviews for a while, so here goes. The folks at Apress have been kind enough to send me review copies of a couple books, so I’m going to start with one of them. First up, Pro Active Record.
Title: Pro Active Record: Databases with Ruby and Rails
Authors: Kevin Marshall, Chad Pytel, Jon Yurek
Publisher: Apress
My first thought at seeing this book was, “Hey, a book all about ActiveRecord! Cool!” It’s nice to finally see a volume dedicated to ActiveRecord, since it’s my favorite part of Rails. However, this book ends up being something of a mixed bag. There’s a lot of good information in it, and it does a decent job of covering all the basics. There are even some excellent parts here and there. But the book also has some problems, so it’s hard for me to give it an unequivocal recommendation. Nevertheless, it does have value and fills a needed spot, so it may be what you’re looking for.
The Good
Let’s start by taking a look at what the book provides. As I said, it covers all the basics.
Pro Active Record starts with a good introduction to ActiveRecord, going over a bit of the history, how to install it, and shows a small example program. The best part of this chapter is the section that shows all the configuration settings for the different database adapters. It’s nice to see all that in one place.
Chapter 2 digs into the foundation of ActiveRecord and how it maps objects to SQL. It covers CRUD operations, transactions, and locking. I like how it is full of examples that show an AR API call and the resulting SQL.
Chapter 3 is entitled Setting Up Your Database, but it’s mainly about using migrations. It does however start with a good summary of the main ActiveRecord conventions for table naming and structure. It would be even better to see a summary of all the magic fields in one place (e.g. features like counter cache and optimistic locking).
Chapter 4 is where things start to get interesting. This chapter gets into the meat and potatoes (or granola and tofu for us Californians) of ActiveRecord. The three main topics are Callbacks (what I call the life-cycle features), Associations, and Validations. This is where you start to get a feel for what using ActiveRecord is like. Every major feature comes with some code examples, which is a good thing, though as contrived examples go some of them are pretty uninspired. Probably the biggest weakness in terms of content is that the section on associations doesn’t show more than the most basic use cases. ActiveRecord associations are a rich topic and could easily cover a whole chapter, if not several. But for a beginner’s book on ActiveRecord, this is probably enough. Though not seeing any mention of association extensions made me sad.
Chapter 5 is like the whole book in microcosm. Some good stuff, some stupid stuff, but not a waste of time. It covers some “bonus features” of ActiveRecord. The section on observers was an interesting start, but the topic deserves more than just one page. On the other hand, there are thirteen whole pages wasted covering the List, Tree and Nested Set features that everyone has known for ages were slated to be pulled from ActiveRecord (and were just extracted and turned into plugins). The section on aggregations is adequate, but the examples obfuscate more than they reveal. And yet, the chapter recovers and even shines with one of the best discussions of metaprogramming in Ruby and ActiveRecord that I’ve yet to read. Really, I’d almost say it’s worth it to get this book just for the Extending Active Record section of this chapter. The thing that makes it work is how they show a problem, then an evolving series of solutions that do similar things but with more sophistication as they progress. At each step there is a discussion of the advantages and drawbacks of each approach. If the whole book was up to this standard, it would be a no-brainer to recommend it to everyone.
Chapter 6 introduces ActiveRecord testing and debugging. It includes a rather light discussion of writing tests and the basics of using fixtures. Most of the testing section covers the assertion methods in Test::Unit. While this book’s focus isn’t testing, it’s a shame that there weren’t at least a few good examples or some deeper how-to discussion. The world really needs a good book on testing Rails (so get off your butts, guys - you know who you are!). There follows a section that lists and describes the ActiveRecord exception classes. Finally there’s a section on debugging tips, which is mainly about using logging. I was disappointed the chapter didn’t include any mention of using irb (or the Rails console) for experimenting with code or debugging, and that there was no mention of using the Ruby debugger.
Chapter 7 addresses how to work with legacy databases. This is one of the trickiest things to do with ActiveRecord, because you don’t get to go with the flow and have to do a lot more configuration than normal. The first part of the chapter describes the various configuration methods ActiveRecord provides to override its default conventions, and it’s great to see them listed in one place like that. Then there is a slow dive into the bowels of ActiveRecord, covering find_by_sql and some of the low-level database APIs. There’s also a section on import/export of your favorite interchange formats (xml, yaml, csv). What is missing is any discussion of how to map typical un-Rails-ish database usage patterns into ActiveRecord. For example, how to deal with non-integer primary keys, composite keys, foreign key constraints, enums, etc. That would have made this chapter a real winner.
Chapter 8 is the catch-all for everything that didn’t fit in the other chapters. It has a section on reading the ActiveRecord source code that provides a roadmap for finding your way around. There’s a decent discussion of various alternatives to ActiveRecord (other Ruby ORM packages), though it misses some recent additions to the field like Sequel and DataMapper. The FAQ section is pretty good, and provided a number of answers that were missing from previous chapters. One answer even includes some code from my own blog (thanks for giving the proper attribution!).
Finally, there is an Appendix that documents the core ActiveRecord API.
Looking back, that’s a pretty good chunk of information on ActiveRecord, and probably enough to get anyone started. It’s also very readable (though all the anecdotes about Kevin got to be a bit much). I thought the organization was good and followed a logical progression.
The Bad (and The Ugly, because you expected it)
Unfortunately, for all the book provides, there are enough problems with it that I have to wonder if it missed out on some much-needed editing.
To begin, this book doesn’t say anywhere what version of ActiveRecord (or Rails) it is documenting. It makes me wonder if the authors were all on the same page here, because while most places seem to be working with Rails 1.2, some look like they are talking about Rails 2.0 code. Since Rails 2.0 is being released any day now, that’s an important issue. There have been a lot of changes to ActiveRecord since Rails 1.2, and readers may be pretty confused about the applicability of the information. If nothing else, this book needs an update to get it in sync with Rails 2.0.
Next off, the book doesn’t come with any downloadable example code. I’ve reached the point where I think that is a basic requirement for a software book. I think it’s important to provide code that you can play with, or can use to copy/paste into your own code. It’s also possible to provide a lot more code in the example projects, since putting all that code in the book is usually too much. And maybe most of all, having real code from which you grab excerpts for the book means that you can have confidence the code actually works. The code examples in Pro Active Record were obviously written in a word processor and never executed, since many of them wouldn’t work correctly or even compile. I’ve messed up doing that in my own blog postings enough that I’ve learned that lesson.
One of the problems that affects the code samples disproportionately is that the book is riddled with typos and capitalization errors. It looks like Word’s auto-capitalization messed a lot of stuff up badly, especially the example code. Unfortunately, when you’re showing source code for a language that is case-sensitive, what might otherwise be a minor annoyance can become a significant issue. This is the sort of thing that is so easily prevented that I don’t understand how it can happen.
More seriously though, there are some glaring factual errors. For example, Chapter 2 states that ActiveRecord#update_attributes doesn’t run validations on the model. But it’s a totally common use case to use update_attributes like so:
def update
@user = User.find(params[:id])
if @user.update_attributes(params[:user])
redirect_to user_path(@user)
else
render :action => "edit"
end
end
That’s even how it’s done in the standard scaffolding now. If update_attributes didn’t run validations, that code wouldn’t work. Now, the update_attribute (note the singular) method does not run validations, but it is used quite differently from the plural form method. I could see how a casual reader of the ActiveRecord API might get confused, but not someone who had ever written a typical CRUD Rails application. Oddly enough, they get it right in the API summary appendix. Ah, the joys of collaborative authorship.
The book also states that there is a standard db:bootstrap rake task in Rails, which doesn’t exist even in Rails 2.0 (though Rick Olson and others have rolled their own). It says you can explicitly delete object instances in Ruby, something that is impossible in a garbage collected language like Ruby. And it says the :id attribute is optional in has_and_belongs_to_many, where it will in reality break certain things if you include it. They also claim that it doesn’t matter which ActiveRecord class you call find_by_sql on, when in actuality the class determines what kind of model object is returned from the call. Those are just some examples I caught; there are plenty of others.
This may all sound nit-picky, but I think if you can’t have confidence in the accuracy of a reference book, then you can’t truly rely on any of the information in it. Fortunately for the authors, none of these detail errors are major problems and they could be corrected with a good technical edit of the book. Perhaps they can be corrected in the ebook without waiting for a second printing
Bottom Line
If you’re looking to get started with ActiveRecord, Pro Active Record is a pretty good place to start. It has everything you need to get your bearings and start your journey. Be advised, however, that it’s not going to take you much past the start of that journey. And at least with the current edition, you’ll need to double check the directions along the way.
Reviewing the Review
Since this was my first book review here, I’d like to get some feedback. What did you all think of it? Useful? Too critical? Too short? Too long? Not enough pie?
I’m intending to do more of these (maybe one every month or two), so tell me what works and what doesn’t.
