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.

See also

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.

See also

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.

See also

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

See also

Indicates whether this connection is currently involved in a transaction.

See also

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."

See also

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.

See also

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 file, the value is 0.

See also

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

See also

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 event. 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, according to whether the main database was connected using the open() method or the openAsync() method.

Parameters

See also

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.

Nested transactions are not allowed (nested calls to begin() are ignored). 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.

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

See also

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

See also

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 committed. 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.

Parameters

See also

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

See also

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

Parameters

See also

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.

See also

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

See also

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

See also

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

See also

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

See also

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.

Parameters

See also

Dispatched when an analyze() operation completes successfully.

See also

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

See also

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

See also

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

See also

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

See also

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

See also

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

See also

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

See also

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.

See also

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

See also

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.

See also

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

See also

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

See also

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

See also

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

See also

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:

See also