# Titanium.Database.DB

The Database instance returned by open or install.

Availability

0.8

9.2.0

Extends

Titanium.Proxy

# Properties

# apiName READONLY

Availability

3.2.0

9.2.0

apiName :String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button returns Ti.UI.Button.

# bubbleParent

Availability

3.0.0

9.2.0

bubbleParent :Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true

# file READONLY

Availability

5.4.0

2.0.0

9.2.0

file :Titanium.Filesystem.File

A File object representing the file where this database is stored. Must only be used for setting file properties.

# lastInsertRowId READONLY

Availability

0.8

9.2.0

lastInsertRowId :Number

The identifier of the last populated row.

# lifecycleContainer

Availability

3.6.0

lifecycleContainer :Titanium.UI.Window | Titanium.UI.TabGroup

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.

# name READONLY

Availability

0.8

9.2.0

name :String

The name of the database.

# rowsAffected READONLY

Availability

0.8

9.2.0

rowsAffected :Number

The number of rows affected by the last query.

# Methods

# addEventListener

Availability

0.8

9.2.0

addEventListener(name, callback) → void

Adds the specified callback as an event listener for the named event.

Parameters

Name	Type	Description
`name`	String	Name of the event.
`callback`	Callback<Titanium.Event>	Callback function to invoke when the event is fired.

Returns

Type: void

# applyProperties

Availability

3.0.0

9.2.0

applyProperties(props) → void

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

Parameters

Name	Type	Description
`props`	Dictionary	A dictionary of properties to apply.

Returns

Type: void

# close

Availability

0.8

9.2.0

close() → void

Closes the database and releases resources from memory. Once closed, this instance is no longer valid and should not be used. On iOS, also closes all Titanium.Database.ResultSet instances that exist.

Returns

Type: void

# execute

Availability

0.8

9.2.0

execute(sql[, ...vararg]) → Titanium.Database.ResultSet

Executes an SQL statement against the database and returns a ResultSet.

Parameters

Name	Type	Description
`sql`	String	SQL to execute. May include placeholders for parameter substitution.
`vararg`	String \| Array<String> \| Object \| Array<Object>	Either a variable ordered list of zero or more values, or an array of values, to be substituted with the respective `?` placeholder of the query.

Returns

Type: Titanium.Database.ResultSet

# executeAll

Availability

8.1.0

9.2.0

executeAll(queries) → Array<Titanium.Database.ResultSet>

Synchronously executes an array of SQL statements against the database and returns an array of ResultSet. On failure, this will throw an BatchQueryError that reports the failed index and partial results

Parameters

Name	Type	Description
`queries`	Array<String>	Array of SQL queries to execute.

Returns

Type: Array<Titanium.Database.ResultSet>

# executeAllAsync

Availability

8.1.0

9.2.0

executeAllAsync(queries[, callback]) → Promise<Array<Titanium.Database.ResultSet>>

Asynchronously executes an array of SQL statements against the database and fires a callback with a possible Error, and an array of ResultSet. On failure, this will call the callback with an PossibleBatchQueryError that reports the failed index, and a second argument with the partial results.

Parameters

Name	Type	Description
`queries`	Array<String>	Array of SQL queries to execute.
`callback`	Callback<PossibleBatchQueryError, Array<Titanium.Database.ResultSet>>	Callback when query execution has completed.

Returns

On SDK 10+, this method will return a Promise whose resolved value is equivalent to that passed to the optional callback argument. If the Promise is rejected, the Error will have custom properties indicating the index of the failed query, and the partial results up to that failure. See PossibleBatchQueryError.

Type: Promise<Array<Titanium.Database.ResultSet>>

# executeAsync

Availability

8.1.0

9.2.0

executeAsync(query[, vararg[, callback]]) → Promise<Titanium.Database.ResultSet>

Asynchronously executes an SQL statement against the database and fires a callback with a possible Error argument, and a second argument holding a possible ResultSet.

Parameters

Name	Type	Description
`query`	String	SQL query to execute. May include placeholders for parameter substitution.
`vararg`	String \| Array<String> \| Object \| Array<Object>	Either a variable ordered list of zero or more values, or an array of values, to be substituted with the respective `?` placeholder of the query.
`callback`	Callback<Object, Titanium.Database.ResultSet>	Callback when query execution has completed.

Returns

On SDK 10+, this method will return a Promise whose resolved value is equivalent to that passed to the optional callback argument.

Type: Promise<Titanium.Database.ResultSet>

# fireEvent

Availability

0.8

9.2.0

fireEvent(name[, event]) → void

Fires a synthesized event to any registered listeners.

Parameters

Name	Type	Description
`name`	String	Name of the event.
`event`	Dictionary	A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Returns

Type: void

# remove

Availability

0.8

9.2.0

remove() → void

Removes the database files for this instance from disk. WARNING: this is a destructive operation and cannot be reversed. All data in the database will be lost; use with caution.

Returns

Type: void

# removeEventListener

Availability

0.8

9.2.0

removeEventListener(name, callback) → void

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

Name	Type	Description
`name`	String	Name of the event.
`callback`	Callback<Titanium.Event>	Callback function to remove. Must be the same function passed to `addEventListener`.

Returns

Type: void