Please note, however, that manual migrations require the explicit inclusion of an ID column:

  var BoxContent = new JazzRecord.Model({
    table: "box_contents",
    belongsTo: {box: boxes}
  });

  JazzRecord.createTable("boxes", {
    id: "int",
    label: "text",
    volume: "float"
  });

  JazzRecord.createTable("box_contents", {
    id: "int",
    name: "text",
    size: "float"
  });

This example shows how a minimal amount of code in the models can set up a 1 to N relationship between a Box and several BoxContent objects. At any time schema operations (like createTable() or removeColumn()) are called, the model’s definition is updated in memory, so calling save() or similar will always be up to date.

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!

The coolest two things about JazzRecord, and likewise Rails’ ActiveRecord:

* the fact they automatically load associated records as objects, based on models’ knowledge of interrelations with other models, and that associated records’ linkage is handled transparently to the user in such a way as to make total sense. The *databaseness* of working with things melts away to pure OO code.
* the fact the built in validations lend so much power and usefulness when it comes to business logic, without sacrificing readability of code.

In order to maintain the ease of use that ActiveRecord affords, I had to put JazzRecord together carefully. One thing I really wanted to maintain, which I’ve seen fall by the wayside in similar JavaScript ORMs, is the ability to simply assign new values to properties of a record object and have them be validated at save time, saved down as appropriate column/field data in the database, and even reload appropriate associated records from different tables. This requires that record objects have knowledge, or rather the ability to communicate with objects that *do* have knowledge (models), of interrelations between tables and knowledge of how to validate the properties.

Even knowledge of a record’s model and its associations is not enough to overcome the language barriers faced when porting a Ruby-language project to JavaScript: JavaScript function calls require the use of parenthesis, and because of this field name getters/setters cannot be treated as simple properties the way ActiveRecord field names are. To avoid having to unnecessarily clutter up API code with function calls for simple setting and getting of field data, JazzRecord introduces the idea that fields are simply properties of record objects – it just doesn’t care about any extraneous properties not defined within a record’s model declaration. At the time of save, and partially at the time a record is validated, a record’s data are examined in the context of those fields defined on the record’s model, and those associations defined in the same place. Any additional properties are simply ignored by JazzRecord. This stresses the importance of tying the record object to its basis, a model. Without the knowledge inherent in this connection, the record would have no way of loading associated data, and no means for validating field data. Without this connection, each record object would have to carry around its own set of validation rules and association-loading methods. And that would be slow.

An example may help to illustrate the ease of use/power combo better: Say we’re dealing with a *Home* model and a *Person* model. The relationship is 1 to N, where Person is the N end. Let’s say we also have a *Vehicle* model, which has a relationship of 1 to 1, with Vehicle belonging to Person. We’ve set up some nominal validation setup for ensuring a person’s age is an integer. Setup code will follow the usage examples.

Here’s a few things JazzRecord does or lets you do:

* Everyone knows finders: `var p = Person.findBy(”name”, “Nick”)`
* And getting and setting local column properties of the record is simple: `p.age //returns 28`, `p.age = “29yrs” //it’s my birthday!`
* Calling `isValid()` on a record object will return a boolean, as well as populating the error object with appropriate error information.
* Calling `p.save()` will also cause validation methods to run. Since this is an existing record, any *validatesAtUpdate* or *validatesAtSave* methods defined on the model will run.

Our record will fail to save because we’ve got errors: p.errors.age is an array of all errors relating to the *age* field, and it contains the helpful default string “age is not an integer”. This error message could easily be customized for use as actual presentational text to be used in an application to show users entering invalid data.

Correcting the age to a simple number and saving again will fix this and clear out the errors arrays: `p.age = 29; p.save()` This now succeeds, and indeed our p.errors object is re-initialized to an empty state.

Did you know JazzRecord will also reload all associated records? Didja even know it loaded them to begin with? Associations are easy to use. As soon as a finder returns a record, or as soon as a save finishes, your new record has not only the immediate field properties defined on its own model, but the associated data of any immediately-related records are loaded automatically. Here’s what this means:

* `p.vehicle` is an actual vehicle record. It has all the capabilities p has, such as retrieving/editing immediate fields and saving them back down. `p.vehicle.model` returns the string “Forenza”, and setting it `p.vehicle.model = “Corvette”` and saving `p.save()` will update the record accordingly. This is quite useful.
* if validations were defined for the vehicle record, they would be run prior to actually updating it.
* Records can be loaded more than 1 level deep by calling the `load(colname)` method of a record with unloaded subordinate records: `p.vehicle.load(”dealership”)`, perhaps, if a dealership association was defined and such data existed.

Upon loading the new data, all of the newly-loaded record’s immediate data is available for tinkering with, just as with the automatically-loaded association data.

Be careful! Loading associated records which are already present earlier in the scope chain may lead to unpredictable and undesirable results. Never do `p.vehicle.load(”owner”)`, for instance, as this will load a *second* instance of the same person record stored in *p*, and these two objects cannot be kept in sync. This is a language limitation and is unavoidable. **Do NOT load redundant records from earlier in the scope chain!**

The last piece of the powerful parts of JazzRecord puzzle (say that three times fast!) is auto-linking and unlinking of associations in the database based on logical user interaction in the API.

* A user can add or change a foreign-key reference manually: `vehic.person_id = 1`, or she can change it through the association property itself: `vehic.owner = Person.last()`. After calling `vehic.save()`, the association and the ID are both set correctly, no matter which was the triggering mechanism. Note that trying to assign both the key manually and the association can lead to confusion and is best avoided. If one has been set and you want to reset before setting the other, feel free to call the record’s *revert()* method. It will return to the state it was in after the last find or save operation.

* Likewise, deleting a foreign-key manually or deleting an association both work: `delete vehic.person_id` and `delete vehic.owner` work equally well. After calling `vehic.save()`, both association and foreign key will be deleted.

This is a useful concept. It allows the user to think in more abstract terms than setting keys all over the place. It works on all supported association types, even N to N. (it will delete and add records to mapping tables automatically) It *also* works from either side of an association. More on that in a second.

We’ve seen that deleting a record’s association when it “belongs to” another record is easy. But we can also link or unlink a record from the other side: `p.vehicle = Vehicle.find(3)` followed by a save will cause the original vehicle’s foreign key reference to disappear and the foreign key on the new vehicle (#3) to be set to the person’s ID. Again, powerful stuff. Deleting an association works the same: `h = Home.first(); delete h.people[0]; h.save()` causes the first Home record to be loaded, and removes the association of the first person object from the equation. The person object’s `home_id` will now be gone.

As for the models which were used in this article…

var Home = new JazzRecord.Model({
table: “homes”,
foreignKey: “home_id”,
hasMany: { people: “people”},
columns: {
address: “text”,
}
});

var Person = new JazzRecord.Model({
table: “people”,
foreignKey: “person_id”,
belongsTo: { home: “homes”},
hasOne: { vehicle: “vehicles”},
columns: {
name: “text”,
age: “number”,
home_id: “number”,
},

validate: {
atSave: function() {
this.validatesIsInt(”age”);
}
}
});

var Vehicle = new JazzRecord.Model({
table: “vehicles”,
foreignKey: “vehicle_id”,
belongsTo: { owner: “people”},
columns: {
make: “text”,
model: “text”,
person_id: “number”
}
});

More complex versions of these models are in the *example_models.js* file which comes in the zip file of source code for JazzRecord.

Working with the library functions almost identically to most general usage of Rails’ ActiveRecord, and this ease of use/identical behavior was a driving goal in its development. Because of its scope and methodology, actually sitting down to use JazzRecord may be the easiest way to learn it.