public methods

The following methods provide the functionality for interacting with a specific database through its handle. In order to use them you thus need to retrieve the handle first using the jsql.DB.open() method. For example:

var db = jsql.DB.open("books");

jsql.DB.prototype.exists (table)

This method will check if a table with the given name exists in this DB.

Parameters

• table: The name of the table to be checked for existence.

Returns

• true: The table with the given name exists.
• false: The table with the given name does not exist.

jsql.DB.prototype.isEmpty (table)

This method will check if the table with the given name is empty. If invoked without a parameter, the method will check if the DB itself is empty (i.e. contains no tables).

Parameters

• table: The name of the table to be checked for emptiness.

Returns

• true: The table with the given name is empty.
• false: The table with the given name is is not empty.

jsql.DB.prototype.create (name, definitions)

This method will create a new table in the database associated with this object. If the table already exists, nothing will be done.

Parameters

• name : The name of the table to be created.
• definitions: Array containing sub-arrays each defining a column. Each sub-array contains 3 elements:
  1. column-name
  2. data-type
  3. "NULL" | "NOT NULL" | "PRIMARY KEY"
     Example: [["id", "INTEGER", "PRIMARY KEY"], ["name", "TEXT", ""]]

Wiki page with information on [data types and constraints].

Returns

• true: A new table was created.
• false: No table was created (it already existed).

jsql.DB.prototype.alter (table, operation, column, type, constraint)

This method will change a table's definitions, either by adding, modifying or droping one of its columns.

Parameters

• table : The name of the table to be altered.
• operation: The operation to be performed. Accepted values are:
  • "ADD"
  • "MODIFY"
  • "DROP"
• column: The name of the column to be added, modified or droped.
• type: The type of the column when adding or modifying.
• constraint: The constraint to be applied when adding or modifying a column. When modifying, this parameter is optional. Accepted values are:
  • "NULL"
  • "NOT NULL"
  • "PRIMARY KEY"

Returns

• true: The operation was successfully completed.
• false: The operation was not successfully completed.

jsql.DB.prototype.insert (table, values)

This method will insert the given values in the given table. If the table does not exist, nothing will be done and null will be returned.

Parameters

• table: The name of the table into which the values will be inserted.
• values: Array containing all the values needed for creating a new record.

Returns

• The new record's primary key (or -1 if the table has no primary key). If the given table does not exists or a type error is found, null is returned.

jsql.DB.prototype.select (table, sfields, condition)

This method will use the given conditions to select the given fields from the table. If the table does not exist, nothing will be done and null will be returned.

Parameters

• table: The name of the table into which the values will be inserted.
• sfields: Array containing the names of the fields whose values are to be retrieved. If any of the element in this array is *, all the fields will be selected.
• conditions: An array containing sub-arrays and logical operators. Each sub-array contains 3 elements describing the selection operation. Those elements are:
  1. The field.
  2. The operator.
  3. The value.
     The logical operator is a string containing AND or OR.
     Example: [["id", "=", 5], "OR", ["name", "=", "john"]]

Returns

• An array containing the values of the given fields matching the given condition. If the table does not exist, null is returned.

jsql.DB.prototype.update (table, set, condition)

This method will use the given conditions to update the given fields with the given values in the table. If the table does not exist, nothing will be done and null will be returned.

Parameters

• table: The name of the table to be updated.
• set: An array containing field value pairs which will be used to update the table. Example:
  • ["name", "John", "age", 32, "city", "Memphis"]
• conditions: An array containing sub-arrays and logical operators. Each sub-array contains 3 elements describing the selection operation. Those elements are:
  1. The field.
  2. The operator.
  3. The value.
     The logical operator is a string containing AND or OR.
     Example: [["id", "=", 5], "OR", ["name", "=", "john"]]

Returns

• An array containing the IDs of the records updated by the method. If the table does not exist, null is returned.

jsql.DB.prototype.delete (table, conditions)

This method will delete all the entries selected by the given conditions from the table. If the table does not exist, nothing will be done and null will be returned.

Parameters

• table: The name of the table from where the entries will be deleted.
• conditions: An array containing sub-arrays and logical operators. Each sub-array contains 3 elements describing the selection operation. Those elements are:
  1. The field.
  2. The operator.
  3. The value.
     The logical operator is a string containing AND or OR.
     Example: [["id", "=", 5], "OR", ["name", "=", "john"]]

Returns

• The number of deleted entries. If the table does not exist, null is returned.

jsql.DB.prototype.drop (table)

This method will drop the given table from this database. If the table does not exist, nothing will be done.

Parameters

• table: The name of the table to be droped.

Returns

• None.

jsql.DB.prototype.getTableNames ()

This method will retrieve the name of all the tables in the database associated with this object.

Parameters

• None.

Returns

• Array containing the name of all the tables in the database.

jsql.DB.prototype.getFieldNames (name)

This method will retrieve the name of all the fields in the table identified by the given name.

Parameters

• name: Name of the table whose fields are to be retrieved.

Returns

• Array containing the name of all the fields in the table.

jsql.DB.prototype.save (table)

This method will save the table identified by the given name to the local storage. If no table name is provided, all the tables will be saved.

Parameters

• table: (Optional) The name of the table to be saved to the local storage.

Returns

• None.

jsql.DB.prototype.setAutoSave (flag)

This method will set the autosave flag for this database.

Parameters

• flag: Boolean value indicating whether the autosave feature should be on (true) or off (false).