I have to assume folks are making use of JazzRecord in some way, and that they’re visiting to refer to the documentation. I don’t see any other explanation. I’d really like to get to know the users, and find out if we can do anything to improve JazzRecord short-tern and long-term.

Long-term, for instance, I’d like to move our documentation into the source code repo and simply reference/style that nicer on the Web site. I’d also like to provide better docs and add a few more features, like the ability to add indexes in a model’s declaration. I’m still considering the implications of async support eventually, though I certainly don’t have time to support this idea at the moment. We’d still like to translate the docs into other languages, but we need volunteers.

Short-term, I’d like to add some new adapters to the codebase. I’d like to support any new runtimes that may have cropped up lately. Node.js and similar are definitely on the list. Does anyone use Jaxer still? Is there an environment you’d like to see supported? So long as SQLite or a compatible dialect of SQL is supported, and so long as a *synchronous* API of some kind exists, JazzRecord can be added with very little effort.

Please, take a moment and comment, here or on Twitter. Let us know how you use JR and what you’d like to see in the future.

We’ve been busy once more, putting together JazzRecord 0.7, which incorporates manual migrations with all of the major features from Rails’ ActiveRecord migrations. While there are no official updated docs yet, here’s a brief list of changes:

ID must now explicitly be listed as a column for a model. If using automigrations, you must list it in the model definition. The explicit requirement for ID column may change going forward, but once we hit Version 1 (another month, perhaps) we will stand firm on the API. If using manual migrations, you may now leave out columns from the model definition entirely and rely on migrations setting the model’s column knowledge for you.

What this means is, no matter what changes you make to a db schema using migrations, the model is always aware of the current state of the schema and will allow you to create, destroy, and modify properties of records with no problem. The only thing to watch out for is validations if you have any, because they can cause problems if there are requirements which cannot be satisfied given a specific updated schema.

The following schema operations are available as of now:

JazzRecord.createTable(tableName, cols) – this creates a table using a columns object, identical the the (now optional) columns object from a model declaration.

• JazzRecord.dropTable(tableName) – removes a table from the DB.
• JazzRecord.renameTable(tableName) – renames a table
• JazzRecord.addColumn(tableName, colName, colType) – adds a column of given type to a table
• JazzRecord.removeColumn(tableName, colName) – removes a column from a table
• JazzRecord.renameColumn(tableName, oldName, newName) – renames a given column in a table
• JazzRecord.changeColumn(tableName, colName, colType) – changes the type of a column. This can result in data loss, as determined by how the DB converts data types

The last three functions were the trickiest, because SQLite does not provide inherent capabilities for modifying columns once they exist in a table. In order to reproduce thesefeatures, then, we have to go about slurping up all data in a table, dropping the existing table, creating a new table with the new schema, and spitting the same data back into the database, with data types changed or columns removed or changed in type. To keep this (hopefully) relatively safe, we wrap the destructive DROP operation in a transaction.

Did anyone even know JazzRecord had a JazzRecord.runTransaction(func, bind) method? I’m not sure! Calling this and passing in a function full of operations will ensure that if something goes wrong and you or some function you call throws an exception, all will revert to its pre-transaction state. Pretty cool, huh?

Making use of the schema operations is as simple as calling them anywhere, though typically you’d organize them into migrations. Migrations are now a bit streamlined, as well.

To automigrate, simply call JazzRecord.migrate() with no options, or to refresh the DB to an empty state, pass in an object with refresh property set to true:JazzRecord.migrate({refresh: true}). To optionally load fixture data, assign a fixtures object (same as the old object format) to JazzRecord.fixtures, and if it exists it will be loaded. To run migrations, simply assign to JazzRecord.migrations an object literal with numerically-named properties (starting with the number 1) each containing an object literal which has an up function and a down function. These functions should be the reverse of one another, and for an explanation of proper migration usage consult any Rails tutorial or wait for the documentation. Here’s a simple sample migration which creates a couple tables and adds a column to one of them over a few schema versions:

  JazzRecord.migrations = {
    1: {
      up: function() {
        JazzRecord.createTable("military_dudes", {
          id: "number",
          name: "text",
          title: "text",
          base_id: "number"
        });

        JazzRecord.createTable("bases", {
          id: "number",
          location_name: "text"
        });
      },
      down: function() {
        JazzRecord.dropTable("bases");
        JazzRecord.dropTable("military_dudes");
      }
    },

    2: {
      up: function() {
        JazzRecord.renameColumn("military_dudes", "title", "rank");
        JazzRecord.addColumn("bases", "state", "text");
      },
      down: function() {
        JazzRecord.removeColumn("bases", "state");
        JazzRecord.renameColumn("military_dudes", "rank", "title");
      }
    }
  };

After setting up a migrations object like this, you can call JazzRecord.migrate() standalone (to migrate to the latest version), or you can pass in a version number to reach the specified migration number. To reset to pre-migration status, call JazzRecord.migrate(0). In this way, you can evolve an application’s schema over time and can almost effortlessly jump between schema versions to diagnose problems or revert when you’ve introduced more problems than you’ve fixed! You can pretty much use migrations exactly as in Rails: changing schema and inserting/removing/updating data for existing, already-deployed applications. Soon we will add additional tools for updating multiple columns and multiple rows simultaneously, which will further add to the usefulness of migrations.

The smaller, but still useful, function introduced in JazzRecord 0.7 is Record’s isNew() function. This function, when called, will return true if a record has not been saved yet, or false if it has.

As a previous blog post stated, we are extremely interested in having our documentation translated into other languages, so please contact me at thynctank@thynctank.com if you can help with that.

Enjoy!

JazzRecord is veritably an international JavaScript ORM.  It eats at the International House of Pancakes (Are there even any of these restaurants outside of the United States?) and it drives on the wrong side of the road.  It can’t help it.  It just loves multinationalism.  Actually, as of last week, Google Analytics reports that JazzRecord.org has enjoyed visitors from all seven continents!  That’s right!  Someone from Antarctica visited 3 pages and spent a whopping 14 minutes and 13 seconds on JazzRecord.org!  That’s one JavaScript ORMing penguin!!!  JazzRecord.org has hosted 72 countries‘ worth of visitors that speak 40 languages, and is particularly well read by Eurasia, and recently Brazil!  This is all very exciting news to the JazzRecord team. However, there is a problem with these demographics: I remember very little of my high school German and Spanish courses. Also, I don’t know a lick of Portuguese, Khmer, Russian, or whatever the hell it is they speak in England!  We’re hoping that this is where you come in.

The JazzRecord team is always excited to hear from developers that are using the library in other parts of the world, especially ones that speak other languages, but we’re afraid that the all-English documentation might be impeding their usage.  So, we’re calling out all fluently bilingual JazzRecord users to help us expand our documentation into other languages! If you fit this description and would like to help out, please send an email to Nick Carter (Project Leader) at thynctank at thynctank dot com or David Rivers (Web Designer/Webmaster) at david at ideogon dot com.  We can’t promise that helping us out will get you on Oprah, but we will certainly give credit where credit is due!

JazzRecord is open-source, free software, because a small group of developers devote their blood, sweat, tears, first-born, and third arms to the cause. Unlike the RIAA we believe in the power of transparency and collaboration. However, we do need you (Think like Uncle Sam is pointing you out minus all the negative connotations that the American military would conjure in the minds of our far-reaching user base)! After all, I can hit my Rosetta Stone even harder, but I don’t think my ability to describe an apple in each of the colors of the rainbow is going to get us anywhere!