The Parable of CouchDB
By Jason on Jun 15, 2011
Suppose you begin keeping a personal library. You’ve rented a floor from the building in the Matrix. It’s just room after room, all identical; except the big main room at the end with the source. Helmut Bakaitis is your librarian, and he can perform a couple of minor miracles.

Your library facility
The big main room holds all your stuff. There is no organization at all. It’s just piles and piles of things. You can keep scientific journals, your childhood pop-up books, your private literature, an old globe that still says U.S.S.R.—pretty much anything. Just throw it in the pile. On your way out the door, the librarian asks, “what do you call that thing?” and you’re like, “whatever.” As far as adding to your library, nothing could be simpler.
To access the stuff in your library, you’ll exploit the librarian’s miracles. The librarian can make unlimited copies of your stuff, instantly! He’s got a full arts-and-crafts kit: colored paper, popsicle sticks, scissors, and sticky tack. He can complete any project you can conceive, instantly!
The librarian keeps similar copies of your library in every normal room on the floor. Normal rooms are impeccably organized: long shelves, sorted, everything in its place. Each room’s shelves are sorted differently, depending on what you want. Pick out a room and tell the librarian how to sort the shelves. You’ll say, "This is the titles room. Everything in here is always shelved by title." Poof! It’s just like your main library, but everything is shelved by title.
Go to the next room. You say, "Everything here is shelved by author." Poof! Now you’ve got two rooms, totally organized. When you need Asimov, you know just where to find him. On and on, you can use every room on the floor, and you can make specialized rooms. You can say, "This is the personal room. It’s got my private literature and nothing else." We’ve all got a personal room; but different people’s rooms will be differently-populated. Of course, the librarian can expand or pare-down your normal-room copies: whatever you need to look things up easily.
If you like, you can alter or even destroy your stuff in the big main room. The librarian ensures that normal rooms reflect changes from the source material. For example, if you scribble corrections on your globe, you won’t find the USSR in your normal rooms anymore.
But the big main room is disorganized. How will you find anything? Fortunately, the librarian remembers it all. Just ask him, “Hey, where’s my globe?” And there’s your globe! Start scribbling.
The End.
Key (Spoilers)
| In the story | In CouchDB |
|---|---|
| Personal library | Database |
| Floor | Hard disk space |
| Big main room | The database API |
| Things in the main room | Records ("documents") in the DB |
| What do you call that / whatever | Optional document ID ("_id") |
| Normal room | Database view |
| Librarian's miracle | Internal CouchDB mechanism |
| Altering your stuff | Updating a document |