# Titanium.Database

> The top-level `Database` module, used for creating and accessing the in-application SQLite database.

- Source: https://titaniumsdk.com/docs/sdk/Titanium.Database
- Titanium SDK version: 14.0.0
- Kind: module
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 0.1
- Extends: Titanium.Module
- Inheritance: Titanium.Module > Titanium.Proxy

## Properties

### CREATE_IF_NECESSARY

- Type: Number
- Platforms: Android
- Since: Titanium SDK 14.0.0
- Permission: read-only

Open flag for [Titanium.Database.open](https://titaniumsdk.com/docs/sdk/Titanium.Database.md#open) requesting that the database file be created
if it does not already exist.

### ENABLE_WRITE_AHEAD_LOGGING

- Type: Number
- Platforms: Android
- Since: Titanium SDK 14.0.0
- Permission: read-only

Open flag for [Titanium.Database.open](https://titaniumsdk.com/docs/sdk/Titanium.Database.md#open) enabling SQLite write-ahead logging (WAL).

WAL allows readers and a writer to operate concurrently at the cost of additional
`-wal` and `-shm` files alongside the database. It cannot be combined with
[Titanium.Database.OPEN_READONLY](https://titaniumsdk.com/docs/sdk/Titanium.Database.md#OPEN_READONLY).

### FIELD_TYPE_DOUBLE

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Constant for requesting a column's value returned in double form.

### FIELD_TYPE_FLOAT

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Constant for requesting a column's value returned in float form.

### FIELD_TYPE_INT

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Constant for requesting a column's value returned in integer form.

### FIELD_TYPE_STRING

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Constant for requesting a column's value returned in string form.

### NO_LOCALIZED_COLLATORS

- Type: Number
- Platforms: Android
- Since: Titanium SDK 14.0.0
- Permission: read-only

Open flag for [Titanium.Database.open](https://titaniumsdk.com/docs/sdk/Titanium.Database.md#open) requesting that the database not be
rebuilt with the device's current locale collators.

Use this when the database ships with the app and must not be modified on open,
such as a read-only database on external storage.

### OPEN_READONLY

- Type: Number
- Platforms: Android
- Since: Titanium SDK 14.0.0
- Permission: read-only

Open flag for [Titanium.Database.open](https://titaniumsdk.com/docs/sdk/Titanium.Database.md#open) requesting read-only access.

Any attempt to write to a database opened with this flag throws an exception.

### OPEN_READWRITE

- Type: Number
- Platforms: Android
- Since: Titanium SDK 14.0.0
- Permission: read-only

Open flag for [Titanium.Database.open](https://titaniumsdk.com/docs/sdk/Titanium.Database.md#open) requesting read/write access.

## Methods

### install

- Platforms: Android, iPhone, iPad, macOS

Installs an SQLite database to device's internal storage.

Copies an SQLite database file to the device's internal storage (only) and
creates a persistent name that is available for the lifetime of the app.
On Android, if the source file does not exist, an empty database is created.

Returns a reference to the opened database. If the destination file already
exists, behaves as [Titanium.Database.open](https://titaniumsdk.com/docs/sdk/Titanium.Database.md#open).

This method is primarily used for iOS.

With Android, as there is often minimal internal storage available, `install`
may only be appropriate for small databases or for prototyping. When database
files are to be stored on external storage (for example, SD Card), a combination of
[Titanium.Filesystem](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md) and [Titanium.Database.open](https://titaniumsdk.com/docs/sdk/Titanium.Database.md#open) is required.

With Titanium 1.8.0.1 on iOS, the default database location changed in accordance
with Apple's guidelines. If a database file already exists in the old
location, `install` will automatically move it to the new location
rather than copying the file from the path provided in the first
argument.

Files stored in the `Private Documents` directory on iOS 5 will be
automatically backed up to iCloud and removed from the device in low
storage situations. See
[How do I prevent files from being backed up to iCloud?](https://developer.apple.com/library/ios/qa/qa1719/_index.html)
for details. To prevent this for database files, use the [Titanium.Database.DB.file](https://titaniumsdk.com/docs/sdk/Titanium.Database.DB.md#file)
object with the [Titanium.Filesystem.File.remoteBackup](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.File.md#remoteBackup) property.

Always [close](https://titaniumsdk.com/docs/sdk/Titanium.Database.DB.md#close) the database after use.

Parameters:

- `path` (String): Path and filename of the database file to copy to internal storage. File location is relative to the script's context unless an absolute path, such as one constructed with a [Titanium.Filesystem](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md) constant, is used.
- `dbName` (String): Destination filename or absolute path, which will subsequently be passed to [Titanium.Database.open](https://titaniumsdk.com/docs/sdk/Titanium.Database.md#open).

Returns: Titanium.Database.DB

Example: Install a Database (iOS)

A database, with a filename of `mydb1` and located in the same directory as the
the running script, is installed.

``` js
var db1 = Ti.Database.install('mydb1', 'mydb1Installed');
```

The file is copied to the default database location with a file
extension of `sql`.

**On simulator**

* `/Users/user_name/Library/Application Support/iPhone Simulator/ios_version/Applications/apple_app_id/Library/Private Documents/mydb1Installed.sql` (Titanium 1.8.0.1)
* `/Users/user_name/Library/Application Support/iPhone Simulator/ios_version/Applications/apple_app_id/Library/Application Support/database/mydb1Installed.sql` (earlier versions)

**On device**

* `/Applications/apple_app_id/Library/Private Documents/mydb1Installed.sql` (Titanium 1.8.0.1)
* `/Applications/apple_app_id/Library/Application Support/database/mydb1Installed.sql` (earlier versions)

To prevent the database file being automatically backed up to iCloud, use [remoteBackup](Titanium.Filesystem.File.remoteBackup).

``` js
db1.file.remoteBackup = false;
```

Example: Install a Database to Internal Storage (Android)

A database, with a filename of `mydb1` and located in the same directory as the
the running script, is installed.

``` js
var db1 = Ti.Database.install('mydb1', 'mydb1Installed');
```

Unlike on iOS, no file extension is added. The file is opened in the
following default database location, on both emulator and device.

* `file:///data/data/appID/databases/mydb1Installed`

Example: Install a Database to External Storage (Android)

The device is checked for the presence of external storage and a
database, with a filename of `mydb2` and located in the same directory as the
the running script, is installed.

``` js
if (Ti.Platform.name === 'android' && Ti.Filesystem.isExternalStoragePresent()) {
  var db2 = Ti.Database.install('mydb2', Ti.Filesystem.externalStorageDirectory + 'path' + Ti.Filesystem.separator + 'to' + Ti.Filesystem.separator + 'mydb2Installed');
}
```

Unlike on iOS, no file extension is added. The file is copied to the
absolute path provided.

* `file:///sdcard/path/to/mydb2Installed`

### open

- Platforms: Android, iPhone, iPad, macOS

Opens an SQLite database.

Opens an SQLite database and returns a reference to it. If the database does
not exist, creates an empty database file and returns a reference to this
opened database.

With Titanium 1.8.0.1 on iOS, the default database location changed in accordance
with Apple's guidelines. If a database file already exists in the old
location, `open` will automatically move it to the new location.

Always [close](https://titaniumsdk.com/docs/sdk/Titanium.Database.DB.md#close) the database after use.

Parameters:

- `dbName` (String): The dbname previously passed to [Titanium.Database.install](https://titaniumsdk.com/docs/sdk/Titanium.Database.md#install). An absolute path to the file, including one that is constructed with a [Titanium.Filesystem](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md) constant or [Titanium.Filesystem.directoryForSuite](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#directoryForSuite) method, may be used.
- `flags` (Number, optional): Bitmask controlling how the database is opened. Android only, since Titanium SDK 14.0.0; ignored on all other platforms. The given value *replaces* the defaults rather than being combined with them. When omitted, the database is opened with [Titanium.Database.CREATE_IF_NECESSARY](https://titaniumsdk.com/docs/sdk/Titanium.Database.md#CREATE_IF_NECESSARY) | [Titanium.Database.NO_LOCALIZED_COLLATORS](https://titaniumsdk.com/docs/sdk/Titanium.Database.md#NO_LOCALIZED_COLLATORS). So passing [Titanium.Database.OPEN_READONLY](https://titaniumsdk.com/docs/sdk/Titanium.Database.md#OPEN_READONLY) on its own opens the database read-only *without* `NO_LOCALIZED_COLLATORS` — combine the constants explicitly to keep it. Opening a database that does not exist without [Titanium.Database.CREATE_IF_NECESSARY](https://titaniumsdk.com/docs/sdk/Titanium.Database.md#CREATE_IF_NECESSARY) throws an exception.

Returns: Titanium.Database.DB

Example: Open a Database from Internal Storage (iOS)

A database, with a persistent name of `mydb1Installed` and located in the
default database location on internal storage, is opened.

``` js
var db = Ti.Database.open('mydb1Installed');
```

A file extension of `sql` is added, and the file is opened from the
following location.

On simulator

* `/Users/<user name>/Library/Application Support/iPhone Simulator/<iOS version>/Applications/<apple app id>/Library/Private Documents/mydb1Installed.sql` (Titanium 1.8.0.1)
* `/Users/<user name>/Library/Application Support/iPhone Simulator/<iOS version>/Applications/<apple app id>/Library/Application Support/database/mydb1Installed.sql` (earlier versions)

On device

* `/Applications/<apple app id>/Library/Private Documents/mydb1Installed.sql` (Titanium 1.8.0.1)
* `/Applications/<apple app id>/Library/Application Support/database/mydb1Installed.sql` (earlier versions)

Example: Open a Database on Internal Storage (Android)

A database, with a persistent name of `mydb1Installed` and located in the
default database location on internal storage, is opened.

``` js
var db1 = Ti.Database.open('mydb1Installed');
```

Unlike on iOS, no file extension is added. The file is opened in
the following location.

* `file:///data/data/appID/databases/mydb1Installed`

Example: Open a Database on External Storage (Android)

A database, with a filename of `mydb2Installed` and located at the
absolute path provided, is opened.

``` js
if (Ti.Platform.name === 'android' && Ti.Filesystem.isExternalStoragePresent()) {
  var db2 = Ti.Database.open(Ti.Filesystem.externalStorageDirectory + 'path' + Ti.Filesystem.separator + 'to' + Ti.Filesystem.separator + 'mydb2Installed');
}
```

Unlike on iOS, no file extension is added. The file is copied to the
absolute path, as follows.

* `file:///sdcard/path/to/mydb2Installed`

Example: Open a Database in the shared directory of an application group (iOS)

Opens a Database in a shared directory

``` js
var suiteDir = Ti.Filesystem.directoryForSuite('group.appc.Sharing');
if (!suiteDir) {
    logInApp('Suite Directory not found, check Entitlements.');
    return;
}
var path = suiteDir + 'TestDB';
var db = Ti.Database.open(path);
db.close();
```

## Inherited members

7 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`

---

- This corpus documents Titanium SDK 14.0.0. Anything here that does not name a version describes 14.0.0.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.