Readonly databaseThe current database nsIFile. Null if the database connection refers to an in-memory database.
The default behavior for all transactions run on this connection. Defaults
to TRANSACTION_DEFERRED, and can be overridden for individual
transactions.
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.
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.
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.
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.
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
mozIStorageAsyncConnection represents an asynchronous database connection attached to a specific file or to an in-memory data storage. It is the primary interface for interacting with a database from the main thread, including creating prepared statements, executing SQL, and examining database errors.