SQLConnection  - AS3

Indicates whether autocompacting was enabled when the current database was originally created (the value that was specified for the autoCompact parameter in the open() or openAsync() call that created the database). If this property is true, unused space is removed from the database file automatically after each write operation, keeping the database file smaller. If the property is false, the space previously occupied by removed data is left in the database file and reused when needed. Even when autoCompact is false, you can force the database to reclaim unused space by calling the compact() method.

If the connected property is false, this property is set to false.

Related API Elements

Provides access to the cache size for this connection, which represents the maximum number of database disk pages that are held in memory at one time. Each page uses about 1.5 KB of memory (depending on the value specified for the pageSize parameter of the open() or openAsync() method call that created the database). The default cache size is 2000. If an application is executing UPDATE or DELETE operations that change many rows of a database, increasing the cache size can improve speed at the cost of increased memory consumption.

Related API Elements

Indicates how column names are reported in the result of a SELECT statement.

The constants defined in the SQLColumnNameStyle class represent the possible values for this property:

• SQLColumnNameStyle.LONG indicates that column names are returned in the format [table-name]_[column-name].
• SQLColumnNameStyle.SHORT specifies that column names are given the format [column-name]. If there are multiple columns with the same name, only one property with that name is added to the result object.
• SQLColumnNameStyle.DEFAULT is the default value. When this value is used, result column names are formatted according to the number of tables in the SELECT statement that have similar column names. If the SELECT statement includes only one table, the short name format [column-name] is used, and if the SELECT statement includes multiple tables joined together, whenever there is a naming collision because two column names are identical, the long name format [table-name]_[column-name] is used for the identically named columns.

Related API Elements

Indicates whether the SQLConnection instance has an open connection to a database file.

Related API Elements

Indicates whether this connection is currently involved in a transaction.

Related API Elements

Indicates whether SQLConnection class is supported on the current platform or not.

The last generated row identifier created by a SQL INSERT statement. A row identifier is used to uniquely identify a row in a table within the database. The value is frequently generated by the database.

The value is zero if no database is connected or no INSERT statement has been executed.

The row identifier for a single SQL INSERT statement execution can be obtained through the lastInsertRowID property of the SQLResult object returned by the SQLStatement object's getResult() method (when called after the SQLStatement dispatches its result event).

For more information on primary keys and generated row identifiers, see the "CREATE TABLE" and "Expressions" sections in the appendix "SQL support in local databases."

Related API Elements

Indicates the database page size (in bytes) that was specified when the current database was originally created (the value that was specified for the pageSize parameter in the open() or openAsync() call that created the database).

If the connected property is false, this property's value is 0.

The page size for a database can be changed (using the open() or openAsync() methods) until the first table is created in the database.

Related API Elements

Contains the total number of data changes that have been made since the connection to the database was opened. In addition to tracking changes made by INSERT, DELETE, and UPDATE statements, this value includes changes caused by triggers.

When the database connection is closed, the value is reset to 0. When the SQLConnection instance isn't connected to a database, the value is 0.

Related API Elements

Creates a SQLConnection instance.

Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. You can register event listeners on all nodes in the display list for a specific type of event, phase, and priority.

After you successfully register an event listener, you cannot change its priority through additional calls to addEventListener(). To change a listener's priority, you must first call removeListener(). Then you can register the listener again with the new priority level.

Keep in mind that after the listener is registered, subsequent calls to addEventListener() with a different type or useCapture value result in the creation of a separate listener registration. For example, if you first register a listener with useCapture set to true, it listens only during the capture phase. If you call addEventListener() again using the same listener object, but with useCapture set to false, you have two separate listeners: one that listens during the capture phase and another that listens during the target and bubbling phases.

You cannot register an event listener for only the target phase or the bubbling phase. Those phases are coupled during registration because bubbling applies only to the ancestors of the target node.

If you no longer need an event listener, remove it by calling removeEventListener(), or memory problems could result. Event listeners are not automatically removed from memory because the garbage collector does not remove the listener as long as the dispatching object exists (unless the useWeakReference parameter is set to true).

Copying an EventDispatcher instance does not copy the event listeners attached to it. (If your newly created node needs an event listener, you must attach the listener after creating the node.) However, if you move an EventDispatcher instance, the event listeners attached to it move along with it.

If the event listener is being registered on a node while an event is being processed on this node, the event listener is not triggered during the current phase but can be triggered during a later phase in the event flow, such as the bubbling phase.

If an event listener is removed from a node while an event is being processed on the node, it is still triggered by the current actions. After it is removed, the event listener is never invoked again (unless registered again for future processing).

Parameters

function(evt:Event):void

Gathers statistics about database indices and stores them in the database. These statistics can then be used by the query optimizer (the portion of the database engine that determines the most efficient way to execute each statement). The statistics help the query optimizer make better choices about which index or indices to use when executing a particular query.

If a database has indices defined, but the analyze() method hasn't been called, the runtime still uses those indices to execute statements. However, without the additional statistical information generated by the analyze() method, the runtime may not choose the most efficient index for a particular query.

When a table's data changes (as a result of INSERT, UPDATE, or DELETE statements) the indices associated with that table change as well. The statistical information generated by analyze() is not automatically updated. Consequently, after a large number of data changes, calling the analyze() method again might be beneficial. However, the benefit obtained from calling analyze() again depends on several factors, including the number of indices defined on a table, the relationship between the number of changed rows and the total number of rows in the table, how much variation there is in the table's indexed data, and how different the changed data is from the prechange data.

The resourceName parameter indicates whether the operation is performed on the indices of all attached databases, a specific database, or a specific table.

Each time this method is called, any previously created statistical data is purged and recreated for the database or table specified in the resourceName parameter (or all tables in all connected databases if resourceName is null). This method can be called at any time while a database connection is open. The analyze() operation and its statistical data are not included in a transaction; however, it is best not to call analyze() when the database has a current transaction (the inTransaction property is true). This is because any data, table schema, or index changes that have been executed in the transaction but not yet committed are not taken into account by the analyze() call, and the analyze() data is out of date as soon as the transaction is committed.

To remove the statistical data created with the analyze() method, use the deanalyze() method.

Parameters

Related API Elements

Adds another database to the SQLConnection instance, giving the new database the specified name. Attaching a database allows that database to be used in SQL statements executed against this SQLConnection instance.

If a database is already attached using the specified name, calling attach() results in an error. However, the same database may be attached multiple times using unique names. Only ten databases can be attached to a single SQLConnection instance.

Any SQL statement can be executed on a database connected using attach() that can be executed on the main database (the database connected using open() or openAsync()). A SQL statement can access tables in any of the databases attached to the statement's associated SQLConnection instance, including accessing tables from multiple databases in a single statement. When the runtime is resolving table names in a statement, it searches through the SQLConnection instance's databases in the order in which the databases were attached, starting with the database that was connected using the open() or openAsync() method. Use the database name (as specified in the attach() method's name parameter) in the statement to explicitly qualify a table name.

To remove a database attached using the attach() method, use the detach() method. When the SQLConnection instance is closed (by calling the close() method), all attached databases are detached.

The attached database uses the same execution mode (synchronous or asynchronous) as the main database, depending on whether the main database was connected using the open() method or the openAsync() method.

Parameters

More examples

Related API Elements

Begins a transaction within which all SQL statements executed against the connection's database or databases are grouped.

By default, each SQL statement is executed within its own transaction, and the transaction ends when the statement's execution succeeds or fails. Creating a transaction using the begin() method causes a new, manual transaction to be created. From that point on, all SQL statements executed against the SQLConnection instance take place within the transaction, and any actions or modifications performed by the statements can be committed (made permanent) or rolled back (undone) as a group.

To end a transaction, call the commit() or rollback() method, depending on whether the changes made by the transactions' statements are to be made permanent or discarded.

Nested calls to begin() are ignored. You can create savepoints, which are like bookmarks within a transaction, by calling the setSavepoint() method. You can then partially commit or roll back SQL statements by calling the releaseSavepoint() or rollbackToSavepoint() methods. However, if a transaction is started by calling begin(), changes are not permanently committed to the database until the commit() method is called.

If the database connection closes while a transaction is currently open, AIR rolls back the transaction automatically. (Note: for AIR 1.1 and previous versions, an open transaction is automatically committed when a connection closes.)

A transaction is not limited to statement executions in a single database; it can include statements executed on different attached databases.

Parameters

Related API Elements

package
{
    import flash.data.SQLConnection;
    import flash.data.SQLResult;
    import flash.data.SQLStatement;
    import flash.display.Sprite;
    import flash.events.SQLErrorEvent;
    import flash.events.SQLEvent;
    import flash.filesystem.File;
    
    public class MultiInsertTransactionExample extends Sprite
    {
        private var conn:SQLConnection;
        private var insertEmployee:SQLStatement;
        private var insertPhoneNumber:SQLStatement;
        
        public function MultiInsertTransactionExample():void
        {
            // define where to find the database file
            var appStorage:File = File.applicationStorageDirectory;
            var dbFile:File = appStorage.resolvePath("ExampleDatabase.db");
            
            // open the database connection
            conn = new SQLConnection();
            conn.addEventListener(SQLErrorEvent.ERROR, errorHandler);
            conn.addEventListener(SQLEvent.OPEN, openHandler);
            conn.openAsync(dbFile);
        }
        
        // Called when the database is connected
        private function openHandler(event:SQLEvent):void
        {
            conn.removeEventListener(SQLEvent.OPEN, openHandler);
            
            // start a transaction
            conn.addEventListener(SQLEvent.BEGIN, beginHandler);
            conn.begin();
        }
        
        // Called when the transaction begins
        private function beginHandler(event:SQLEvent):void
        {
            conn.removeEventListener(SQLEvent.BEGIN, beginHandler);
            
            // create and execute the first SQL statement:
            // insert an employee record
            insertEmployee = new SQLStatement();
            insertEmployee.sqlConnection = conn;
            insertEmployee.text = 
                "INSERT INTO employees (lastName, firstName, email) " + 
                "VALUES (:lastName, :firstName, :email, :birthday)";
            insertEmployee.parameters[":lastName"] = "Smith";
            insertEmployee.parameters[":firstName"] = "Bob";
            insertEmployee.parameters[":email"] = "bsmith@example.com";
            insertEmployee.parameters[":birthday"] = new Date(1971, 8, 12);
            
            insertEmployee.addEventListener(SQLEvent.RESULT, insertEmployeeHandler);
            insertEmployee.addEventListener(SQLErrorEvent.ERROR, errorHandler);
            
            insertEmployee.execute();
        }
        
        // Called after the employee record is inserted
        private function insertEmployeeHandler(event:SQLEvent):void
        {
            insertEmployee.removeEventListener(SQLEvent.RESULT, insertEmployeeHandler);
            insertEmployee.removeEventListener(SQLErrorEvent.ERROR, errorHandler);
            
            // Get the employee id of the newly created employee row
            var result:SQLResult = insertEmployee.getResult();
            var employeeId:Number = result.lastInsertRowID;
            
            // Add a phone number to the related phoneNumbers table
            insertPhoneNumber = new SQLStatement();
            insertPhoneNumber.sqlConnection = conn;
            insertPhoneNumber.text =
                "INSERT INTO phoneNumbers (employeeId, type, number) " +
                "VALUES (:employeeId, :type, :number)";
            insertPhoneNumber.parameters[":employeeId"] = employeeId;
            insertPhoneNumber.parameters[":type"] = "Home";
            insertPhoneNumber.parameters[":number"] = "(555) 555-1234";
            
            insertPhoneNumber.addEventListener(SQLEvent.RESULT, insertPhoneNumberHandler);
            insertPhoneNumber.addEventListener(SQLErrorEvent.ERROR, errorHandler);
            
            insertPhoneNumber.execute();
        }
        
        // Called after the phone number record is inserted
        private function insertPhoneNumberHandler(event:SQLEvent):void
        {
            insertPhoneNumber.removeEventListener(SQLEvent.RESULT, insertPhoneNumberHandler);
            insertPhoneNumber.removeEventListener(SQLErrorEvent.ERROR, errorHandler);
            
            // No errors so far, so commit the transaction
            conn.addEventListener(SQLEvent.COMMIT, commitHandler);
            conn.commit();
        }
        
        // Called after the transaction is committed
        private function commitHandler(event:SQLEvent):void
        {
            conn.removeEventListener(SQLEvent.COMMIT, commitHandler);
            
            trace("Transaction complete");
        }
        
        // Called whenever an error occurs
        private function errorHandler(event:SQLErrorEvent):void
        {
            // If a transaction is happening, roll it back
            if (conn.inTransaction)
            {
                conn.addEventListener(SQLEvent.ROLLBACK, rollbackHandler);
                conn.rollback();
            }
            
            trace(event.error.message);
            trace(event.error.details);
        }
        
        // Called when the transaction is rolled back
        private function rollbackHandler(event:SQLEvent):void
        {
            conn.removeEventListener(SQLEvent.ROLLBACK, rollbackHandler);
            
            // add additional error handling, close the database, etc.
        }
    }
}

package
{
    import flash.data.SQLConnection;
    import flash.data.SQLResult;
    import flash.data.SQLStatement;
    import flash.display.Sprite;
    import flash.events.SQLErrorEvent;
    import flash.events.SQLEvent;
    import flash.filesystem.File;
    
    public class MultiDeleteTransactionExample extends Sprite
    {
        private var conn:SQLConnection;
        private var deleteEmployee:SQLStatement;
        private var deletePhoneNumbers:SQLStatement;
        
        private var employeeIdToDelete:Number = 25;
        
        public function MultiDeleteTransactionExample():void
        {
            // define where to find the database file
            var appStorage:File = File.applicationStorageDirectory;
            var dbFile:File = appStorage.resolvePath("ExampleDatabase.db");
            
            // open the database connection
            conn = new SQLConnection();
            conn.addEventListener(SQLErrorEvent.ERROR, errorHandler);
            conn.addEventListener(SQLEvent.OPEN, openHandler);
            conn.openAsync(dbFile);
        }
        
        // Called when the database is connected
        private function openHandler(event:SQLEvent):void
        {
            conn.removeEventListener(SQLEvent.OPEN, openHandler);
            
            // start a transaction
            conn.addEventListener(SQLEvent.BEGIN, beginHandler);
            conn.begin();
        }
        
        // Called when the transaction begins
        private function beginHandler(event:SQLEvent):void
        {
            conn.removeEventListener(SQLEvent.BEGIN, beginHandler);
            
            // Create and execute the first SQL statement:
            // Delete an employee's phone number records
            deletePhoneNumbers = new SQLStatement();
            deletePhoneNumbers.sqlConnection = conn;
            deletePhoneNumbers.text =
                "DELETE FROM phoneNumbers " +
                "WHERE employeeId = :employeeId";
            deletePhoneNumbers.parameters[":employeeId"] = employeeIdToDelete;
            
            deletePhoneNumbers.addEventListener(SQLEvent.RESULT, deletePhoneNumbersHandler);
            deletePhoneNumbers.addEventListener(SQLErrorEvent.ERROR, errorHandler);
            
            deletePhoneNumbers.execute();
        }
        
        // Called after the phone number records are deleted
        private function deletePhoneNumbersHandler(event:SQLEvent):void
        {
            deletePhoneNumbers.removeEventListener(SQLEvent.RESULT, deletePhoneNumbersHandler);
            deletePhoneNumbers.removeEventListener(SQLErrorEvent.ERROR, errorHandler);
            
            deleteEmployee = new SQLStatement();
            deleteEmployee.sqlConnection = conn;
            deleteEmployee.text = 
                "DELETE FROM employees " + 
                "WHERE employeeId = :employeeId";
            deleteEmployee.parameters[":employeeId"] = employeeIdToDelete;
            
            deleteEmployee.addEventListener(SQLEvent.RESULT, deleteEmployeeHandler);
            deleteEmployee.addEventListener(SQLErrorEvent.ERROR, errorHandler);
            
            deleteEmployee.execute();
        }
        
        // Called after the employee record is deleted
        private function deleteEmployeeHandler(event:SQLEvent):void
        {
            deleteEmployee.removeEventListener(SQLEvent.RESULT, deleteEmployeeHandler);
            deleteEmployee.removeEventListener(SQLErrorEvent.ERROR, errorHandler);
            
            // No errors so far, so commit the transaction
            conn.addEventListener(SQLEvent.COMMIT, commitHandler);
            conn.commit();
        }
        
        // Called after the transaction is committed
        private function commitHandler(event:SQLEvent):void
        {
            conn.removeEventListener(SQLEvent.COMMIT, commitHandler);
            
            trace("Transaction complete");
        }
        
        // Called whenever an error occurs
        private function errorHandler(event:SQLErrorEvent):void
        {
            // If a transaction is happening, roll it back
            if (conn.inTransaction)
            {
                conn.addEventListener(SQLEvent.ROLLBACK, rollbackHandler);
                conn.rollback();
            }
            
            trace(event.error.message);
            trace(event.error.details);
        }
        
        // Called when the transaction is rolled back
        private function rollbackHandler(event:SQLEvent):void
        {
            conn.removeEventListener(SQLEvent.ROLLBACK, rollbackHandler);
            
            // add additional error handling, close the database, etc.
        }
    }
}

Aborts all SQL statements that are currently executing on databases connected to the SQLConnection instance. This method can be used to stop long running or runaway queries.

If there are statements executing when the cancel() method is called, this method aborts the statements' operations and any incomplete updates or transactions are rolled back. If there are no statements currently executing, calling this method rolls back an open transaction but otherwise does nothing.

Parameters

Related API Elements

Closes the current database connection. Any attached databases are detached as well.

If there is an open transaction when close() is called, the transaction is rolled back. When a SQLConnection instance is garbage-collected, the runtime calls close() automatically, including if an AIR application is closed while a SQLConnection is still connected to a database.

Parameters

Commits an existing transaction, causing any actions performed by the transaction's statements to be permanently applied to the database.

Intermediate savepoints, which are like bookmarks in a transaction, can be created by calling the setSavepoint() method. Using savepoints you can commit portions of a transaction by calling the releaseSavepoint() method, or roll back portions of a transaction by calling the rollbackToSavepoint() method. However, if a transaction is opened using the begin() method, changes are not permanently saved to the database until the entire transaction is committed by calling the commit() method.

For a transaction that uses savepoints, any statements that were rolled back using the rollbackToSavepoint() method are not committed when the entire transaction is committed. Statements that were committed using releaseSavepoint() or whose savepoints weren't released or rolled back are committed to the database.

Parameters

Related API Elements

Reclaims all unused space in the database. When an object (table, index, or trigger) is dropped from the database, it leaves behind empty space. This makes the database file larger than it needs to be, but can speed up INSERT operations. Over time, INSERT and DELETE operations can leave the database file structure fragmented, which slows down disk access to the database contents. This method compacts the database file, eliminating free pages, aligning table data to be contiguous, and otherwise cleaning up the database file structure.

The compact() operation can't be performed on an attached database file; it can only be performed on the main (original) database file opened by the SQLConnection instance. This operation fails if there is an active transaction, and has no effect on an in-memory database.

Parameters

Removes all statistical information created by a call to the analyze() method.

Because the statistics generated by the analyze() method take up space in a database, calling deanalyze() allows you to reclaim that space, such as after dropping several indices or tables.

This operation is not included in an active transaction.

Parameters

Related API Elements

Detaches an additional database previously attached to the SQLConnection instance using the attach() method. It is possible to have the same database attached multiple times using different names, and detaching one connection leaves the others intact. A database cannot be detached if the connection has an open transaction (if the inTransaction property is true).

Parameters

More examples

Related API Elements

Provides access to the result of a call to the loadSchema() method. The getSchemaResult() method behaves as a first-in, first-out queue of results. Each time the loadSchema() method call completes (each time the schema event is dispatched in asynchronous execution mode), a new SQLSchemaResult object is added to the queue. Each time the getSchemaResult() method is called, the earliest result (the one that was added to the queue first) is returned and removed from the queue. When there are no more objects left in the queue, getSchemaResult() returns null.

When the database connection is closed the method returns null.

Related API Elements

Loads schema information from the connected database or any attached databases. The schema indicates the structure of the database's tables, columns, indices, and triggers.

To access the loaded schema use the SQLConnection.getSchemaResult() method.

In asynchronous execution mode, a schema event is dispatched if the operation is successful, or an error event is dispatched if the operation fails.

The combination of the type and name parameter values determines the type of schema data that's generated by the loadSchema() method and, consequently, the values of the properties of the SQLSchemaResult instance that's generated. The following table lists the valid type and name pairs and the schema data that's generated as a result:

If the combination of type and name arguments does not correspond to one of the specified combinations, an error event is dispatched in asynchronous execution mode or an exception is thrown in synchronous execution mode. For instance, if the type argument is SQLViewSchema and the name argument is the name of a table (rather than the name of a view), an error is raised indicating that the database doesn't contain an object of the specified type with the specified name.

If the database is empty (it doesn't contain any tables, views, triggers, or indices), calling the loadSchema() method results in an error.

Parameters

Related API Elements

Opens a synchronous connection to the database file at the specified location in the file system, or creates and opens a new database file at the location, or creates and opens an in-memory database. The operations of creating and opening the database, as well as all other operations that are performed using this SQLConnection instance (including statement execution and other operations performed by a SQLStatement instance associated with this SQLConnection instance) are performed synchronously when the database is opened using this method. To perform operations asynchronously, open the database connection using the openAsync() method instead.

Once a database is connected, use a SQLStatement instance to execute SQL commands. Database-level operations such as beginning or ending transactions, loading schema information, and other operations are performed using the SQLConnection instance.

A database that is connected using the open() method is automatically assigned the database name "main". That name can be used to explicitly qualify table names in SQL statements using the format [database-name].[table-name].

Parameters

More examples

Related API Elements

Opens an asynchronous connection to the database file at the specified location in the file system, or creates and opens a new database file at the location, or creates and opens an in-memory database. The operations of creating and opening the database, as well as all other operations that are performed using this SQLConnection instance (including statement execution and other operations performed by a SQLStatement instance associated with this SQLConnection instance) are performed asynchronously when the database is opened using this method. To perform operations synchronously, open the database connection using the open() method instead.

Once a database is connected, use a SQLStatement instance to execute SQL commands. Database-level operations such as beginning or ending transactions, loading schema information, and other operations are performed using the SQLConnection instance.

A database that is connected using the openAsync() method is automatically assigned the database name "main"; that name can be used to explicitly qualify table names in SQL statements using the format [database-name].[table-name].

Parameters

More examples

Related API Elements

Changes the encryption key of an encrypted database. This method only affects the encryption key of the main database (the database that was connected using the open() or openAsync() method). You can only call reencrypt() on a database that was encrypted when it was created. Once a database has been created as an encrypted database, it cannot be unencrypted. Likewise, a database that is created without encryption cannot be encrypted later.

The reencryption operation runs in its own transaction. If the reencryption process is interrupted, the database rolls back the transaction and the encryption key is not changed.

Parameters

More examples

Related API Elements

This method commits the SQL operations made since the most recent savepoint or the named savepoint if a name is specified.

Note that until the entire transaction is committed, any changes are not permanently saved to the database. If the transaction is started using the begin() method, you must call the commit() method to commit the entire transaction. If the transaction is started by calling setSavepoint() while inTransaction is false, you can finish the entire transaction either by calling the commit() method or by calling releaseSavepoint() or rollbackToSavepoint() for the first savepoint of the transaction.

If the code calls the rollback() method, it permanently discards all changes in the transaction, regardless of whether releaseSavepoint() is called before the transaction is rolled back.

If this method is called with no parameters (or with null for the name parameter), it commits all database changes since the most recent unnamed savepoint (the most recent savepoint created by calling setSavepoint() with no name parameter). For example, if the setSavepoint() method has been called three times, three savepoints are set. Calling releaseSavepoint() at that point commits the SQL operations performed since the third (newest) savepoint.

If a value is provided for the name parameter this method commits all the SQL operations performed since the savepoint with the specified name. If other savepoints have been created more recently than the specified savepoint, operations performed after those savepoints are committed also.

Once a savepoint is released or rolled back, that savepoint and any more recent savepoints are removed. If code executes additional SQL operations after a releaseSavepoint() or rollbackToSavepoint() call removes a savepoint, those operations belong to the most recent remaining savepoint. (In other words, they belong to the savepoint created most recently before the removed savepoint.) If no savepoint remains, the operations belong to the main transaction.

Parameters

Related API Elements

Removes a listener from the EventDispatcher object. If there is no matching listener registered with the EventDispatcher object, a call to this method has no effect.

Parameters

Rolls back an existing transaction created using the begin() method, meaning all changes made by any SQL statements in the transaction are discarded.

Intermediate savepoints can be marked within a transaction by calling the setSavepoint() method. Using savepoints you can commit portions of a transaction by calling the releaseSavepoint() method, or roll back portions of a transaction by calling rollbackToSavepoint(). However, calling the rollback() method permanently discards all changes made in a transaction, regardless of whether individual savepoints have been released (committed) before the transaction is rolled back.

Parameters

Related API Elements

Rolls back any SQL operations since the most recent savepoint or the named savepoint if a name is specified.

Note that if the entire transaction is committed by calling the commit() method, any changes in the transaction that are not already rolled back using the rollbackToSavepoint() method are permanently saved to the database. In addition, calling the rollback() method permanently discards all changes, regardless of whether individual savepoints have been released (committed) or rolled back before the transaction is rolled back.

If this method is called with no parameters (or with null for the name parameter), it rolls back all database changes since the most recent unnamed savepoint (the most recent call to setSavepoint() with no name parameter value).

If a value is provided for the name parameter this method rolls back all the SQL operations performed since the savepoint with the specified name. If other savepoints have been created more recently than the specified savepoint, operations performed since those savepoints are rolled back also.

Once a savepoint is released or rolled back, that savepoint and any more recent savepoints are removed. If code executes additional SQL operations after a releaseSavepoint() or rollbackToSavepoint() call removes a savepoint, those operations belong to the most recent remaining savepoint. (In other words, they belong to the savepoint created most recently before the removed savepoint.) If no savepoint remains, the operations belong to the main transaction.

Parameters

Related API Elements

Creates a savepoint, which is like a bookmark within a database transaction. A savepoint represents a point within a transaction. The set of SQL operations performed between savepoints can be committed or rolled back separately from other operations using the releaseSavepoint() and rollbackToSavepoint() methods. In this way, using a savepoint allows you to treat a set of SQL operations as a nested transaction.

When the setSavepoint() method is called, if a transaction has not already been opened (by calling the begin() method), calling this method begins the transaction and creates a savepoint at the start of the transaction. If a transaction is already open, calling setSavepoint() creates a savepoint within the transaction.

Note that until the entire transaction is committed, any changes are not permanently saved to the database. If the transaction is started using the begin() method, you must call the commit() method to commit the entire transaction. If the transaction is started by calling setSavepoint() while inTransaction is false, you can finish the entire transaction either by calling the commit() method. The transaction also finishes automatically when you call releaseSavepoint() or rollbackToSavepoint() for the savepoint that started the transaction.

You can specify a name for a savepoint by providing a value for the name parameter. This allows you to to rollback or commit all changes made since that specific savepoint. If no name is specified (the default) then an unnamed savepoint is created.

Once a savepoint is released or rolled back, that savepoint and any more recent savepoints are removed. If code executes additional SQL operations after a releaseSavepoint() or rollbackToSavepoint() call removes a savepoint, those operations belong to the most recent remaining savepoint. (In other words, they belong to the savepoint created most recently before the removed savepoint.) If no savepoint remains, the operations belong to the main transaction.

Parameters

Related API Elements

Dispatched when an analyze() operation completes successfully.

Related API Elements

Dispatched when an attach() method call's operation completes successfully.

Related API Elements

Dispatched when a begin() method call's operation completes successfully.

Related API Elements

Dispatched when a cancel() method call's operation completes successfully.

Related API Elements

Dispatched when a close() method call's operation completes successfully.

Related API Elements

Dispatched when a commit() method call's operation completes successfully.

Related API Elements

Dispatched when a compact() method call's operation completes successfully.

Related API Elements

Dispatched when a deanalyze() method call's operation completes successfully.

Related API Elements

Dispatched when data in any table in any of the connected databases changes as a result of a SQL DELETE command. The data change can be a direct result of a DELETE statement executed through a SQLStatement instance, or an indirect result caused by a trigger firing in response to a statement execution.

Related API Elements

Dispatched when a detach() method call's operation completes successfully.

Related API Elements

Dispatched when any of the SQLConnection object's asynchronous operations results in an error. The SQLErrorEvent instance that's dispatched as the event object has an error property that contains information about the operation that was attempted and the cause of the failure.

Dispatched when data in any table in any of the connected databases changes as a result of a SQL INSERT command. The data change can be a direct result of an INSERT statement executed through a SQLStatement instance, or an indirect result caused by a trigger firing in response to a statement execution.

Related API Elements

Dispatched when an openAsync() method call's operation completes successfully.

Related API Elements

Dispatched when a reencrypt() method call's operation completes successfully.

Related API Elements

Dispatched when a releaseSavepoint() method call's operation completes successfully.

Related API Elements

Dispatched when a rollback() method call's operation completes successfully.

Related API Elements

Dispatched when a rollbackToSavepoint() method call's operation completes successfully.

Related API Elements

Dispatched when a loadSchema() method call's operation completes successfully and the schema results are ready.

Related API Elements

Dispatched when a setSavepoint() method call's operation completes successfully.

Related API Elements

Dispatched when data in any table in any of the connected databases changes as a result of a SQL UPDATE command. The data change can be a direct result of a UPDATE statement executed through a SQLStatement instance, or an indirect result caused by a trigger firing in response to a statement execution.

The update event has the following properties:

Related API Elements