storage/public/mozIStorageConnection.idlScriptable
This interface represents a database connection attached to a specific file or an in-memory database. It is the primary interface for interacting with a database, including creating prepared statements, executing SQL, and examining database errors.
1.0
68
Introduced
Gecko 1.8
Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

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

Method overview

void asyncClose([optional] in mozIStorageCompletionCallback aCallback);
void beginTransaction();
void beginTransactionAs(in PRInt32 transactionType);
mozIStorageStatement clone([optional] in boolean aReadOnly);
void close();
void commitTransaction();
void createAggregateFunction(in AUTF8String aFunctionName, in long aNumArguments, in mozIStorageAggregateFunction aFunction);
mozIStorageAsyncStatement createAsyncStatement(in AUTF8String aSQLStatement);
void createFunction(in AUTF8String aFunctionName, in long aNumArguments, in mozIStorageFunction aFunction);
mozIStorageStatement createStatement(in AUTF8String aSQLStatement);
void createTable(in string aTableName, in string aTableSchema);
mozIStoragePendingStatement executeAsync([array, size_is(aNumStatements)] in mozIStorageBaseStatement aStatements, in unsigned long aNumStatements, [optional] in mozIStorageStatementCallback aCallback );
void executeSimpleSQL(in AUTF8String aSQLStatement);
boolean indexExists(in AUTF8String aIndexName);
void preload(); Obsolete since Gecko 1.9
void removeFunction(in AUTF8String aFunctionName);
mozIStorageProgressHandler removeProgressHandler();
void rollbackTransaction();
void setGrowthIncrement(in PRInt32 aIncrement, in AUTF8String aDatabaseName);
mozIStorageProgressHandler setProgressHandler(in PRInt32 aGranularity, in mozIStorageProgressHandler aHandler);
boolean tableExists(in AUTF8String aTableName);

Attributes

Attribute Type Description
connectionReady boolean Indicates if the connection is open and ready to use. This will be false if the connection failed to open, or it has been closed. Read only.
databaseFile nsIFile The current database nsIFile. null if the database connection refers to an in-memory database. Read only.
lastError long The last SQLite error code that occurred. Read only.

Note: This is not reliable if you are using asynchronous statements or if you are using the connection on multiple threads.
lastErrorString AUTF8String The English error string reported by the SQLite library for the last SQLite operation. Read only.

Note: This is not reliable if you are using asynchronous statements or if you are using the connection on multiple threads.
lastInsertRowID long long The row ID from the last SQL INSERT operation. Read only.

Note: This is not reliable if you are using asynchronous statements or if you are using the connection on multiple threads.
schemaVersion long The schema version of the database. This should not be used until the database is ready. The version will be reported as 0 if it is not set.
transactionInProgress boolean Returns true if there is a transaction in progress on the database. Otherwise returns false. Read only.

Constants

Transaction execution time constants.

Constant Value Description
TRANSACTION_DEFERRED 0 No database lock is obtained until the first statement is run.
TRANSACTION_IMMEDIATE 1 A reserved lock is obtained on the database.
TRANSACTION_EXCLUSIVE 2 An exclusive lock is obtained on the database.

SQLite database page size constant

Constant Value Description
DEFAULT_PAGE_SIZE 32768 The default size for SQLite database pages. This is used by the Storage API when creating new databases, and must match the SQLITE_DEFAULT_PAGE_SIZE configured in db/sqlite3/src/Makefile.in.

Methods

asyncClose()

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.

Note: The database engine does not support nested transactions, so attempting to start a transaction when one is already active will throw an exception.

 void beginTransactionAs(
   in PRInt32 transactionType
 );
Parameters
transactionType
One of the transaction constants (mozIStorageConnection.TRANSACTION_DEFERRED, mozIStorageConnection.TRANSACTION_IMMEDIATE, mozIStorageConnection.TRANSACTION_EXCLUSIVE)

clone()

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

Note: If your connection is already read-only, you will get a read-only clone.

Note: Due to a bug in SQLite, if you use the shared cache (by calling mozIStorageService.openDatabase()), the cloned connection's access privileges will be the same as the original connection, regardless of the value you specify for the aReadOnly parameter.
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.

close()

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

Note: You must not call this method if any asynchronous statements have been executed on the connection. Instead, you should call asyncClose().
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.

createAggregateFunction()

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.

createAsyncStatement()

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.

Note

If the statement is meant to be executed asynchronously, you should rather create it with createAsyncStatement. The resulting statement will be faster to execute. Additionally, the system will be able to inform you if you erroneously attempt to execute it synchronously.

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.

executeAsync()

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

Note: The statements may be reused immediately, and the statements do not need to be reset individually.

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.

Warning: Performing synchronous IO on the main thread can cause serious performance problems. As a result, this method of modifying the database is strongly discouraged!

 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.

preload()

Obsolete since Gecko 1.9 (Firefox 3)

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.

removeFunction()

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.

removeProgressHandler()

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.

setGrowthIncrement()

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.

Note: This works by adjusting the SQLITE_FCNTL_CHUNK_SIZE setting in SQLite.

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.

setProgressHandler()

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.

Note: If you use the asynchronous storage APIs or use your database on multiple threads, the progress handler you register must be threadsafe

 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