flash.data

# SQLConnection - AS3

Package | flash.data
Class | public class SQLConnection
Inheritance | SQLConnection EventDispatcher Object

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

A SQLConnection instance is used to manage the creation of and connection to local SQL database files (local databases).

The functionality of the SQLConnection class falls into several categories:

- A local SQL database file is created or opened by calling the `open()` method or the SQLConnection instance to the SQLStatement's `sqlConnection` property.

- The SQLConnection class also provides state for SQL statements, including a mechanism for executing multiple statements in a transaction. Transactions are managed using the `begin()`, `commit()`, and `rollback()` methods. In addition, the `setSavepoint()`, `releaseSavepoint()`, and `rollbackToSavepoint()` methods allow code to define and manage savepoints. These are used to subdivide transactions into sets of operations.

- The SQLConnection class provides access to database schema information for connected databases. A database's schema describes the definitions of its tables, columns, indices, and triggers. See the `loadSchema()` method for more information.

- The SQLConnection class provides the ability to encrypt databases using AES with CCM. This provides both authentication and privacy for data. To encrypt a database, a 16 byte key (specified using a ByteArray) must be specified when the database is created. This key can later be changed using the `SQLConnection.reencrypt()` method. Encryption imposes a performance penalty on writes to and reads from the database. Encryption is applied to data stored on the disk, but not to a temporary data cache in memory. Encryption is not supported for in-memory databases.

- A SQLConnection instance can be used to receive database-level event notifications and provide configuration control for all aspects of a database, including cache page size, process canceling, and statement execution options.

A `SQLConnection` instance operates in one of two distinct execution modes: asynchronous and synchronous. To use synchronous execution, you use the `open()` method to connect to the main database for the SQLConnection instance. To use asynchronous execution, use the `openAsync()` method to connect to the main database for the instance.

When you're using asynchronous execution, you use event listeners or a Responder instance to determine when an operation completes or fails. The operations run in the background rather than in the main application thread, so the application continues to run and respond to user interaction even while the database operations are being performed. Each asynchronous SQLConnection instance executes SQL statements in its own thread.

In asynchronous execution mode, you begin a specific operation by calling the appropriate method, and you can detect the completion (or failure) of the operation by registering a listener for the appropriate event. Each operation has an associated event that is dispatched when the operation completes successfully; for example, when an `openAsync()` method call completes successfully (when the database connection is opened) the `open` event is dispatched. When any operation fails, an `error` event is dispatched. The SQLError instance in the SQLErrorEvent object's `error` property contains information about the specific error, including the operation that was being attempted and the reason the operation failed.

When you're using synchronous execution, you do not need to register event listeners to determine when an operation completes or fails. To identify errors, enclose the error-throwing statements in a `try..catch` block. Because synchronous operations execute in the main execution thread, all application functionality (including refreshing the screen and allowing mouse and keyboard interaction) is paused while the database operation or operations are performed. For long-running operations this can cause a noticeable pause in the application.

More examples

Creating and modifying a database
Manipulating SQL database data
Using encryption with SQL databases
Strategies for working with SQL databases

Learn more

Quick Start: Working asynchronously with a local SQL database (Flex)
Quick Start: Working asynchronously with a local SQL database (Flash)
Quick Start: Working asynchronously with a local SQL database (HTML)
Quick Start: Working synchronously with a local SQL database (Flex)
Quick Start: Working synchronously with a local SQL database (Flash)
Quick Start: Working synchronously with a local SQL database (HTML)

Related API Elements

flash.data.SQLStatement
flash.events.SQLEvent
flash.events.SQLErrorEvent
flash.errors.SQLError

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | autoCompact : Boolean [read-only] 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). | SQLConnection
|  | cacheSize : uint 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. | SQLConnection
|  | columnNameStyle : String Indicates how column names are reported in the result of a SELECT statement. | SQLConnection
|  | connected : Boolean [read-only] Indicates whether the SQLConnection instance has an open connection to a database file. | SQLConnection
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | inTransaction : Boolean [read-only] Indicates whether this connection is currently involved in a transaction. | SQLConnection
|  | isSupported : Boolean [static] [read-only] Indicates whether SQLConnection class is supported on the current platform or not. | SQLConnection
|  | lastInsertRowID : Number [read-only] The last generated row identifier created by a SQL INSERT statement. | SQLConnection
|  | pageSize : uint [read-only] 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). | SQLConnection
|  | totalChanges : Number [read-only] Contains the total number of data changes that have been made since the connection to the database was opened. | SQLConnection

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | SQLConnection() Creates a SQLConnection instance. | SQLConnection
|  | addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0.0, useWeakReference:Boolean = false):void [override] Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. | SQLConnection
|  | analyze(resourceName:String = null, responder:Responder = null):void Gathers statistics about database indices and stores them in the database. | SQLConnection
|  | attach(name:String, reference:Object = null, responder:Responder = null, encryptionKey:ByteArray = null):void Adds another database to the SQLConnection instance, giving the new database the specified name. | SQLConnection
|  | begin(option:String = null, responder:Responder = null):void Begins a transaction within which all SQL statements executed against the connection's database or databases are grouped. | SQLConnection
|  | cancel(responder:Responder = null):void Aborts all SQL statements that are currently executing on databases connected to the SQLConnection instance. | SQLConnection
|  | close(responder:Responder = null):void Closes the current database connection. | SQLConnection
|  | commit(responder:Responder = null):void Commits an existing transaction, causing any actions performed by the transaction's statements to be permanently applied to the database. | SQLConnection
|  | compact(responder:Responder = null):void Reclaims all unused space in the database. | SQLConnection
|  | deanalyze(responder:Responder = null):void Removes all statistical information created by a call to the analyze() method. | SQLConnection
|  | detach(name:String, responder:Responder = null):void Detaches an additional database previously attached to the SQLConnection instance using the attach() method. | SQLConnection
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | getSchemaResult():SQLSchemaResult Provides access to the result of a call to the loadSchema() method. | SQLConnection
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | loadSchema(type:Class = null, name:String = null, database:String = "main", includeColumnSchema:Boolean = true, responder:Responder = null):void Loads schema information from the connected database or any attached databases. | SQLConnection
|  | open(reference:Object = null, openMode:String = "create", autoCompact:Boolean = false, pageSize:int = 1024, encryptionKey:ByteArray = null):void 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. | SQLConnection
|  | openAsync(reference:Object = null, openMode:String = "create", responder:Responder = null, autoCompact:Boolean = false, pageSize:int = 1024, encryptionKey:ByteArray = null):void 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. | SQLConnection
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | reencrypt(newEncryptionKey:ByteArray, responder:Responder = null):void Changes the encryption key of an encrypted database. | SQLConnection
|  | releaseSavepoint(name:String = null, responder:Responder = null):void This method commits the SQL operations made since the most recent savepoint or the named savepoint if a name is specified. | SQLConnection
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void [override] Removes a listener from the EventDispatcher object. | SQLConnection
|  | rollback(responder:Responder = null):void Rolls back an existing transaction created using the begin() method, meaning all changes made by any SQL statements in the transaction are discarded. | SQLConnection
|  | rollbackToSavepoint(name:String = null, responder:Responder = null):void Rolls back any SQL operations since the most recent savepoint or the named savepoint if a name is specified. | SQLConnection
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | setSavepoint(name:String = null, responder:Responder = null):void Creates a savepoint, which is like a bookmark within a database transaction. | SQLConnection
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Click for more information on events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher
|  | analyze | Dispatched when an analyze() operation completes successfully. | SQLConnection
|  | attach | Dispatched when an attach() method call's operation completes successfully. | SQLConnection
|  | begin | Dispatched when a begin() method call's operation completes successfully. | SQLConnection
|  | cancel | Dispatched when a cancel() method call's operation completes successfully. | SQLConnection
|  | close | Dispatched when a close() method call's operation completes successfully. | SQLConnection
|  | commit | Dispatched when a commit() method call's operation completes successfully. | SQLConnection
|  | compact | Dispatched when a compact() method call's operation completes successfully. | SQLConnection
|  | deactivate | [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher
|  | deanalyze | Dispatched when a deanalyze() method call's operation completes successfully. | SQLConnection
|  | delete | Dispatched when data in any table in any of the connected databases changes as a result of a SQL DELETE command. | SQLConnection
|  | detach | Dispatched when a detach() method call's operation completes successfully. | SQLConnection
|  | error | Dispatched when any of the SQLConnection object's asynchronous operations results in an error. | SQLConnection
|  | insert | Dispatched when data in any table in any of the connected databases changes as a result of a SQL INSERT command. | SQLConnection
|  | open | Dispatched when an openAsync() method call's operation completes successfully. | SQLConnection
|  | reencrypt | Dispatched when a reencrypt() method call's operation completes successfully. | SQLConnection
|  | releaseSavepoint | Dispatched when a releaseSavepoint() method call's operation completes successfully. | SQLConnection
|  | rollback | Dispatched when a rollback() method call's operation completes successfully. | SQLConnection
|  | rollbackToSavepoint | Dispatched when a rollbackToSavepoint() method call's operation completes successfully. | SQLConnection
|  | schema | Dispatched when a loadSchema() method call's operation completes successfully and the schema results are ready. | SQLConnection
|  | setSavepoint | Dispatched when a setSavepoint() method call's operation completes successfully. | SQLConnection
|  | update | Dispatched when data in any table in any of the connected databases changes as a result of a SQL UPDATE command. | SQLConnection

Property Detail

### autoCompact

property

`autoCompact:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

Implementation
`public function get autoCompact():Boolean`

Related API Elements

open()
openAsync()

### cacheSize

property

`cacheSize:uint`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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.

Implementation
`public function get cacheSize():uint`
`public function set cacheSize(value:uint):void`
Throws

| `IllegalOperationError` — When an attempt is made to set this property while the SQLConnection instance isn't connected to a database (the `connected` property is `false`); or if a transaction is currently open (the `inTransaction` property is `true`).

Related API Elements

open()
openAsync()

### columnNameStyle

property

`columnNameStyle:String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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.

Implementation
`public function get columnNameStyle():String`
`public function set columnNameStyle(value:String):void`
Throws

| `IllegalOperationError` — When an attempt is made to set this property while the SQLConnection instance isn't connected to a database (the `connected` property is `false`).

Related API Elements

flash.data.SQLColumnNameStyle

### connected

property

`connected:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

Implementation
`public function get connected():Boolean`

Related API Elements

open()
openAsync()
close()

### inTransaction

property

`inTransaction:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Indicates whether this connection is currently involved in a transaction.

Implementation
`public function get inTransaction():Boolean`

Related API Elements

begin()
commit()
rollback()

### isSupported

property

`isSupported:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 3.4

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

Implementation
`public static function get isSupported():Boolean`

### lastInsertRowID

property

`lastInsertRowID:Number` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

Implementation
`public function get lastInsertRowID():Number`

Related API Elements

flash.data.SQLResult.lastInsertRowID
flash.events.SQLUpdateEvent.rowID

### pageSize

property

`pageSize:uint` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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.

Implementation
`public function get pageSize():uint`

Related API Elements

open()
openAsync()

### totalChanges

property

`totalChanges:Number` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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.

Implementation
`public function get totalChanges():Number`

Related API Elements

flash.data.SQLResult.rowsAffected
Constructor Detail

### SQLConnection

()
Constructor

`public function SQLConnection()`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Creates a SQLConnection instance.

Throws

| `SecurityError` — if constructor is called from any sandbox outside of the main application sandbox.

Method Detail

### addEventListener

()
method

`override public function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0.0, useWeakReference:Boolean = false):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

| `type:String` — The type of event.
| `listener:Function` — The listener function that processes the event. This function must accept an Event object as its only parameter and must return nothing, as this example shows: Copy
    function(evt:Event):void
The function can have any name.
| `useCapture:Boolean` (default = `false`)`` — Determines whether the listener works in the capture phase or the target and bubbling phases. If `useCapture` is set to `true`, the listener processes the event only during the capture phase and not in the target or bubbling phase. If `useCapture` is `false`, the listener processes the event only during the target or bubbling phase. To listen for the event in all three phases, call `addEventListener` twice, once with `useCapture` set to `true`, then again with `useCapture` set to `false`.
| `priority:int` (default = `0.0`)`` — The priority level of the event listener. The priority is designated by a signed 32-bit integer. The higher the number, the higher the priority. All listeners with priority n are processed before listeners of priority n-1. If two or more listeners share the same priority, they are processed in the order in which they were added. The default priority is 0.
| `useWeakReference:Boolean` (default = `false`)`` — Determines whether the reference to the listener is strong or weak. A strong reference (the default) prevents your listener from being garbage-collected. A weak reference does not. Class-level member functions are not subject to garbage collection, so you can set `useWeakReference` to `true` for class-level member functions without subjecting them to garbage collection. If you set `useWeakReference` to `true` for a listener that is a nested inner function, the function will be garbage-collected and no longer persistent. If you create references to the inner function (save it in another variable) then it is not garbage-collected and stays persistent.

### analyze

()
method

`public function analyze(resourceName:String = null, responder:Responder = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

| `resourceName:String` (default = `null`)`` — The name of the database or table whose indices are to be analyzed. If the specified resource is a table whose name is unique among all the attached databases, only the table name needs to be specified. However, a table name can be specified in the form `[database-name].[table-name]` to prevent ambiguity when the table name is not unique. If the `resourceName` parameter is `null` (the default), all the indices in all attached databases are analyzed.
| `responder:Responder` (default = `null`)`` — An object that designates methods to be called when the operation succeeds or fails. In asynchronous execution mode, if the `responder` argument is `null` an `analyze` or `error` event is dispatched when execution completes.

Events

| `analyze:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation fails in asynchronous execution mode.

Throws

| `IllegalOperationError` — When this method is called while the SQLConnection instance isn't connected to a database (the `connected` property is `false`).
| `SQLError` — if the operation fails in synchronous execution mode.

Related API Elements

deanalyze()

### attach

()
method

`public function attach(name:String, reference:Object = null, responder:Responder = null, encryptionKey:ByteArray = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

| `name:String` — The name that is used to identify the newly attached database. This name can be used in SQL statements to explicitly indicate that a table belongs to the specified database, when using the format `[database-name].[table-name]`. The names "main" and "temp" are reserved and cannot be used.
| `reference:Object` (default = `null`)`` — A reference to the database file to attach (a flash.filesystem.File instance). If the reference refers to a file that doesn't exist, either a new database file is created or an error is thrown according to the value that was specified for the `openMode` parameter in the `open()` or `openAsync()` call that connected the main database.

If the parameter's value is `null`, an in-memory database is created and attached.

| `responder:Responder` (default = `null`)`` — An object that designates methods to be called when the operation succeeds or fails. In asynchronous execution mode, if the `responder` argument is `null` an `attach` or `error` event is dispatched when execution completes.
| `encryptionKey:ByteArray` (default = `null`)`` — The encryption key for the database file. If the `attach()` call creates a database, the database is encrypted and the specified key is used as the encryption key for the database. If the call attaches an existing encrypted database, the value must match the database's encryption key or an error occurs. If the database being attached is not encrypted, or to create an unencrypted database, the value must be `null` (the default).

A valid encryption key is 16 bytes long. An in-memory database cannot be encrypted, so this parameter must be `null` when the `reference` parameter's value is `null`.

When attaching an encrypted database, if the encryption key provided doesn't match the database's encryption key, an exception occurs. In synchronous execution mode, a SQLError exception is thrown. In asynchronous execution mode, a SQLErrorEvent is dispatched, and the event object's `error` property contains a SQLError instance. In either case, the SQLError object's `errorID` property is 3138 ("File opened is not a database file").

The `encryptionKey` parameter is available starting with AIR 1.5.

Events

| `attach:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation fails in asynchronous execution mode.

Throws

| `ArgumentError` — When the `name` parameter is an empty string (`""`) or `null`
| `ArgumentError` — When the value specified for the `reference` parameter is not a flash.filesystem.File instance
| `ArgumentError` — When the `encryptionKey` argument is not `null` and its `length` is not 16 bytes
| `ArgumentError` — When the `reference` parameter is `null` and the `encryptionKey` argument is not `null`
| `IllegalOperationError` — When the SQLConnection instance isn't connected to a database (the `connected` property is `false`); or if a transaction is currently open (the `inTransaction` property is `true`).
| `SQLError` — if the operation fails in synchronous execution mode.

More examples

Working with multiple databases

Related API Elements

open()
openAsync()
detach()

### begin

()
method

`public function begin(option:String = null, responder:Responder = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

| `option:String` (default = `null`)`` — Indicates the locking strategy that is used by the transaction. The value can be one of the constants defined in the SQLTransactionLockType class:

- `SQLTransactionLockType.DEFERRED` indicates that a lock is not acquired until the first read or write operation.
- `SQLTransactionLockType.EXCLUSIVE` indicates that a lock is acquired as soon as possible, and no other SQLConnection instance can read from or write to the database.
- `SQLTransactionLockType.IMMEDIATE` indicates that a lock is acquired as soon as possible, in which other SQLConnection instances can read from but can't write to the database.

The default value (`null`) is equivalent to `SQLTransactionLockType.DEFERRED`.

| `responder:Responder` (default = `null`)`` — An object that designates methods to be called when the operation succeeds or fails. In asynchronous execution mode, if the `responder` argument is `null` a `begin` or `error` event is dispatched when execution completes.

Events

| `begin:`SQLEvent`` — Dispatched when the operation completes.
| `error:`SQLErrorEvent`` — Dispatched when the operation fails in asynchronous execution mode.

Throws

| `IllegalOperationError` — When this method is called while the SQLConnection instance isn't connected to a database (the `connected` property is `false`).
| `ArgumentError` — If the option specified is not one of the SQLTransactionLockType constants.
| `SQLError` — if the operation fails in synchronous execution mode.

Related API Elements

commit()
rollback()
setSavepoint()
releaseSavepoint()
rollbackToSavepoint()
flash.data.SQLTransactionLockType
Example ( How to use this example )
The following example demonstrates executing multiple SQL `INSERT` statements within a transaction. First a row is added to the "employees" table. Next the primary key of the newly inserted row is retrieved, and used to add a row to the related "phoneNumbers" table.
Copy

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

The following example demonstrates executing multiple SQL `DELETE` statements within a transaction. The transaction is used to delete an employee record. First the related rows in the "phoneNumbers" table are deleted. Next the employee record row is deleted from the "employees" table.
Copy

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

### cancel

()
method

`public function cancel(responder:Responder = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

| `responder:Responder` (default = `null`)`` — An object that designates methods to be called when the operation succeeds or fails. In asynchronous execution mode, if the `responder` argument is `null` a `cancel` or `error` event is dispatched when execution completes.

Events

| `cancel:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation fails in asynchronous execution mode.

Throws

| `IllegalOperationError` — When this method is called while the SQLConnection instance isn't connected to a database (the `connected` property is `false`).
| `SQLError` — If the operation fails in synchronous execution mode.

Related API Elements

flash.data.SQLStatement

### close

()
method

`public function close(responder:Responder = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

| `responder:Responder` (default = `null`)`` — An object that designates methods to be called when the operation succeeds or fails. In asynchronous execution mode, if the `responder` argument is `null` a `close` or `error` event is dispatched when execution completes.

Events

| `close:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation fails in asynchronous execution mode.

Throws

| `SQLError` — If the operation fails in synchronous execution mode.

### commit

()
method

`public function commit(responder:Responder = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

| `responder:Responder` (default = `null`)`` — An object that designates methods to be called when the operation succeeds or fails. In asynchronous execution mode, if the `responder` argument is `null` a `commit` or `error` event is dispatched when execution completes.

Events

| `commit:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation completes with a failure.

Throws

| `IllegalOperationError` — When the method is called while the SQLConnection instance isn't connected to a database (the `connected` property is `false`); or if no transaction is currently open (the `inTransaction` property is `false`).

Related API Elements

begin()
rollback()
setSavepoint()
releaseSavepoint()
rollbackToSavepoint()

### compact

()
method

`public function compact(responder:Responder = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

| `responder:Responder` (default = `null`)`` — An object that designates methods to be called when the operation succeeds or fails. In asynchronous execution mode, if the `responder` argument is `null` a `compact` or `error` event is dispatched when execution completes.

Events

| `compact:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation fails in asynchronous execution mode.

Throws

| `IllegalOperationError` — If the method is called while the SQLConnection instance isn't connected to a database (the `connected` property is `false`); or if a transaction is currently in progress (the `inTransaction` property is `true`).
| `SQLError` — If the operation fails in synchronous execution mode.

### deanalyze

()
method

`public function deanalyze(responder:Responder = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

| `responder:Responder` (default = `null`)`` — An object that designates methods to be called when the operation succeeds or fails. In asynchronous execution mode, if the `responder` argument is `null` a `deanalyze` or `error` event is dispatched when execution completes.

Events

| `deanalyze:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation fails in asynchronous execution mode.

Throws

| `IllegalOperationError` — When this method is called while the SQLConnection instance isn't connected to a database (the `connected` property is `false`).
| `SQLError` — If the operation fails in synchronous execution mode.

Related API Elements

analyze()

### detach

()
method

`public function detach(name:String, responder:Responder = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

| `name:String` — The given name of the database to detach.
| `responder:Responder` (default = `null`)`` — An object that designates methods to be called when the operation succeeds or fails. In asynchronous execution mode, if the `responder` argument is `null` a `detach` or `error` event is dispatched when execution completes.

Events

| `detach:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation fails in asynchronous execution mode.

Throws

| `ArgumentError` — If the `name` argument is `null` or contains an empty string (`""`).
| `IllegalOperationError` — If this method is called while the SQLConnection instance isn't connected to a database (the `connected` property is `false`); or if the SQLConnection instance has an open transaction (the `inTransaction` property is `true`).
| `SQLError` — If the operation fails in synchronous execution mode.

More examples

Working with multiple databases

Related API Elements

attach()

### getSchemaResult

()
method

`public function getSchemaResult():SQLSchemaResult`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

Returns

| `SQLSchemaResult`

Related API Elements

loadSchema()
schema

### loadSchema

()
method

`public function loadSchema(type:Class = null, name:String = null, database:String = "main", includeColumnSchema:Boolean = true, responder:Responder = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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:

`type` argument | `name` argument | Retrieves schema data for:
--- | --- | ---
`null` | `null` | all objects in the database (all tables, views, triggers, and indices)
`SQLIndexSchema` | `null` | all indices in the database
`SQLIndexSchema` | valid table name | all indices defined on the specified table
`SQLIndexSchema` | valid index name | the specified index
`SQLTableSchema` | `null` | all tables in the database
`SQLTableSchema` | valid table name | the specified table
`SQLTriggerSchema` | `null` | all triggers in the database
`SQLTriggerSchema` | valid table name | all triggers associated with the specified table
`SQLTriggerSchema` | valid view name | all triggers associated with the specified view
`SQLTriggerSchema` | valid trigger name | the specified trigger
`SQLViewSchema` | `null` | all views in the database
`SQLViewSchema` | valid view name | the specified view

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

| `type:Class` (default = `null`)`` — Indicates the type of schema to load. A `null` value (the default) indicates that all the schema information should be loaded. Specifying a non-`null` value for this parameter narrows the scope of the resulting schema, removing potentially unneeded information from the results and making the operation more efficient. The value must be the class name of one of the following classes:

- SQLIndexSchema
- SQLTableSchema
- SQLTriggerSchema
- SQLViewSchema

| `name:String` (default = `null`)`` — Indicates which resource's schema is loaded. How this value is used depends on the `type` argument specified. Typically, this is the name of a database object such as a table name, an index or view name, and so forth. If a value is specified, only schema information for the database object with the specified name is included in the result.

If the specified value is not valid an `error` event is dispatched (or an error is thrown in synchronous execution mode). The `type` parameter value must correspond to the type of the object named in order for the value to be valid, as described in the method description.

If the `name` argument is `null` then all schemata of the specified type are included. If the value specified is not valid an `error` event is dispatched.

| `database:String` (default = "`main`")`` — The name of the database whose schema is loaded. If the value specified is not valid an `error` event is dispatched.
| `includeColumnSchema:Boolean` (default = `true`)`` — Indicates whether the result includes schema information for the columns of tables and views.
| `responder:Responder` (default = `null`)`` — An object that designates methods to be called when the operation succeeds or fails. In asynchronous execution mode, if the `responder` argument is `null` a `schema` or `error` event is dispatched when execution completes.

Events

| `schema:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation completes with a failure.

Throws

| `IllegalOperationError` — When the method is called while the SQLConnection instance isn't connected to a database (the `connected` property is `false`).
| `ArgumentError` — When the specified `type` argument value isn't one of the allowed types.
| `SQLError` — When using synchronous execution mode, if an invalid value is supplied for the name or database parameters.

Related API Elements

getSchemaResult()
schema
flash.data.SQLIndexSchema
flash.data.SQLTableSchema
flash.data.SQLTriggerSchema
flash.data.SQLViewSchema

### open

()
method

`public function open(reference:Object = null, openMode:String = "create", autoCompact:Boolean = false, pageSize:int = 1024, encryptionKey:ByteArray = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

| `reference:Object` (default = `null`)`` — The location of the database file that is opened. This value must be a flash.filesystem.File instance. If the parameter's value is `null`, an in-memory database is created and opened.
| `openMode:String` (default = "`create`")`` — Indicates how the database is opened. The value can be any of the constants defined in the SQLMode class. The default value is `SQLMode.CREATE`, indicating that if a database file is not found at the specified location, one is created. If `openMode` is `SQLMode.READ` and the specified file does not exist then an error occurs. This parameter is ignored when the `reference` parameter is `null`.
| `autoCompact:Boolean` (default = `false`)`` — Indicates whether unused space in the database is reclaimed automatically. This parameter is only valid when creating a new database file or opening a database file in which no tables have been created. By default, the space taken up by removed data is left in the database file and reused when needed. Setting this parameter to `true` causes the database to automatically reclaim unused space. This can negatively affect performance because it requires additional processing each time data is written to the database and can also cause the database data to become fragmented over time. At any time you can force the database to reclaim unused space in a database file and defragment the database file using the `compact()` method.

This parameter is ignored when the `openMode` parameter is `SQLMode.READ`.

| `pageSize:int` (default = `1024`)`` — Indicates the page size (in bytes) for the database. This parameter is only valid when creating a new database file or opening a database file in which no tables have been created. The value must be a power of two greater than or equal to 512 and less than or equal to 32768. The default value is 1024 bytes. This value can only be set before any tables are created. Once the tables are created attempting to change this value results in an error.
| `encryptionKey:ByteArray` (default = `null`)`` — The encryption key for the database file. If the `open()` call creates a database, the database is encrypted and the specified key is used as the encryption key for the database. If the call opens an encrypted database, the value must match the database's encryption key or an error occurs. If the database being opened is not encrypted, or to create an unencrypted database, the value must be `null` (the default) or an error occurs.

A valid encryption key is 16 bytes long. An in-memory database cannot be encrypted, so this parameter must be `null` when the `reference` parameter's value is `null`.

When opening an encrypted database, if the encryption key provided doesn't match the database's encryption key, a SQLError exception is thrown. In that case the SQLError object's `errorID` property is 3138 ("File opened is not a database file").

The `encryptionKey` parameter is available starting with AIR 1.5.

Events

| `open:`SQLEvent`` — Dispatched when the operation completes successfully.

Throws

| `IllegalOperationError` — When the SQLConnection instance already has an open connection to a database (the `connected` property is `true`).
| `SQLError` — If the operation fails. The connection is never left open after a failed operation.
| `ArgumentError` — When the value specified for the `reference` parameter is not a flash.filesystem.File instance
| `ArgumentError` — When the `encryptionKey` argument is not `null` and its `length` is not 16 bytes
| `ArgumentError` — When the `reference` parameter is `null` and the `encryptionKey` argument is not `null`
| `ArgumentError` — If an invalid `pageSize` parameter is specified. This includes passing a page size when the mode is `SQLMode.READ`.

More examples

Creating a database
Connecting to a database
Using synchronous database operations
Creating an encrypted database
Connecting to an encrypted database

Related API Elements

openAsync()
close()
flash.data.SQLMode

### openAsync

()
method

`public function openAsync(reference:Object = null, openMode:String = "create", responder:Responder = null, autoCompact:Boolean = false, pageSize:int = 1024, encryptionKey:ByteArray = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

| `reference:Object` (default = `null`)`` — The location of the database file that is opened. This value must be a flash.filesystem.File instance. If the parameter's value is `null`, an in-memory database is created and opened.
| `openMode:String` (default = "`create`")`` — Indicates how the database is opened. The value can be any of the constants defined in the SQLMode class. The default value is `SQLMode.CREATE`, indicating that if a database file is not found at the specified location, one is created. If `openMode` is `SQLMode.READ` and the specified file does not exist then an `error` event is dispatched. This parameter is ignored when the `reference` parameter is `null`.
| `responder:Responder` (default = `null`)`` — An object that designates methods to be called when the operation succeeds or fails. If the `responder` argument is `null` an `open` or `error` event is dispatched when execution completes.
| `autoCompact:Boolean` (default = `false`)`` — Indicates whether unused space in the database is reclaimed automatically. This parameter is only valid when creating a new database file or opening a database file in which no tables have been created. By default, the space taken up by removed data is left in the database file and reused when needed. Setting this parameter to `true` causes the database to automatically reclaim unused space. This can negatively affect performance because it requires additional processing each time data is written to the database and can also cause the database data to become fragmented over time. To force the database to reclaim unused space in a database file at any time and to defragment the database file, use the `compact()` method.

This parameter is ignored when the `openMode` parameter is `SQLMode.READ`.

| `pageSize:int` (default = `1024`)`` — Indicates the page size (in bytes) for the database. This parameter is only valid when creating a new database file or opening a database file in which no tables have been created. The value must be a power of two greater than or equal to 512 and less than or equal to 32768. The default value is 1024 bytes. This value can only be set before any tables are created. Once the tables are created attempting to change this value results in an error.
| `encryptionKey:ByteArray` (default = `null`)`` — The encryption key for the database file. If the `openAsync()` call creates a database, the database is encrypted and the specified key is used as the encryption key for the database. If the call opens an encrypted database, the value must match the database's encryption key or an error occurs. If the database being opened is not encrypted, the value must be `null` (the default) or an error occurs.

A valid encryption key is 16 bytes long. An in-memory database cannot be encrypted, so this parameter must be `null` when the `reference` parameter's value is `null`.

When opening an encrypted database, if the encryption key provided doesn't match the database's encryption key, a SQLErrorEvent is dispatched. The event object's `error` property contains a SQLError instance. That SQLError object's `errorID` property is 3138 ("File opened is not a database file").

The `encryptionKey` parameter is available starting with AIR 1.5.

Events

| `open:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation fails. The connection is never left open after a failed operation.

Throws

| `IllegalOperationError` — When the SQLConnection instance already has an open connection to a database (the `connected` property is `true`).
| `ArgumentError` — When the value specified for the `reference` parameter is not a flash.filesystem.File instance
| `ArgumentError` — When the `encryptionKey` argument is not `null` and its `length` is not 16 bytes
| `ArgumentError` — When the `reference` parameter is `null` and the `encryptionKey` argument is not `null`
| `ArgumentError` — If an invalid `pageSize` parameter is specified. This includes passing a page size when the mode is `SQLMode.READ`.

More examples

Creating a database
Connecting to a database
Understanding the asynchronous execution model
Creating an encrypted database
Connecting to an encrypted database

Related API Elements

open()
close()
flash.data.SQLMode

### reencrypt

()
method

`public function reencrypt(newEncryptionKey:ByteArray, responder:Responder = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.5

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

| `newEncryptionKey:ByteArray` — A ByteArray containing the new encryption key for the database. A valid encryption key is 16 bytes long.
| `responder:Responder` (default = `null`)`` — An object that designates methods to be called when the operation succeeds or fails. If the `responder` argument is `null` a `reencrypt` or `error` event is dispatched when execution completes.

Events

| `reencrypt:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation fails.

Throws

| `ArgumentError` — When the `newEncryptionKey` value is `null` or its `length` is not 16 bytes.
| `IllegalOperationError` — When the connection is not open, or if there is an open transaction.
| `SQLError` — If the operation fails in synchronous execution mode.

More examples

Changing the encryption key of a database

Related API Elements

open()
openAsync()
attach()

### releaseSavepoint

()
method

`public function releaseSavepoint(name:String = null, responder:Responder = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

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

| `name:String` (default = `null`)`` — String The name of the savepoint from which all SQL operations should be committed. If no value is provided or if this parameter is `null` (the default) then the most recent unnamed savepoint (created by a call to `setSavepoint()` with no `name` value) is used. The `name` value cannot be an empty string (`""`).
| `responder:Responder` (default = `null`)`` — Responder An object that designates methods to be called when the operation succeeds or fails. In asynchronous execution mode, if the responder argument is `null` a `releaseSavepoint` or `error` event is dispatched when execution completes.

Events

| `releaseSavepoint:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation fails in asynchronous execution mode.

Throws

| `ArgumentError` — when the `name` parameter value is an empty string (`""`).
| `IllegalOperationError` — When the method is called while the SQLConnection instance isn't connected to a database (the `connected` property is `false`); or if no transaction is currently open (the `inTransaction` property is `false`).
| `SQLError` — If the operation fails in synchronous execution mode.

Related API Elements

setSavepoint()
rollbackToSavepoint()

### removeEventListener

()
method

`override public function removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

| `type:String` — The type of event.
| `listener:Function` — The listener object to remove.
| `useCapture:Boolean` (default = `false`)`` — Specifies whether the listener was registered for the capture phase or the target and bubbling phases. If the listener was registered for both the capture phase and the target and bubbling phases, two calls to `removeEventListener()` are required to remove both, one call with `useCapture()` set to `true`, and another call with `useCapture()` set to `false`.

### rollback

()
method

`public function rollback(responder:Responder = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

| `responder:Responder` (default = `null`)`` — An object that designates methods to be called when the operation succeeds or fails. In asynchronous execution mode, if the `responder` argument is `null` a `rollback` or `error` event is dispatched when execution completes.

Events

| `rollback:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation fails in asynchronous execution mode.

Throws

| `IllegalOperationError` — When the method is called while the SQLConnection instance isn't connected to a database (the `connected` property is `false`); or if no transaction is currently open (the `inTransaction` property is `false`).
| `SQLError` — If the operation fails in synchronous execution mode.

Related API Elements

begin()
commit()
setSavepoint()
releaseSavepoint()
rollbackToSavepoint()

### rollbackToSavepoint

()
method

`public function rollbackToSavepoint(name:String = null, responder:Responder = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

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

| `name:String` (default = `null`)`` — String The name of the savepoint to which the database state should be rolled back. If no value is provided or if this parameter is `null` (the default) then most recent unnamed savepoint (created by a call to `setSavepoint()` with no `name` value) is used. The `name` value cannot be an empty string (`""`).
| `responder:Responder` (default = `null`)`` — Responder An object that designates methods to be called when the operation succeeds or fails. In asynchronous execution mode, if the responder argument is `null` a `rollbackToSavepoint` or `error` event is dispatched when execution completes.

Events

| `rollbackToSavepoint:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation fails in asynchronous execution mode.

Throws

| `ArgumentError` — when the `name` parameter value is an empty string (`""`).
| `IllegalOperationError` — When the method is called while the SQLConnection instance isn't connected to a database (the `connected` property is `false`); or if no transaction is currently open (the `inTransaction` property is `false`).
| `SQLError` — If the operation fails in synchronous execution mode.

Related API Elements

setSavepoint()
releaseSavepoint()

### setSavepoint

()
method

`public function setSavepoint(name:String = null, responder:Responder = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

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

| `name:String` (default = `null`)`` — String The name for the savepoint. If no value is provided or if this parameter is `null` (the default) then the next call to `releaseSavepoint()` or `rollbackToSavepoint()` with no `name` parameter specified commits or rolls back the SQL operations performed since the unnamed savepoint.

If the name provided is a duplicate of a previous named savepoint, the next call to either `SQLConnection.releaseSavepoint()` or `SQLConnection.rollbackToSavepoint()` commits or rolls back changes made since the most recent savepoint with that name.

The `name` value cannot be an empty string (`""`).

| `responder:Responder` (default = `null`)`` — Responder An object that designates methods to be called when the operation succeeds or fails. In asynchronous execution mode, if the responder argument is `null` a `setSavepoint` or `error` event is dispatched when execution completes.

Events

| `setSavepoint:`SQLEvent`` — Dispatched when the operation completes successfully.
| `error:`SQLErrorEvent`` — Dispatched when the operation fails in asynchronous execution mode.

Throws

| `ArgumentError` — when the `name` parameter value is an empty string (`""`).
| `IllegalOperationError` — When the method is called while the SQLConnection instance isn't connected to a database (the `connected` property is `false`).
| `SQLError` — If the operation fails in synchronous execution mode.

Related API Elements

begin()
releaseSavepoint()
rollbackToSavepoint()
commit()
rollback()
Event Detail

### analyze

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.ANALYZE`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Dispatched when an `analyze()` operation completes successfully.

The `SQLEvent.ANALYZE` constant defines the value of the `type` property of an `analyze` event object. This type of event is dispatched when a `SQLConnection.analyze()` method call completes successfully. The `analyze` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

analyze()

### attach

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.ATTACH`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

The `SQLEvent.ATTACH` constant defines the value of the `type` property of an `attach` event object. This type of event is dispatched when a `SQLConnection.attach()` method call completes successfully. The `attach` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

attach()

### begin

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.BEGIN`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

The `SQLEvent.BEGIN` constant defines the value of the `type` property of a `begin` event object. This type of event is dispatched when a `SQLConnection.begin()` method call completes successfully. The `begin` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

begin()

### cancel

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.CANCEL`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

The `SQLEvent.CANCEL` constant defines the value of the `type` property of a `cancel` event object. This type of event is dispatched when a `SQLConnection.cancel()` method call completes successfully. The `cancel` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection or SQLStatement object that performed the operation.

Related API Elements

cancel()

### close

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.CLOSE`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

The `SQLEvent.CLOSE` constant defines the value of the `type` property of a `close` event object. This type of event is dispatched when a `SQLConnection.close()` method call completes successfully. The `close` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

close()

### commit

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.COMMIT`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

The `SQLEvent.COMMIT` constant defines the value of the `type` property of a `commit` event object. This type of event is dispatched when a `SQLConnection.commit()` method call completes successfully. The `commit` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

commit()

### compact

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.COMPACT`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

The `SQLEvent.COMPACT` constant defines the value of the `type` property of a `compact` event object. This type of event is dispatched when a `SQLConnection.compact()` method call completes successfully. The `compact` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

compact()

### deanalyze

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.DEANALYZE`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

The `SQLEvent.DEANALYZE` constant defines the value of the `type` property of a `deanalyze` event object. This type of event is dispatched when a `SQLConnection.deanalyze()` method call completes successfully. The `deanalyze` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

deanalyze()

### delete

Event

Event Object Type: `flash.events.SQLUpdateEvent`
property SQLUpdateEvent.type = `flash.events.SQLUpdateEvent.DELETE`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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.

The `SQLUpdateEvent.DELETE` constant defines the value of the `type` property of a SQLConnection `delete` event. The `delete` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`rowID` | The unique row identifier of the row that was inserted, deleted, or updated.
`target` | The SQLConnection object on which the operation was performed.
`table` | The name of the table on which the change occurred.

Related API Elements

flash.data.SQLStatement

### detach

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.DETACH`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

The `SQLEvent.DETACH` constant defines the value of the `type` property of a `detach` event object. This type of event is dispatched when a `SQLConnection.detach()` method call completes successfully.

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

detach()

### error

Event

Event Object Type: `flash.events.SQLErrorEvent`
property SQLErrorEvent.type = `flash.events.SQLErrorEvent.ERROR`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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.

The `SQLErrorEvent.ERROR` constant defines the value of the `type` property of an error event dispatched when a call to a method of a SQLConnection or SQLStatement instance completes with an error. The `error` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`error` | A SQLError object containing information about the type of error that occurred and the operation that caused the error.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection or SQLStatement object reporting the error.

### insert

Event

Event Object Type: `flash.events.SQLUpdateEvent`
property SQLUpdateEvent.type = `flash.events.SQLUpdateEvent.INSERT`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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.

The `SQLUpdateEvent.INSERT` constant defines the value of the `type` property of a SQLConnection `insert` event. The `insert` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`rowID` | The unique row identifier of the row that was inserted, deleted, or updated.
`target` | The SQLConnection object on which the operation was performed.
`table` | The name of the table on which the change occurred.

Related API Elements

flash.data.SQLStatement

### open

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.OPEN`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

The `SQLEvent.OPEN` constant defines the value of the `type` property of a `open` event object. This type of event is dispatched when a `SQLConnection.open()` or `SQLConnection.openAsync()` method call completes successfully. The `open` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

openAsync()

### reencrypt

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.REENCRYPT`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.5

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

The `SQLEvent.REENCRYPT` constant defines the value of the `type` property of a `reencrypt` event object. This type of event is dispatched when a `SQLConnection.reencrypt()` method call completes successfully. The `reencrypt` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

reencrypt()

### releaseSavepoint

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.RELEASE_SAVEPOINT`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

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

The `SQLEvent.RELEASE_SAVEPOINT` constant defines the value of the `type` property of a `releaseSavepoint` event object. This type of event is dispatched when a `SQLConnection.releaseSavepoint()` method call completes successfully. The `releaseSavepoint` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

releaseSavepoint()

### rollback

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.ROLLBACK`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

The `SQLEvent.ROLLBACK` constant defines the value of the `type` property of a `rollback` event object. This type of event is dispatched when a `SQLConnection.rollback()` method call completes successfully. The `rollback` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

rollback()

### rollbackToSavepoint

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.ROLLBACK_TO_SAVEPOINT`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

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

The `SQLEvent.ROLLBACK_TO_SAVEPOINT` constant defines the value of the `type` property of a `rollbackToSavepoint` event object. This type of event is dispatched when a `SQLConnection.rollbackToSavepoint()` method call completes successfully. The `rollbackToSavepoint` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

rollbackToSavepoint()

### schema

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.SCHEMA`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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

The `SQLEvent.SCHEMA` constant defines the value of the `type` property of a `schema` event object. Dispatched when the `SQLConnection.loadSchema()` method completes successfully. Once the `SQLEvent.SCHEMA` event is dispatched the `SQLConnection.getSchemaResult()` method can be used to get the schema information. The `schema` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

loadSchema()

### setSavepoint

Event

Event Object Type: `flash.events.SQLEvent`
property SQLEvent.type = `flash.events.SQLEvent.SET_SAVEPOINT`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

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

The `SQLEvent.SET_SAVEPOINT` constant defines the value of the `type` property of a `setSavepoint` event object. This type of event is dispatched when a `SQLConnection.setSavepoint()` method call completes successfully. The `setSavepoint` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`target` | The SQLConnection object that performed the operation.

Related API Elements

setSavepoint()

### update

Event

Event Object Type: `flash.events.SQLUpdateEvent`
property SQLUpdateEvent.type = `flash.events.SQLUpdateEvent.UPDATE`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

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 `SQLUpdateEvent.UPDATE` constant defines the value of the `type` property of a SQLConnection `update` event.

The `update` event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the event object with an event listener.
`rowID` | The unique row identifier of the row that was inserted, deleted, or updated.
`target` | The SQLConnection object on which the operation was performed.
`table` | The name of the table on which the change occurred.

Related API Elements

flash.data.SQLStatement

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00