#localDB - A Simple localStorage Database

localDB is a simple database layer for localStorage.

##Table of Contents:

• Overview
• Installation
• localDB Anatomy
• Loading a Database
• Deleting a Database
• Creating a Table
• Deleting a Table
• Getting Table Meta Data
• Inserting Data
• Updating Data
• Removing Data
• Finding Data
• Checking a Database Exists
• Checking a Table Exists
• Exporting Data

Overview

localDB is a very simple database for localStorage. It allows you to harnes the power of the browsers localStorage so that you can still store data even when your user is using an offline application. localDB is completely standalone and has absolutely no dependencies other than your users browser supporting localStorage ;)

One thing to bear in mind when using localStorage is that it has a limit of 5MB before the browser warns the user.

Installation

To install localDB all you need to do is include the javascript in your page. The line should look something like the one below:

<script type="text/javascript" src="localdb.min.js"></script>

localDB Anatomy

In this section I would like to spend some time explaining how the databases created by localDB are structured and what to expect in terms of errors if a function fails for some reason.

Structure:
A database is stored as a key in localStorage, this key contains a JSON encoded string of an object which is the database. The structure of the database is displayed below:

db_name
   |---table_name
         |---totalrows (variable)
         |---autoinc (variable)
         |---rows (array)

Return values:
If a function fails a some point it will always return false, most functions will also output an error message into the browsers console in order to give you a description of exactly what went wrong in an attempt to help you what the problem was. Return values are noted next to each of the functions further down these docs.

Loading a Database

After you have included the javascript in your page, you will now need to load a database. To do this you will need to call a new instance of localdb() with the first and only parameter being the name of the database you want to load. If the database exists it will be loaded into memory, if the database doesn't exist yet then it will be created and then loaded into memory. The line of code should look something like this:

var db = new localdb('dbname');

Example:

var db = new localdb('foo');

Returns:
None

Deleting a Database

If at any point you would like to delete a database, you can do so using the following function. If the database you are trying to delete doesn't exist, an error will be displayed in the browsers error console and the function will return false. The code to delete a database would like something like this:

db.deleteDatabase('database_name');

Example:

db.deleteDatabase('foo');

Returns:
Success: true
Error: false with error message (console)

Creating a Table

Now that you have loaded a database into memory. Let's create a table. localDB is a schemaless database system, this means that when creating a table in localDB you don't need to worry about defining any columns, all you need to define is the name of the table that you would like to create. To create a table in the database we just loaded, it would look something like this:

db.createTable('table_name');

Example:

db.createTable('users');

Returns:
Success: true
Error: false with error message (console)

Deleting a Table

Deleting a table in localDB is simple, you simply need to enter the name of the table you would like to delete as the first parameter in the dropTable() function like so:

db.dropTable('table_name');

Example:

db.dropTable('users');

Returns:
Success: true
Error: false with error message (console)

Getting Table Meta Data

localDB stores a couple of pieces of information that you might want to use every so often like the total number of rows in a table and the current auto increment value of the table. To get this information, call the tableMeta() method with the first and only parameter being the name of the table you want to retrieve the meta information for. The code would look something like this:

var meta = db.tableMeta('table_name');

Example:

var meta = db.tableMeta('users');

Returns:
Success: true
Error: false with error message (console)

Inserting Data

When it comes to inserting data into the database, as I said earlier localDB is a schemaless database system which means when you are inserting data into the column you won't need to worry about if the column you are trying to insert data into has been defined or not as each row of data in the database has it's own set of "columns". This means that some rows in the database could possibly have more "columns" than another row in the same table.

In order to insert some data into the database you need to provide the name of the table and the data you would like to insert into the first and second parameters respectively of the insert() function as follows:

db.insert('table_name', data_object);

Example:

db.insert('users', {'username': 'johnsmith', 'firstname': 'John', 'lastname': 'Smith'});

Returns:
Success: true

Updating Data

There are 2 methods for updating data in localDB. These methods are **update()** and **updateById()**.

update(table_name, data_object, where_object)

The update() method has 3 parameters, going from first to last they are: table, data and where. The code for updating some data in the database using the update() method would look something like this:

db.update('users', {'username': 'smithy576'}, {'username': 'johnsmith'});

Returns:
Success: true
Error: false with error message (console)
 

updateById(table_name, data_object, id)

The updateById() method also has 3 parameters, going from first to last they are: table, data and id. This function is only really any use when you know the ID of the row you are trying to update. The code for updating some data using the updateById() method would look something like this:

db.updateById('users', {'username': 'smithy576'}, 1);

Returns:
Success: true
Error: false with error message (console)

Removing Data

Similar to updating above, there are 2 methods for removing data in localDB. These methods are **remove()** and **removeById()**.

remove(table_name, where_object)

The remove() method has 2 parameters, the first one being table and the second being where. The code for removing some data from the database using the remove() method would look something like this:

db.remove('users', {'username': 'smithy576'});

Returns:
Success: true
Error: false with error message (console)
 

removeById(table_name, id)

The removeById() method also has 2 parameters, the first one being table and the second one being id. This function is only really any use when you know the ID of the row you are trying to remove. The code for removing some data using the removeById() method would look something like this:

db.removeById('users', 1);

Returns:
Success: true
Error: false with error message (console)

Finding Data

Just like updating and deleting, there are 2 methods at your disposal for finding data in localDB. These methods are **find()** and **findById()**.

find(table_name, where_object, limit, offset, type)

The find() method has 5 parameters, from left to right they are as follows: table_name, where, limit, offset, type. I will explain these parameters a little more below:

table_name - Simple, it's the name of the table that you want to search in
where (optional) - An object containing the where criteria, check below for an example. If omitted, the search will match all rows
limit (optional) - The maximum number of items you want to be returned
offset (optional) - The offset of the returned results
type (optional) - This is the type of search you want to run. Possible values are AND and OR. If omitted this defaults to AND.

The code for finding some data in the database using the find() method would look something like this:

Example 1:

var results = db.find('users', {'username': 'smithy576'});
English: Find all users where their username is smithy576

Example 2:

var results = db.find('users', {'username': 'smithy576', 'firstname': 'Jason'}, 1, 0, 'OR');
English: Find one user where either their username is smithy576 or their first name is Jason

Example 3:

var results = db.find('users', {'title': 'Mr', 'lastname': 'Williams'}, 5, 0, 'AND');
English: Find 5 users where their title is Mr and their last name is Williams

Returns:
Success: Array
Error: false with error message (console)
 

findById(table_name, id)

The findById() method has 2 parameters, the first one being table and the second one being id. This function is only really any use when you know the ID of the row you are trying to find. The code for finding some data using the findById() method would look something like this:

db.findById('users', 1);

Returns:
Success: Array
Error: false with error message (console)

Checking a Database Exists

You can use the dbExists() method to check if a certain database already exists or not. This function will return true if the database exists and false if it doesn't. You can use the function like so:

var dbexists = db.dbExists('dbname');

Example:

var dbexists = db.dbExists('bar');

Returns:
Success: true
Error: false

Checking a Table Exists

You can use the tableExists() method to check if a certain table already exists or not in the currently loaded database. This function will return true if the table exists and false if it doesn't. You can use the function like so:

var tableexists = db.tableExists('table_name');

Example:

var tableexists = db.tableExists('users');

Returns:
Success: true
Error: false

Exporting Data

localDB allows you to export either the whole database or a certain table from the database using the exportData() method. The exportData() method has 1 parameter which is **table** and it is optional. If the table parameter is supplied the required table will be exported as a JSON string from the currently loaded database otherwise if the parameter is omitted the entire currently loaded database will be exported as a JSON string.

var json = db.exportData('table_name');

Example 1:

var database = db.exportData();

Example 2:

var table = db.exportData('users');

Returns:
Success: JSON
Error: false with error message (console)