Mongo Bongo

I really love the paradigm shift that happens when you start using new tools, and recently this happened to me with MongoDB. Here are a couple of gotchas that I wanted to document for my future self.

From the incredibly rich and highly helpful documentation pages, “MongoDB is an open-source document database that provides high performance, high availability, and automatic scaling.”¹

MongoDB is a noSQL database, which means it is schema-less. This means no need for migrations. Incredible, I know. Records in MongoDB consist of documents in a BSON object format which are functionally identical to the JSON objects that we all know and love.

I happened to use MongoDB in conjunction with a recent Rails project via the Ruby gem, Mongoid. Mongoid is “an ODM (Object-Document-Mapper) framework for MongoDB in Ruby,”² and it is also very well documented.³

Cool things that you can do with MongoDB include querying the database in JavaScript, nested attributes and whole slew of other nice things.

It is obviously not the right choice for every project, and I don’t think anyone is really claiming it to be, but what it does, it does extremely well. It is performant and scalable, did I mention it is well documented? That being said, there were a couple of subtleties that I noticed.

Gotcha #1

Anytime you drop the database and you had a document’s field indexed, then that index would have to be created again before seeding. (A document field is like a SQL table column.)

You would simply have to include this command in your workflow:

$ rake db:mongoid:create_indexes

Gotcha #2

MongoDB and by extension Mongoid uses the _id field as the analogue to the more familiar id in SQL tables. The _id field consists an ObjectId⁴ hexadecimal that increments sequentially, but not one by one as we are used to with ordinary id attribute integers.

For example, a typical newly-created object on a new database could have the _id field of:

_id: {
  $oid: "56d3320efc3868284b000000"
}

This was confusing, but after a while I started getting used to my URLs having a hexadecimal :id params.

If you really, really need the id field automatically generated alongside the existing _id field, (and this is quite conceivable since most programs expect there to be an id field or column in a database), I used a workaround to insert them.

In Rails config/initializers folder, create a file called mongoid.rb:

module Mongoid
  module Document
    def as_json(options={})
      attrs = super(options)
      attrs["id"] = attrs["_id"].to_s
      attrs
    end
  end
end

This adds an additional field called id with the same hexadecimal value of _id to each new Mongoid document.

There are plenty of other avenues to explore with regard to MongoDB, and the above barely scratches the surface. These were just a couple of the issues that were new to me when I started exploring the exciting world of noSQL databases.

Don't Act Surprised

I had an experience recently in my coder education that I had previously only read about in blog posts and twitter stories. It is when you state your ignorance of a certain topic to someone, (be they a peer, mentor or manager,) and their first reaction is complete and utter surprise. “You don’t know about (some topic in software development)? WOW! OMG”

There are few things more off-putting than this “acting surprised” phenomenon for the budding learner. It makes the entirely wrong assumption that knowledge that an experienced coder has internalized must be second nature to someone else, even if they are still learning the subject. This can be especially harmful for anyone who has just mustered the courage to ask the question in the first place on a topic that may be new or concepts that are still foreign.

At the coding bootcamp I attended we were encouraged to “expose your ignorance”. This is a great way to let go of any fears of appearing to know less than the sum total of all human knowledge, something that I have noticed some professionals in the wild seem to hold as an attainable goal. Putting the stuff one does not know very well out in the open provides a direct way of tackling these gaps and being able to learn and grow.

The concept here is that you may know some things that others don’t and vice versa. It is therefore completely natural to not know everything, (as strange as this sounds.) This reminds me of my beginning of the year post: It’s OK To Be Wrong

In a professional setting, if I am say, a coder with fifteen years of experience, and I ask a seemingly “obvious” question, then perhaps the person receiving that question could be permitted to act surprised over an apparent gap in knowledge. However, even in this instance the experience will most likely leave a bad taste in my mouth and I would think twice about asking that individual for help again in the future.

From the point of view of the mentor, just as one would not “call out” a child for not knowing what a mortgage is, how to file taxes, drive a car, or do any number of ‘adulting’ activities, one should also not act surprised (or worse) when a junior dev, intern or apprentice has expressed their ignorance over a topic that seems to the mentor to be trivially obvious.

Serious thought should be given to type of culture that one wishes to foster: a culture of openness and freedom to ask questions or one of closeted ignorance and constant fear of being judged for perceived shortcomings.

So the next time someone asks a question, please don’t act surprised.

Did You Miss Me?

Hello there, bloggy blog,

It’s been a while, so I thought I’d pop in and drop a quick post.

As I mentioned in a recent /now post, I’ve been super busy with my dev apprenticeship which is now entering the last phase. It’s been an amazing experience and I will be glad to share more about it in the coming weeks.

Although it may look like I have been neglecting you, my beloved reliable and nimble static Jekyll blog, astute readers (all three of you) will have noticed a few subtle improvements behind the scenes in the past few weeks:

Drafts

To my chagrin, I found that I posted a (naive) interpretation of ES6 JavaScript Promises before it was complete. This was not very Genuine Hacker™ of me, so that day I learned the hard way about creating a _drafts/ folder for my cobbled but not-quite-ready-for-peer-review blog posts. Adding that folder to my .gitignore file prevents pushing up any more half-baked ideas to the main repository.

Excerpts

Additionally, I wished to shorten the amount of scrolling that one had to do on the main index page just to get the bottom pagination links. This meant condensing posts into blurbs or snippets, and wouldn’t you just know it? Jekyll already has such a functionality in the Liquid template system, and it is called excerpts. Yet another great example to always RTFDocs, folks.

CNAME

I migrated from my GitHub-generated .io URL to this shiny new .com one. Namecheap had it on sale for 88¢ for the first-year, so I went for it. I kinda like it.

Google Analytics

Shoved this code snippet into my _includes/ folder.

Redcarpet to kramdown

Finally I updated Jekyll to 3.0 and saw that GitHub was leaving some ominous warning messages on the command line about the coming use of kramdown, one of a many types of Markdown parsers that have sprung up over the years. The message indicated kramdown would soon be used as a default for GitHub hosted webpages like this one.

Note: Starting May 1st, 2016, GitHub Pages will only support kramdown.

At the time I was on Redcarpet, which I had settled upon after a short survey revealed it provided what I needed: fenced code block syntax highlighting (via Pygments), strikethrough, superscript, and footnotes. Even tables were supported! The autolink extension was very nice also (wherein URLs in the Markdown document were automagically converted to anchor tags in markup.)

After the requisite panicking stage, I soon found out one of the main reasons why kramdown was chosen: it is blazingly fast. GitHub even provided a handy dandy page to help people update. Soon I was able to semi-smoothly make the transition.

Here are all the steps I took in excruciating detail. First, modify the _config.yml file to use kramdown for Markdown instead of Redcarpet, and Rouge instead of Pygments (which is also being deprecated,) for syntax highlighting. kramdown is “GitHub Flavored Markdown” so naturally the three-backtick (`) code blocks work just fine. More on this code syntax-highlighting later.

I still had footnotes, and strikeouts, but support for ^super or _sub -scripts will have to wait. The workaround method of HTML in Markdown exists via <sup> and <sub> tags, but that still won’t work within code blocks. For me, this is not a tremendous issue, but I could see it being a problem for science equation publishers. Nevertheless LaTeX fully works in kramdown, in case I want to break out some Laws of Thermodynamics or Drake Equation posts.

All the previously autolinked URLs that were in my posts went back to being just plain strings, so I had to go back and fix them. C’est la vie.

Going back to the code syntax highlighting issue, one last thing that I wanted to implement was line numbers in my code blocks, since it would be much easier to reference specific points within the posts. I was able to accomplish syntax highlighting with Rouge which was replacing Pygments by applying the knowledge of this blog post: Syntax Highlighting in Jekyll With Rouge Thank you, Sacha!

However that post ends with the statement that line numbers are not yet supported, and that for code block line numbers “you’ll have to wait for a little while.” Luckily for us, a little while has passed, and I found a post a few months later on a different blog describing a very nice workaround for implementing line numbers in your Rouge code blocks on Jekyll. All credit is due to Minh Nguyen for this solution: JEKYLL LINE NUMBERS Thank you, Minh!

Good to be back

Yes, indeed. After stressing out about learning new and difficult/different stuff on work projects, it feels really good to just be able to poke around and have fun with a pet project like this blog. I hope this information helps the next person that may happen upon it. Cheers!

Addendum

I forgot to mention a final enhancement which was to modify the internal/external link behavior globally. kramdown helpfully provides anchor tags with the target="_blank" to open the link in another tab/window. In kramdown you can do this, on a per link basis:

[Link Text](Link URL){:target="_blank"}

However, being a good lazy programmer, I wanted to not worry about adding this to every past and future link, so I found a quick n’ dirty fix using jQuery.

Edit (December 2016): I have updated this using pure Vanilla Js so as not to require the entirety of the jQuery library for this simple function.

After including jQuery, add this JavaScript snippet to application.js:

jQuery(function ($) {
  //Change target attribute of external links
  var domain_root = document.location.protocol + '//' + document.location.host;
  var all_links = $('a').each(function (index, element) {
    if (element.href.substr(0, domain_root.length) !== domain_root) {
      element.target = '_blank';
    }
  });
});

Now every external link will open its own tab while internal links (say to /projects) will proceed in the same window as normal.

I like the way this blog is coming along as my own Incremental build model. Onwards and upwards!