mozIStorageConnection

For a general overview on how to use this interface, see Storage.

Method overview

Attributes

Constants

Transaction execution time constants.

SQLite database page size constant

Methods

Asynchronously closes a database connection, allowing all pending asynchronous statements to complete first.

void asyncClose(
  in mozIStorageCompletionCallback aCallback Optional
);

Parameters

aCallback Optional

An optional callback handler to be executed when the connection is successfully closed. That object's mozIStorageCompletionCallback.complete() routine will be called once the connection is closed.

Exceptions thrown

NS_ERROR_UNEXPECTED

Thrown if the method was called on a thread other than the one that opened the connection.

beginTransaction()

Starts a new transaction DEFERRED transaction. This is the same as calling mozIStorageConnection with mozIStorageConnection.TRANSACTION_DEFERRED.

 void beginTransaction();

Parameters

None.

beginTransactionAs()

This method starts a new transaction of the given transaction type. See the SQLite documentation on transactions for more details.

In JavaScript, managing transactions can be difficult when you are using the same connection on different threads, or are using a combination of asynchronous and synchronous statement execution. The best way to deal with this is to only execute your statements asynchronously using mozIStorageConnection.executeAsync(). This method will manage the transactions for you, so you don't have to worry about them.

 void beginTransactionAs(
   in PRInt32 transactionType
 );

Parameters

transactionType

One of the transaction constants (mozIStorageConnection.TRANSACTION_DEFERRED, mozIStorageConnection.TRANSACTION_IMMEDIATE, mozIStorageConnection.TRANSACTION_EXCLUSIVE)

Clones a database connection, optionally making the new connection read only.

mozIStorageConnection clone(
  in boolean aReadOnly Optional
);

Parameters

aReadOnly

If true, the returned database connection is in read only mode. This is false by default.

Return value

A new mozIStorageConnection object representing the cloned connection.

Exceptions thrown

NS_ERROR_UNEXPECTED

The connection is to a memory database.

Closes a database connection. Before closing the connection, you need to finalize all statements created for the connection.

void close();

Parameters

None.

Exceptions thrown

NS_ERROR_UNEXPECTED

Thrown if any statement has been executed asynchronously on the connection, or if the method was called on a thread other than the one that opened the connection.

commitTransaction()

This method commits the current transaction.

 void commitTransaction();

Parameters

None.

This method creates a new aggregate function that can be used in SQL. See mozIStorageAggregateFunction for sample code and more details.

If you use your connection on multiple threads, your function needs to be threadsafe, or it should only be called on one thread.

 void createAggregateFunction(
   in AUTF8String aFunctionName,
   in long aNumArguments,
   in mozIStorageAggregateFunction aFunction
 );

Parameters

aFunctionName

The name of the aggregate function to create, as seen in SQL.

aNumArguments

The number of arguments the function takes. Pass -1 for variable-argument functions.

aFunction

The instance of mozIStorageAggregateFunction that implements the function.

Creates a mozIStorageAsyncStatement for the given SQL expression. An asynchronous statement can only be used to dispatch asynchronous requests to the asynchronous execution thread and cannot be used to take any synchronous actions on the database.

The expression may use "?#" to indicate sequentially numbered parameters (?1, ?2, etc) or ":name" to indicate named parameters. JavaScript callers should use named parameters.

mozIStorageAsyncStatement createAsyncStatement(
   in AUTF8String aSQLStatement
 );

Parameters

aSQLStatement

The SQL statement to execute.

Return value

Returns a new mozIStorageAsyncStatement to be used to execute the specified statement.

createFunction()

Creates a new function that can be used in SQL. See mozIStorageFunction for sample code and more details.

If you use your connection on multiple threads, your function needs to be threadsafe, or it should only be called on one thread.

 void createFunction(
   in AUTF8String aFunctionName,
   in long aNumArguments,
   in mozIStorageFunction aFunction
 );

Parameters

aFunctionName

The name of function to create, as seen in SQL.

aNumArguments

The number of arguments the function takes. Pass -1 for variable-argument functions.

aFunction

The instance of mozIStorageFunction that implements the function.

createStatement()

Creates a mozIStorageStatement for the given SQL expression. The expression may use "?#" to indicate sequentially numbered parameters (?1, ?2, etc) or ":name" to indicate named parameters. JavaScript callers should use named parameters.

 mozIStorageStatement createStatement(
   in AUTF8String aSQLStatement
 );

Parameters

aSQLStatement

The SQL statement to execute.

Return value

Returns a new mozIStorageStatement to be used to execute the specified statement.

createTable()

This method creates a table with the given table name and schema.

 void createTable(
   in string aTableName,
   in string aTableSchema
 );

Parameters

aTableName

The name of the table to create; table names may consist of the letters A-Z in either upper or lower case, the underscore, and the digits 0-9. The first character must be a letter.

aTableSchema

The table's schema. This should be specified using the same syntax the CREATE TABLE statement uses. For example: "foo INTEGER, bar STRING".

Exceptions thrown

NS_ERROR_FAILURE

Table already exists or the requested table couldn't be created.

Asynchronously executes an array of queries created with this connection, using any currently bound parameters. The statements are run wrapped in a transaction.

mozIStoragePendingStatement executeAsync(
  [array, size_is(aNumStatements)] in mozIStorageBaseStatement aStatements,
  in unsigned long aNumStatements,
  in mozIStorageStatementCallback aCallback Optional
);

Parameters

aStatements

The array of statements to execute asynchronously. They will be executed sequentially, in the order in which they appear in the array. Prior to Gecko 2.0 this was type mozIStorageStatement.

aNumStatements

The number of statements in aStatements.

aCallback Optional

A mozIStorageStatementCallback object to receive progress, error, and completion notifications.

Return value

A mozIStoragePendingStatement object that can be used to cancel the statements' execution.

executeSimpleSQL()

Executes an SQL expression that has no bound parameters.

 void executeSimpleSQL(
   in AUTF8String aSQLStatement
 );

Parameters

aSQLStatement

The SQL statement to execute.

indexExists()

This method determines whether or not the given index exists.

 boolean indexExists(
   in AUTF8String aIndexName
 );

Parameters

aIndexName

The index to check.

Return value

true if the index exists, false otherwise.

This is used to preload the database cache. It loads pages from the start of the database file until the memory cache (specified by "PRAGMA cache_size=") is full or the entire file is read.

The cache MUST be active on the database for this to work. This means that you must have a transaction open on the connection, or have a transaction open on another connection that shares the same pager cache. This cached data will go away when the transaction is closed.

This preload operation can dramatically speed up read operations because the data is loaded as one large block. Normally, pages are read in on demand, which can cause many disk seeks.

void preload();

Parameters

None.

Deletes a custom SQL function that was created with either mozIStorageConnection.createFunction() or mozIStorageConnection.createAggregateFunction().

 void removeFunction(
   in AUTF8String aFunctionName
 );

Parameters

aFunctionName

The name of the function to remove.

Removes the progress handler that was registered with mozIStorageConnection.registerProgressHandler().

 mozIStorageProgressHandler removeProgressHandler();

Parameters

None.

Return value

Returns the previous registered handler.

rollbackTransaction()

This method rolls back the current transaction. This is essentially an "undo," and returns the database to the state it was in before the transaction began.

 void rollbackTransaction();

Parameters

None.

Lets you set the amount by which the SQLite database file is grown or shrunk when resizing is necessary. This helps avoid disk fragmentation by letting you help SQLite make intelligent decisions about resizing of the file.

void setGrowthIncrement(
  in PRInt32 aIncrement,
  in AUTF8String aDatabaseName
);

Parameters

aIncrement

The number of bytes at a time the database file should grow by.

aDatabaseName

The database file for which to adjust the increment size. If you specify an empty string, the main database file is used. See file_control for more details.

This method sets a progress handler. Only one handler can be registered at a time, so if you need more than one, you will have to chain them.

 mozIStorageProgressHandler setProgressHandler(
   in PRInt32 aGranularity,
   in mozIStorageProgressHandler aHandler
 );

Parameters

aGranularity

The number of SQL virtual machine steps between progress handler callbacks.

aHandler

The mozIStorageProgressHandler instance that is being registered.

Return value

Returns the previous registered handler, or null if none was previously registered.

tableExists()

Determines if there exists a table with the given name.

 boolean tableExists(
   in AUTF8String aTableName
 );

Parameters

aTableName

The SQL table whose existence should be checked.

Return value

Returns true if the table exists, false otherwise.

See also

• Storage mozStorage introduction and how-to article
• mozIStorageStatement Create and execute SQL statements on a SQLite database.
• mozIStorageValueArray Wraps an array of SQL values, such as a result row.
• mozIStorageFunction Create a new SQLite function.
• mozIStorageAggregateFunction Create a new SQLite aggregate function.
• mozIStorageProgressHandler Monitor progress during the execution of a statement.
• mozIStorageStatementWrapper Storage statement wrapper