Home| Demo| Download| Guide

General Guide for Using

There are 3 general functions built into the html5sql module.

html5sql.openDatabase(databaseName, displayName, estimatedSize)

The html5sql.openDatabase() is a light wrapper for the native openDatabase function. It open's a connection to your database and saves a reference to that connection for you. It needs to be called before you can process any SQL statements.

This function has 3 arguments.

If you are familiar with the native openDatabase function you may notice that version is missing. Database versions are powerful things when you need to change the structure of your database tables, but using this functionality is implemented within the changeVersion function of html5sql. For right now we just open a generic connection to the database.

So an example could be something like this:

 html5sql.openDatabase(
     "com.mycompany.appdb",
     "The App Database"
     3*1024*1024);

html5sql.process(SQL, finalSuccessCallback, errorCallback)

The html5sql.process() function is the workhorse of the functions. Once you have opened your database you can pass this function SQL and it will make sure that SQL is executed in a sequential manner.

The first argument which is passed to html5sql.process() is SQL. It can accept SQL statements in many forms:

  1. String - You can pass the process function a single SQL statement in a string like this:

    "SELECT * FROM table;"

    or a bunch of SQL statements in a single string, as long as each of them ends in a semicolon like this:

    "CREATE table (id INTEGER PRIMARY KEY, data TEXT);" +
"INSERT INTO table (data) VALUES ('One');" +
"INSERT INTO table (data) VALUES ('Two');" +
"INSERT INTO table (data) VALUES ('Three');" +
"INSERT INTO table (data) VALUES ('Four');" +
"INSERT INTO table (data) VALUES ('Five');"

  2. Text from Separate File - In much the same way html5sql.process() can handle strings with multiple SQL statements, it can handle and process text data retrieved from an separate file. An example of this is shown above.

  3. Array of SQL Statement Strings - You can pass the process function an array of SQL statement strings like this:

     [
     "CREATE table (id INTEGER PRIMARY KEY, data TEXT);",
     "INSERT INTO table (data) VALUES ('One');",
     "INSERT INTO table (data) VALUES ('Two');",
     "INSERT INTO table (data) VALUES ('Three');",
     "INSERT INTO table (data) VALUES ('Four');",
     "INSERT INTO table (data) VALUES ('Five');"
 ]

  4. Array of SQL Statement Objects - The most functional method of providing SQL is by using the SQL Statement Objects in an array. The structure of the SQL Statement object is basically the same as the arguments you pass to the native executeSQL function and has three parts:

    • SQL "String" - A string containing a single SQL statement. This string can optionally include ? in place of data.
    • data [Array] - An array of data which will be sequentially inserted into the SQL statement to replace the ? characters. The number of ? characters and elements in this data array must match.
    • success (function) - A function which will be called upon successful execution of the SQL statement. It has access to the results of the SQL statement. Additionally, if this function returns an array, it will be used as the data parameter for the next SQL statement to be processed. This allows you to use the results of one SQL statement as data for the following SQL statements as is commonly needed for foreign keys.

    Probably the easiest way to define and use this object is by defining an object literal. So a general template for this SQL Statement Object would be something like this: 

    {
   "sql": "",
   "data": [],
   "success": function(transaction, results){
    //Code to be processed when sql statement has been processed
   }
}

    So a simple example of the SQL parameter when using using SQL Statement Objects could be:

     [
   {
     "sql": "INSERT INTO contacts (name, phone) VALUES (?, ?)",
     "data": ["Joe Bob", "555-555-5555"],
     "success": function(transaction, results){
         //Just Added Bob to contacts table
     },
   },
   {
     "sql": "INSERT INTO contacts (name, phone) VALUES (?, ?)",
     "data": ["Mary Bob", "555-555-5555"],
     "success": function(){
         //Just Added Mary to contacts table
     },
   }
 ]

    The only argument of the native executeSQL function that isn't part of the SQL Statement Object is the error callback function. This is because there is a general error callback that is defined for the entire transaction rather than for the individual statements. This general error callback is the third argument passed to the html5sql.process() function.

So in total html5sql.process() has 3 arguments:

Putting this all together. An example usage of html5.process() could be:

 html5sql.process(
     [
         "DROP TABLE table1",
         "DROP TABLE table2",
         "DROP TABLE table3",
         "DROP TABLE table4"
     ],
     function(){
         console.log("Success Dropping Tables");
     },
     function(error, statement){
         console.error("Error: " + error.message + " when processing " + statement);
     }
 );

html5sql.changeVersion("oldVersion","newVersion",SQL,successCallback,errorCallback)

The html5sql.changeVersion() function is what you should use to set up your database and handle version and migrations. This function works by testing if the database's version matches the oldVersion parameter you provide. If it does this function will process the SQL and change the database's version to the newVersion value you specify.