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 |
void beginTransaction(); |
void beginTransactionAs(in PRInt32 transactionType); |
|
void close(); |
void commitTransaction(); |
void createAggregateFunction(in AUTF8String aFunctionName, in long aNumArguments, in |
|
void createFunction(in AUTF8String aFunctionName, in long aNumArguments, in |
|
void createTable(in string aTableName, in string aTableSchema); |
|
void executeSimpleSQL(in AUTF8String aSQLStatement); |
boolean indexExists(in AUTF8String aIndexName); |
void preload(); Obsolete since Gecko 1.9 |
void removeFunction(in AUTF8String aFunctionName); |
|
void rollbackTransaction(); |
void setGrowthIncrement(in PRInt32 aIncrement, in AUTF8String aDatabaseName); |
|
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 |
|
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.
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.
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 isfalse
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.
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.
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()
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.
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.
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