# Class Database

java.lang.Object
com.codename1.db.Database

Direct Known Subclasses:
  `ThreadSafeDatabase`

public abstract class Database extends Object

Allows access to SQLite specifically connecting to a database and executing sql queries on the data. There is more thorough coverage of the `Database API here`.

The Database class abstracts the underlying SQLite of the device if available.

Notice that this might not be supported on all platforms in which case the `Database` will be null.

SQLite should be used for very large data handling, for small storage refer to `com.codename1.io.Storage` which is more portable.

The sample code below presents a Database Explorer tool that allows executing arbitrary SQL and viewing the tabular results:

    Toolbar.setGlobalToolbar(true);
    Style s = UIManager.getInstance().getComponentStyle("TitleCommand");
    FontImage icon = FontImage.createMaterial(FontImage.MATERIAL_QUERY_BUILDER, s);
    Form hi = new Form("SQL Explorer", new BorderLayout());
    hi.getToolbar().addCommandToRightBar("", icon, (e) -> {
        TextArea query = new TextArea(3, 80);
        Command ok = new Command("Execute");
        Command cancel = new Command("Cancel");
        if(Dialog.show("Query", query, ok, cancel) == ok) {
            Database db = null;
            Cursor cur = null;
            try {
                db = Display.getInstance().openOrCreate("MyDB.db");
                if(query.getText().startsWith("select")) {
                    cur = db.executeQuery(query.getText());
                    int columns = cur.getColumnCount();
                    hi.removeAll();
                    if(columns > 0) {
                        boolean next = cur.next();
                        if(next) {
                            ArrayList data = new ArrayList<>();
                            String[] columnNames = new String[columns];
                            for(int iter = 0 ; iter

    @author Chen

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Database()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract void`
  `beginTransaction()`
  Starts a transaction
  `abstract void`
  `close()`
  Closes the database
  `abstract void`
  `commitTransaction()`
  Commits current transaction
  `static void`
  `delete(String databaseName)`
  Deletes database
  `abstract void`
  `execute(String sql)`
  Execute an update query.
  `void`
  `execute(String sql, Object... params)`
  Execute an update query with params.
  `abstract void`
  `execute(String sql, String[] params)`
  Execute an update query with params.
  `abstract Cursor`
  `executeQuery(String sql)`
  This method should be called with SELECT type statements that return row set.
  `Cursor`
  `executeQuery(String sql, Object... params)`
  This method should be called with SELECT type statements that return row set it accepts object with params.
  `abstract Cursor`
  `executeQuery(String sql, String[] params)`
  This method should be called with SELECT type statements that return row set.
  `static boolean`
  `exists(String databaseName)`
  Indicates weather a database exists
  `static String`
  `getDatabasePath(String databaseName)`
  Returns the file path of the Database if exists and if supported on the platform.
  `static boolean`
  `isCustomPathSupported()`
  Checks if this platform supports custom database paths.
  `static Database`
  `openOrCreate(String databaseName)`
  Opens a database or create one if not exists.
  `abstract void`
  `rollbackTransaction()`
  Rolls back current transaction
  `static boolean`
  `supportsWasNull(Row row)`
  Checks to see if the given row supports `#wasNull(com.codename1.db.Row)`.
  `static boolean`
  `wasNull(Row row)`
  Checks if the last value accessed from a given row was null.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### Database

    public Database()

- ## Method Details

  - ### isCustomPathSupported

    public static boolean isCustomPathSupported()

    Checks if this platform supports custom database paths. On platforms that support this, you can pass a file path to `#openOrCreate(java.lang.String)`, `#exists(java.lang.String)`, `#delete(java.lang.String)`, and `#getDatabasePath(java.lang.String)`.

    ###### Returns

    True on platorms that support custom database paths.

  - ### openOrCreate

    public static Database openOrCreate(String databaseName) throws java.io.IOException

    Opens a database or create one if not exists.

    ###### Parameters

    - `databaseName`: @param databaseName the name of the database. Platforms that support custom database paths (i.e. `#isCustomPathSupported()` return true), will also accept a file path here.

    ###### Returns

    Database Object or null if not supported on the platform

    ###### Throws

    - `IOException`: if database cannot be created
    Throws:
      `java.io.IOException`

  - ### exists

    public static boolean exists(String databaseName)

    Indicates weather a database exists

    NOTE: Not supported in the Javascript port. Will always return false.

    ###### Parameters

    - `databaseName`: @param databaseName the name of the database. Platforms that support custom database paths (i.e. `#isCustomPathSupported()` return true), will also accept a file path here.

    ###### Returns

    true if database exists

  - ### delete

    public static void delete(String databaseName) throws java.io.IOException

    Deletes database

    NOTE: This method is not supported in the Javascript port. Will silently fail.

    ###### Parameters

    - `databaseName`: @param databaseName the name of the database. Platforms that support custom database paths (i.e. `#isCustomPathSupported()` return true), will also accept a file path here.

    ###### Throws

    - `IOException`: if database cannot be deleted
    Throws:
      `java.io.IOException`

  - ### getDatabasePath

    public static String getDatabasePath(String databaseName)

    Returns the file path of the Database if exists and if supported on the platform.

    ###### Parameters

    - `databaseName`: @param databaseName The name of the database. Platforms that support custom database paths (i.e. `#isCustomPathSupported()` return true), will also accept a file path here.

    NOTE: This method will return null in the Javascript port.

    ###### Returns

    the file path of the database

  - ### wasNull

    public static boolean wasNull(Row row) throws java.io.IOException

    Checks if the last value accessed from a given row was null. Not all platforms support wasNull(). If the platform does not support it, this will just return false.

    Check `#supportsWasNull(com.codename1.db.Row)` to see if the platform supports wasNull().

    Currently wasNull() is supported on UWP, iOS, Android, and JavaSE (Simulator).

    ###### Parameters

    - `row`: The row to check.

    ###### Returns

    True if the last value accessed was null.

    ###### Throws

    - `IOException`

    ###### Since

    7.0

    ###### See also

    - RowExt#wasNull()

    - #supportsWasNull(com.codename1.db.Row)

    Throws:
      `java.io.IOException`

  - ### supportsWasNull

    public static boolean supportsWasNull(Row row) throws java.io.IOException

    Checks to see if the given row supports `#wasNull(com.codename1.db.Row)`.

    ###### Parameters

    - `row`: The row to check.

    ###### Returns

    True if the row supports wasNull().

    ###### Throws

    - `IOException`

    ###### Since

    7.0

    ###### See also

    - #wasNull(com.codename1.db.Row)

    - RowExt#wasNull()

    Throws:
      `java.io.IOException`

  - ### beginTransaction

    public abstract void beginTransaction() throws java.io.IOException

    Starts a transaction

    NOTE: Not supported in Javascript port. This method will do nothing when running in Javascript.

    ###### Throws

    - `IOException`: if database is not opened
    Throws:
      `java.io.IOException`

  - ### commitTransaction

    public abstract void commitTransaction() throws java.io.IOException

    Commits current transaction

    NOTE: Not supported in Javascript port. This method will do nothing when running in Javascript.

    ###### Throws

    - `IOException`: if database is not opened or transaction was not started
    Throws:
      `java.io.IOException`

  - ### rollbackTransaction

    public abstract void rollbackTransaction() throws java.io.IOException

    Rolls back current transaction

    NOTE: Not supported in Javascript port. This method will do nothing when running in Javascript.

    ###### Throws

    - `IOException`: if database is not opened or transaction was not started
    Throws:
      `java.io.IOException`

  - ### close

    public abstract void close() throws java.io.IOException

    Closes the database

    ###### Throws

    - `IOException`
    Throws:
      `java.io.IOException`

  - ### execute

    public abstract void execute(String sql) throws java.io.IOException

    Execute an update query. Used for INSERT, UPDATE, DELETE and similar sql statements.

    ###### Parameters

    - `sql`: the sql to execute

    ###### Throws

    - `IOException`
    Throws:
      `java.io.IOException`

  - ### execute

    public abstract void execute(String sql, String[] params) throws java.io.IOException

    Execute an update query with params. Used for INSERT, UPDATE, DELETE and similar sql statements. The sql can be constructed with '?' and the params will be binded to the query

    ###### Parameters

    - `sql`: the sql to execute

    - `params`: to bind to the query where the '?' exists

    ###### Throws

    - `IOException`
    Throws:
      `java.io.IOException`

  - ### execute

    public void execute(String sql, Object... params) throws java.io.IOException

    Execute an update query with params. Used for INSERT, UPDATE, DELETE and similar sql statements. The sql can be constructed with '?' and the params will be binded to the query

    ###### Parameters

    - `sql`: the sql to execute

    - `params`: @param params to bind to the query where the '?' exists, supported object types are String, byte[], Double, Long and null

    ###### Throws

    - `IOException`
    Throws:
      `java.io.IOException`

  - ### executeQuery

    public abstract Cursor executeQuery(String sql, String[] params) throws java.io.IOException

    This method should be called with SELECT type statements that return row set.

    ###### Parameters

    - `sql`: the sql to execute

    - `params`: to bind to the query where the '?' exists

    ###### Returns

    a cursor to iterate over the results

    ###### Throws

    - `IOException`
    Throws:
      `java.io.IOException`

  - ### executeQuery

    public Cursor executeQuery(String sql, Object... params) throws java.io.IOException

    This method should be called with SELECT type statements that return row set it accepts object with params.

    ###### Parameters

    - `sql`: the sql to execute

    - `params`: @param params to bind to the query where the '?' exists, supported object types are String, byte[], Double, Long and null

    ###### Returns

    a cursor to iterate over the results

    ###### Throws

    - `IOException`
    Throws:
      `java.io.IOException`

  - ### executeQuery

    public abstract Cursor executeQuery(String sql) throws java.io.IOException

    This method should be called with SELECT type statements that return row set.

    ###### Parameters

    - `sql`: the sql to execute

    ###### Returns

    a cursor to iterate over the results

    ###### Throws

    - `IOException`
    Throws:
      `java.io.IOException`