Readonly affectedaffectedRows returns the number of database rows that were changed or inserted or deleted by last operation.
Readonly connectionIndicates if the connection is open and ready to use. This will be false if the connection failed to open, or it has been closed.
Readonly databaseThe current database nsIFile. Null if the database connection refers to an in-memory database.
Readonly defaultThe default size for SQLite database pages used by mozStorage for new databases.
The default behavior for all transactions run on this connection. Defaults
to TRANSACTION_DEFERRED, and can be overridden for individual
transactions.
Readonly lastThe last error SQLite error code.
Readonly lastThe last SQLite error as a string (in english, straight from the sqlite library).
Readonly lastlastInsertRowID returns the row ID from the last INSERT operation.
The schema version of the database. This should not be used until the database is ready. The schema will be reported as zero if it is not set.
Readonly sharedDBMutexThe mutex used for protection of operations (BEGIN/COMMIT/ROLLBACK) in mozStorageTransaction. The lock must be held in a way that spans whole operation, not just when accessing the nesting level.
Readonly transactionReturns true if a transaction is active on this connection.
Note that this is true if a transaction is active on the connection, regardless of how it was opened. There are several ways to open one:
beginTransaction on a mozIStorageConnection.executeSimpleSQL("BEGIN") or
createStatement("BEGIN").execute() on a mozIStorageConnection.createAsyncStatement("BEGIN").executeAsync(...). This is what
Sqlite.sys.mjs does under the hood.Because of this, it's important not to use this attribute to decide
whether to commit the active transaction, because the caller that opened
it may not expect that. This is why both mozStorageTransaction and
Sqlite.sys.mjs use an internal variable (mHasTransaction for the former;
_hasInProgressTransaction for the latter) to check if their transaction
is already in progress, instead of just checking this attribute before
committing. Otherwise, mozStorage might accidentally commit (or roll back!)
a transaction started by Sqlite.sys.mjs, and vice versa.
Readonly variableThe maximum number of bound parameters for statements executed on this
connection. If your statement has more params than this limit, you'll
need to chunk them into multiple statements. See PlacesUtils.chunkArray
and its callers in Places for examples of how to do this, or read on for
an overview.
Keep in mind that the variable limit is for the total number of
parameters, including ones bound by name (using the :VVV, @VVV, or
?VVV syntax) and index (? and ?NNN).
This means, when chunking:
WHERE guid IN (?, ?, ?, ...),
your chunk length is just variableLimit.WHERE url_hash IN (hash(?1), hash(?2), ...) AND url IN (?1, ?2, ...)), you can use the
?NNN syntax with a chunk length of variableLimit.variableLimit / N, since you're binding
two params for each element.WHERE parentGuid = :parentGuid AND guid IN (?, ?, ...)),
your chunk length is variableLimit - M, to ensure there's space for the
fixed variables.If you bind more params than this limit, create{Async}Statement will
fail with a "too many SQL variables" error.
Optional aInstancePtr: objectA run time mechanism for interface discovery.
NS_OK if the interface is supported by the associated instance, NS_NOINTERFACE if it is not.
aInstancePtr must not be null.
[in] A requested interface IID
[out] A pointer to an interface pointer to receive the result.
Clone a database and make the clone read only if needed. SQL Functions and attached on-disk databases are applied to the new clone.
NS_ERROR_NOT_SAME_THREAD If is called on a thread other than the one that opened it.
NS_ERROR_UNEXPECTED If this connection is a memory database.
If your connection is already read-only, you will get a read-only clone.
The resulting connection will implement mozIStorageConnection, but
all synchronous methods will throw if called from the main thread.
Due to a bug in SQLite, if you use the shared cache (see mozIStorageService), you end up with the same privileges as the first connection opened regardless of what is specified in aReadOnly.
The following pragmas are copied over to a read-only clone:
If true, the returned database should be put into read-only mode.
A callback that will be notified when the operation is complete, with the following arguments:
Close this database connection, allowing all pending statements to complete first.
NS_ERROR_NOT_SAME_THREAD If called on a thread other than the one that opened it. The callback will not be dispatched.
NS_ERROR_NOT_INITIALIZED If called on a connection that has already been closed or was never properly opened. The callback will still be dispatched to the main thread despite the returned error.
If this call should fail, the callback won't be invoked.
[optional] A callback that will be notified when the close is completed, with the following arguments:
Vacuum the main database plus all the attached one. If the database is in auto_vacuum = INCREMENTAL mode, this executes an incremental_vacuum, otherwise it will always execute a full vacuum.
While it's possible to invoke this method directly, it's suggested, when possible, to use the VacuumManager instead. That means registering your component for the "vacuum-participant" XPCOM category, and implement the mozIStorageVacuumParticipant interface.
If it's not possible to start the async vacuum operation, note in this case the callback won't be invoked.
Vacuum will fail inside a transaction, or if there is an ongoing read statement.
Optional aCallback: anyCompletion callback invoked once the operation is complete.
Optional aUseIncremental: null | booleanWhen set to true, this will try to convert the main schema to auto_vacuum = INCREMENTAL mode, if it's not set yet. When set to false, it will try to set auto_vacuum = NONE. Note a full vacuum will be executed if the auto_vacuum mode must be changed, otherwise an incremental vacuum will happen if the database is already in INCREMENTAL mode.
Optional aSetPageSize: null | numberThis can be used to change the database page_size, a full vacuum will be executed to persist the change. If the page size is already correct, or you pass 0, this will be a no-op.
Clones a database connection and makes the clone read only if needed. SQL Functions and attached on-disk databases are applied to the new clone.
the cloned database connection.
NS_ERROR_UNEXPECTED If this connection is a memory database.
If your connection is already read-only, you will get a read-only clone.
Due to a bug in SQLite, if you use the shared cache (openDatabase), you end up with the same privileges as the first connection opened regardless of what is specified in aReadOnly.
The following pragmas are copied over to a read-only clone:
If true, the returned database should be put into read-only mode. Defaults to false.
Closes a database connection. Callers must finalize all statements created for this connection prior to calling this method. It is illegal to use call this method if any asynchronous statements have been executed on this connection.
NS_ERROR_UNEXPECTED If any statement has been executed asynchronously on this object.
NS_ERROR_UNEXPECTED If is called on a thread other than the one that opened it.
Create an asynchronous statement for the given SQL. 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 sequential numbered arguments, ?1, ?2 etc. to indicate specific numbered arguments or :name and $var to indicate named arguments.
a new mozIStorageAsyncStatement
The statement is created lazily on first execution.
The SQL statement to execute.
Create a new SQL function. If you use your connection on multiple threads, your function needs to be threadsafe, or it should only be called on one thread.
The name of function to create, as seen in SQL.
The number of arguments the function takes. Pass -1 for variable-argument functions.
The instance of mozIStorageFunction, which implements the function in question.
Create a mozIStorageStatement for the given SQL expression. The expression may use ? to indicate sequential numbered arguments, ?1, ?2 etc. to indicate specific numbered arguments or :name and $var to indicate named arguments.
a new mozIStorageStatement
The SQL statement to execute.
Create the table with the given name and schema.
If the table already exists, NS_ERROR_FAILURE is thrown. (XXX at some point in the future it will check if the schema is the same as what is specified, but that doesn't happen currently.)
NS_ERROR_FAILURE If the table already exists or could not be created for any other reason.
The table name to be created, consisting of [A-Za-z0-9_], and beginning with a letter.
The schema of the table; what would normally go between the parens in a CREATE TABLE statement: e.g., "foo INTEGER, bar STRING".
Execute an array of statements created with this connection using any currently bound parameters. When the array contains multiple statements, the execution is wrapped in a single transaction. These statements can be reused immediately, and reset does not need to be called.
an object that can be used to cancel the statements execution.
If you have any custom defined functions, they must be re-entrant since they can be called on multiple threads.
The array of statements to execute asynchronously, in the order they are given in the array.
[optional] The callback object that will be notified of progress, errors, and completion.
Execute asynchronously an SQL expression, expecting no arguments.
an object that can be used to cancel the statement execution.
The SQL statement to execute
[optional] The callback object that will be notified of progress, errors, and completion.
Get quota objects.
@param[out] aDatabaseQuotaObject The QuotaObject associated with the database file. @param[out] aJournalQuotaObject The QuotaObject associated with the journal file.
NS_ERROR_NOT_INITIALIZED.
Causes any pending database operation to abort and return at the first opportunity.
this cannot be used on mozIStorageConnection unless the connection is
explicitly marked as interruptible. For more details, please
refer to CONNECTION_INTERRUPTIBLE in mozIStorageService.
operations that are nearly complete may still be able to complete.
if used on an unsupported connection type, or a closed connection.
Controls SQLITE_FCNTL_CHUNK_SIZE setting in sqlite. This helps avoid fragmentation by growing/shrinking the database file in SQLITE_FCNTL_CHUNK_SIZE increments. To conserve memory on systems short on storage space, this function will have no effect on mobile devices or if less than 500MiB of space is left available.
NS_ERROR_FILE_TOO_BIG If the system is short on storage space.
The database file will grow in multiples of chunkSize.
Sqlite database name. "" means pass NULL for zDbName to sqlite3_file_control. See http://sqlite.org/c3ref/file_control.html for more details.
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. This progress handler should be threadsafe if you use this connection object on more than one thread.
previous registered handler.
The number of SQL virtual machine steps between progress handler callbacks.
The instance of mozIStorageProgressHandler.
Forcibly closes a database connection synchronously. This should only be used when it's required to close and replace the database synchronously to return control to the consumer, for example in case of a detected corruption on database opening. Since this spins the events loop, it should be used only in very particular and rare situations, or it may cause unexpected consequences (crashes).
NS_ERROR_NOT_SAME_THREAD If called on a thread other than the one that opened it.
Generated using TypeDoc
mozIStorageConnection represents a database connection attached to a specific file or to the in-memory data storage. It is the primary interface for interacting with a database, including creating prepared statements, executing SQL, and examining database errors.
Note
From the main thread, you should rather use mozIStorageAsyncConnection.
Threadsafe