mozIStorageConnection

From MDC

The mozIStorageConnection interface represents a database connection attached to a specific file or to in-memory data storage. It is the primary interface for interacting with a database, including creating prepared statements, executing SQL, and examining database errors.

See Storage for an introduction.

Contents 1 Method overview 2 Attributes 3 Constants 4 Methods 4.1 close() 4.1.1 Parameters 4.2 createStatement() 4.2.1 Parameters 4.2.2 Return value 4.3 executeSimpleSQL() 4.3.1 Parameters 4.4 tableExists() 4.4.1 Parameters 4.4.2 Return value 4.5 indexExists() 4.5.1 Parameters 4.5.2 Return value 4.6 beginTransaction() 4.7 beginTransactionAs() 4.7.1 Parameters 4.8 commitTransaction() 4.8.1 Parameters 4.8.2 Exceptions thrown 4.9 rollbackTransaction() 4.9.1 Parameters 4.9.2 Exceptions thrown 4.10 createTable() 4.10.1 Parameters 4.10.2 Exceptions thrown 4.11 createFunction() 4.11.1 Parameters 4.12 createAggregateFunction() 4.12.1 Parameters 4.13 removeFunction() 4.13.1 Parameters 4.14 setProgressHandler() 4.14.1 Parameters 4.14.2 Return value 4.15 removeProgressHandler() 4.15.1 Parameters 4.15.2 Return value 4.16 preload() 4.16.1 Parameters 4.17 Example: Creating a statement without parameters 4.17.1 C++ 4.17.2 JavaScript 4.18 Example: Creating a statement that has parameters 4.18.1 C++ 4.18.2 JavaScript 5 See also

mozIStorageConnection is defined in storage/public/mozIStorageConnection.idl. It is scriptable and unfrozen (hasn't changed since Mozilla 1.9).

Inherits from: nsISupports

[edit] Method overview

void close();

mozIStorageStatement createStatement(in AUTF8String aSQLStatement);

void executeSimpleSQL(in AUTF8String aSQLStatement);

boolean tableExists(in AUTF8String aTableName);

boolean indexExists(in AUTF8String aIndexName);

void beginTransaction();

void beginTransactionAs(in PRInt32 transactionType);

void commitTransaction();

void rollbackTransaction();

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

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

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

void removeFunction(in AUTF8String aFunctionName);

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

mozIStorageProgressHandler removeProgressHandler();

void preload(); Obsolete

[edit] Attributes

Attribute	Type	Description
connectionReady	boolean	Indicates whether or not the connection is open or ready to use. This is false if the connection failed to open or if it has been closed.
databaseFile	nsIFile	The current database file. NULL if the database connection refers to an in-memory database.
lastInsertRowID	long long	The row ID from the last SQL INSERT operation.
lastError	long	The last sqlite error code that occurred.
lastErrorString	AUTF8String	The English error string reported by the sqlite library for the last sqlite operation.
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 not set. since Gecko 1.9 M8
transactionInProgress	boolean	Returns true if there is a transaction in progress on the database; otherwise returns false.

[edit] Constants

Constant	Value	Description
TRANSACTION_DEFERRED	0	Default. The database lock is acquired when needed.
TRANSACTION_IMMEDIATE	1	Get a read lock on the database immediately.
TRANSACTION_EXCLUSIVE	2	Get a write lock on the database immediately.

[edit] Methods

[edit] close()

Closes a database connection. C++ callers should simply set the database variable to NULL. since Gecko 1.9 M8

You need to call finalize() on the statement if you have created one before attempting to close or you will get an NS_ERROR_FILE_IS_LOCKED exception.

void close();

[edit] Parameters

None.

[edit] createStatement()

Creates a mozIStorageStatement for the given SQL expression. The expression may use "?" to indicate sequentially numbered arguments (?1, ?2, etc) or ":name" and "$var" to indicate named arguments.

 mozIStorageStatement createStatement(
   in AUTF8String aSQLStatement
 );

[edit] Parameters

aSQLStatement

The SQL statement to execute.

[edit] Return value

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

[edit] executeSimpleSQL()

Executes an SQL expression. By default, it doesn't expect any arguments at all.

 void executeSimpleSQL(
   in AUTF8String aSQLStatement
 );

[edit] Parameters

aSQLStatement

The SQL statement to execute.

[edit] tableExists()

This method reports whether the given table exists or not.

 boolean tableExists(
   in AUTF8String aTableName
 );

[edit] Parameters

aTableName

The SQL table whose existence should be checked.

[edit] Return value

Returns true if the table exists, false otherwise.

[edit] indexExists()

This method determines whether or not the given index exists.

 boolean indexExists(
   in AUTF8String aIndexName
 );

[edit] Parameters

aIndexName

The index to check.

[edit] Return value

Returns true if the index exists, false otherwise.

[edit] beginTransaction()

Starts a new transaction. By default, SQLite defers transactions. If a transaction is already active, this method throws an exception.

 void beginTransaction();

[edit] beginTransactionAs()

This method starts a new transaction of the given transaction type.

 void beginTransactionAs(
   in PRInt32 transactionType
 );

[edit] Parameters

transactionType

The type of transaction (TRANSACTION_DEFERRED, TRANSACTION_IMMEDIATE or TRANSACTION_EXCLUSIVE).

[edit] commitTransaction()

This method commits the current transaction.

 void commitTransaction();

[edit] Parameters

None.

[edit] Exceptions thrown

NS_ERROR_STORAGE_NO_TRANSACTION

No transaction is active.

[edit] 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();

[edit] Parameters

None.

[edit] Exceptions thrown

NS_ERROR_STORAGE_NO_TRANSACTION

No transaction is active.

[edit] createTable()

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

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

[edit] 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".

[edit] Exceptions thrown

NS_ERROR_FAILURE

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

[edit] createFunction()

Creates a new SQLite function. since Gecko 1.9 M8

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

[edit] 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.

[edit] createAggregateFunction()

This method creates a new SQLite aggregate function. since Gecko 1.9 M8

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

[edit] 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.

[edit] removeFunction()

Deletes a custom SQLite function; it works with both standard and aggregate functions. since Gecko 1.9 M8

 void removeFunction(
   in AUTF8String aFunctionName
 );

[edit] Parameters

aFunctionName

The name of the function to remove.

[edit] setProgressHandler()

This method sets a progress handler. Only one handler can be registered at a time; if you need more than one, you need to chain them yourself. since Gecko 1.9 M8

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

[edit] Parameters

aGranularity

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

aHandler

The instance of mozIStorageProgressHandler.

[edit] Return value

Returns the previous registered handler.

[edit] removeProgressHandler()

Removes a progress handler. since Gecko 1.9 M8

 mozIStorageProgressHandler removeProgressHandler();

[edit] Parameters

None.

[edit] Return value

Returns the previous registered handler.

[edit] preload()

Preloads the database cache by loading pages from the start of the database file until the memory cache (the size of which is specified by PRAGMA cache_size=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();

[edit] Parameters

None.

[edit] Example: Creating a statement without parameters

[edit] C++

rv = mDBConn->ExecuteSimpleSQL(NS_LITERAL_CSTRING("CREATE TABLE foo (a INTEGER)"));

[edit] JavaScript

mDBConn.executeSimpleSQL("CREATE TABLE foo (a INTEGER)");

[edit] Example: Creating a statement that has parameters

[edit] C++

nsCOMPtr<mozIStorageStatement> statement;
rv = mDBConn->CreateStatement(NS_LITERAL_CSTRING("SELECT * FROM foo WHERE a = ?1"),
                              getter_AddRefs(statement));
NS_ENSURE_SUCCESS(rv, rv);

[edit] JavaScript

var statement = mDBConn.createStatement("SELECT * FROM foo WHERE a = ?1");

[edit] 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