Added in API level 35

SQLiteRawStatement


class SQLiteRawStatement : Closeable
kotlin.Any
   ↳ android.database.sqlite.SQLiteRawStatement

A represents a SQLite prepared statement. The methods correspond very closely to SQLite APIs that operate on a sqlite_stmt object. In general, each API in this class corresponds to a single SQLite API.

A SQLiteRawStatement must be created through a database, and there must be a transaction open at the time. Statements are implicitly closed when the outermost transaction ends, or if the current transaction is marked successful. Statements may be explicitly closed at any time with #close. The #close operation is idempotent and may be called multiple times without harm.

Multiple SQLiteRawStatements may be open simultaneously. They are independent of each other. Closing one statement does not affect any other statement nor does it have any effect on the enclosing transaction.

Once a SQLiteRawStatement has been closed, no further database operations are permitted on that statement. An IllegalStateException will be thrown if a database operation is attempted on a closed statement.

All operations on a SQLiteRawStatement must be invoked from the thread that created it. A IllegalStateException will be thrown if cross-thread use is detected.

A common pattern for statements is try-with-resources.

<code>
  // Begin a transaction.
  database.beginTransaction();
  try (SQLiteRawStatement statement = database.createRawStatement("SELECT * FROM ...")) {
      while (statement.step()) {
          // Fetch columns from the result rows.
      }
      database.setTransactionSuccessful();
  } finally {
      database.endTransaction();
  }
  </code>
Note that SQLiteRawStatement is unrelated to SQLiteStatement.

Summary

Constants
static Int

The constant returned by getColumnType when the column value is SQLITE_BLOB.

static Int

The constant returned by getColumnType when the column value is SQLITE_FLOAT.

static Int

The constant returned by getColumnType when the column value is SQLITE_INTEGER.

static Int

The constant returned by getColumnType when the column value is SQLITE_NULL.

static Int

The constant returned by getColumnType when the column value is SQLITE_TEXT.

Public methods
Unit
bindBlob(parameterIndex: Int, value: ByteArray)

Bind a blob to a parameter.

Unit
bindBlob(parameterIndex: Int, value: ByteArray, offset: Int, length: Int)

Bind a blob to a parameter.

Unit
bindDouble(parameterIndex: Int, value: Double)

Bind a double to a parameter.

Unit
bindInt(parameterIndex: Int, value: Int)

Bind an int to a parameter.

Unit
bindLong(parameterIndex: Int, value: Long)

Bind a long to the parameter.

Unit
bindNull(parameterIndex: Int)

Bind a null to the parameter.

Unit
bindText(parameterIndex: Int, value: String)

Bind a string to the parameter.

Unit

Clear all parameter bindings.

Unit

Close the object and release any native resources.

ByteArray?
getColumnBlob(columnIndex: Int)

Return the column value of the result row as a blob.

Double
getColumnDouble(columnIndex: Int)

Return the column value as a double.

Int
getColumnInt(columnIndex: Int)

Return the column value as a int.

Int
getColumnLength(columnIndex: Int)

Return the length of the column value in the result row.

Long
getColumnLong(columnIndex: Int)

Return the column value as a long.

String
getColumnName(columnIndex: Int)

Return the name of the column in the result row.

String
getColumnText(columnIndex: Int)

Return the column value as a text.

Int
getColumnType(columnIndex: Int)

Return the type of the column in the result row.

Int

Return the number of parameters in the statement.

Int

Return the index of the parameter with specified name.

String?
getParameterName(parameterIndex: Int)

Return the name of the parameter at the specified index.

Int

Return the number of columns in the current result row.

Boolean

Return true if the statement is still open and false otherwise.

Int
readColumnBlob(columnIndex: Int, buffer: ByteArray, offset: Int, length: Int, srcOffset: Int)

Copy the column value of the result row, interpreted as a blob, into the buffer.

Unit

Reset the statement.

Boolean

Step to the next result row.

String

Constants

SQLITE_DATA_TYPE_BLOB

Added in API level 35
static val SQLITE_DATA_TYPE_BLOB: Int

The constant returned by getColumnType when the column value is SQLITE_BLOB.

Value: 4

SQLITE_DATA_TYPE_FLOAT

Added in API level 35
static val SQLITE_DATA_TYPE_FLOAT: Int

The constant returned by getColumnType when the column value is SQLITE_FLOAT.

Value: 2

SQLITE_DATA_TYPE_INTEGER

Added in API level 35
static val SQLITE_DATA_TYPE_INTEGER: Int

The constant returned by getColumnType when the column value is SQLITE_INTEGER.

Value: 1

SQLITE_DATA_TYPE_NULL

Added in API level 35
static val SQLITE_DATA_TYPE_NULL: Int

The constant returned by getColumnType when the column value is SQLITE_NULL.

Value: 5

SQLITE_DATA_TYPE_TEXT

Added in API level 35
static val SQLITE_DATA_TYPE_TEXT: Int

The constant returned by getColumnType when the column value is SQLITE_TEXT.

Value: 3

Public methods

bindBlob

Added in API level 35
fun bindBlob(
    parameterIndex: Int,
    value: ByteArray
): Unit

Bind a blob to a parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

Parameters
parameterIndex Int: The index of the parameter in the query. It is one-based.
value ByteArray: The value to be bound to the parameter. This value cannot be null.
Exceptions
java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
android.database.sqlite.SQLiteException if a native error occurs.

See Also

    bindBlob

    Added in API level 35
    fun bindBlob(
        parameterIndex: Int,
        value: ByteArray,
        offset: Int,
        length: Int
    ): Unit

    Bind a blob to a parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds. The sub-array value[offset] to value[offset+length-1] is bound.

    Parameters
    parameterIndex Int: The index of the parameter in the query. It is one-based.
    value ByteArray: The value to be bound to the parameter. This value cannot be null.
    offset Int: An offset into the value array
    length Int: The number of bytes to bind from the value array.
    Exceptions
    java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
    java.lang.IllegalArgumentException if the sub-array exceeds the bounds of the value array.
    android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
    android.database.sqlite.SQLiteException if a native error occurs.

    See Also

      bindDouble

      Added in API level 35
      fun bindDouble(
          parameterIndex: Int,
          value: Double
      ): Unit

      Bind a double to a parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

      Parameters
      parameterIndex Int: The index of the parameter in the query. It is one-based.
      value Double: The value to be bound to the parameter.
      Exceptions
      java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
      android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
      android.database.sqlite.SQLiteException if a native error occurs.

      See Also

        bindInt

        Added in API level 35
        fun bindInt(
            parameterIndex: Int,
            value: Int
        ): Unit

        Bind an int to a parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

        Parameters
        parameterIndex Int: The index of the parameter in the query. It is one-based.
        Exceptions
        java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
        android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
        android.database.sqlite.SQLiteException if a native error occurs.

        See Also

          bindLong

          Added in API level 35
          fun bindLong(
              parameterIndex: Int,
              value: Long
          ): Unit

          Bind a long to the parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

          Parameters
          value Long: The value to be bound to the parameter.
          Exceptions
          java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
          android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
          android.database.sqlite.SQLiteException if a native error occurs.

          See Also

            bindNull

            Added in API level 35
            fun bindNull(parameterIndex: Int): Unit

            Bind a null to the parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds.

            Parameters
            parameterIndex Int: The index of the parameter in the query. It is one-based.
            Exceptions
            java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
            android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
            android.database.sqlite.SQLiteException if a native error occurs.

            See Also

              bindText

              Added in API level 35
              fun bindText(
                  parameterIndex: Int,
                  value: String
              ): Unit

              Bind a string to the parameter. Parameter indices start at 1. The function throws if the parameter index is out of bounds. The string may not be null.

              Parameters
              parameterIndex Int: The index of the parameter in the query. It is one-based.
              value String: The value to be bound to the parameter. This value cannot be null.
              Exceptions
              java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
              android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the parameter is out of range.
              android.database.sqlite.SQLiteException if a native error occurs.

              See Also

                clearBindings

                Added in API level 35
                fun clearBindings(): Unit

                Clear all parameter bindings.

                Exceptions
                java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
                android.database.sqlite.SQLiteException if a native error occurs.

                See Also

                  close

                  Added in API level 35
                  fun close(): Unit

                  Close the object and release any native resources. It is not an error to call this on an already-closed object.

                  Exceptions
                  java.lang.Exception if this resource cannot be closed
                  java.io.IOException if an I/O error occurs

                  getColumnBlob

                  Added in API level 35
                  fun getColumnBlob(columnIndex: Int): ByteArray?

                  Return the column value of the result row as a blob. Column indices start at 0. This throws an exception if column is not in the result. This returns null if the column value is null. The column value will be converted if it is not of type SQLITE_DATA_TYPE_BLOB; see the sqlite documentation for details.

                  Parameters
                  columnIndex Int: The index of a column in the result row. It is zero-based.
                  Return
                  ByteArray? The value of the column as a blob, or null if the column is NULL.
                  Exceptions
                  java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
                  android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
                  android.database.sqlite.SQLiteException if a native error occurs.

                  See Also

                    getColumnDouble

                    Added in API level 35
                    fun getColumnDouble(columnIndex: Int): Double

                    Return the column value as a double. Column indices start at 0. This throws an exception if column is not in the result. The column value will be converted if it is not of type SQLITE_DATA_TYPE_FLOAT; see the sqlite documentation for details.

                    Parameters
                    columnIndex Int: The index of a column in the result row. It is zero-based.
                    Return
                    Double The value of a column as a double.
                    Exceptions
                    java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
                    android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
                    android.database.sqlite.SQLiteException if a native error occurs.

                    See Also

                      getColumnInt

                      Added in API level 35
                      fun getColumnInt(columnIndex: Int): Int

                      Return the column value as a int. Column indices start at 0. This throws an exception if column is not in the result. The column value will be converted if it is not of type SQLITE_DATA_TYPE_INTEGER; see the sqlite documentation for details.

                      Parameters
                      columnIndex Int: The index of a column in the result row. It is zero-based.
                      Return
                      Int The value of the column as an int.
                      Exceptions
                      java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
                      android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
                      android.database.sqlite.SQLiteException if a native error occurs.

                      See Also

                        getColumnLength

                        Added in API level 35
                        fun getColumnLength(columnIndex: Int): Int

                        Return the length of the column value in the result row. Column indices start at 0. This returns 0 for a null and number of bytes for text or blob. Numeric values are converted to a string and the length of the string is returned. See the sqlite documentation for details. Note that this cannot be used to distinguish a null value from an empty text or blob. Note that this returns the number of bytes in the text value, not the number of characters.

                        Parameters
                        columnIndex Int: The index of a column in the result row. It is zero-based.
                        Return
                        Int The length, in bytes, of the value in the column.
                        Exceptions
                        java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
                        android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
                        android.database.sqlite.SQLiteException if a native error occurs.

                        See Also

                          getColumnLong

                          Added in API level 35
                          fun getColumnLong(columnIndex: Int): Long

                          Return the column value as a long. Column indices start at 0. This throws an exception if column is not in the result. The column value will be converted if it is not of type SQLITE_DATA_TYPE_INTEGER; see the sqlite documentation for details.

                          Parameters
                          columnIndex Int: The index of a column in the result row. It is zero-based.
                          Return
                          Long The value of the column as an long.
                          Exceptions
                          java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
                          android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
                          android.database.sqlite.SQLiteException if a native error occurs.

                          See Also

                            getColumnName

                            Added in API level 35
                            fun getColumnName(columnIndex: Int): String

                            Return the name of the column in the result row. Column indices start at 0. This throws an exception if column is not in the result.

                            Parameters
                            columnIndex Int: The index of a column in the result row. It is zero-based.
                            Return
                            String The name of the column in the result row. This value cannot be null.
                            Exceptions
                            java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
                            android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
                            android.database.sqlite.SQLiteOutOfMemoryException if the database cannot allocate memory for the name.

                            See Also

                              getColumnText

                              Added in API level 35
                              fun getColumnText(columnIndex: Int): String

                              Return the column value as a text. Column indices start at 0. This throws an exception if column is not in the result. The column value will be converted if it is not of type SQLITE_DATA_TYPE_TEXT; see the sqlite documentation for details.

                              Parameters
                              columnIndex Int: The index of a column in the result row. It is zero-based.
                              Return
                              String The value of the column as a string. This value cannot be null.
                              Exceptions
                              java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
                              android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
                              android.database.sqlite.SQLiteException if a native error occurs.

                              See Also

                                getColumnType

                                Added in API level 35
                                fun getColumnType(columnIndex: Int): Int

                                Return the type of the column in the result row. Column indices start at 0.

                                Parameters
                                columnIndex Int: The index of a column in the result row. It is zero-based.
                                Return
                                Int The type of the value in the column of the result row. Value is android.database.sqlite.SQLiteRawStatement#SQLITE_DATA_TYPE_INTEGER, android.database.sqlite.SQLiteRawStatement#SQLITE_DATA_TYPE_FLOAT, android.database.sqlite.SQLiteRawStatement#SQLITE_DATA_TYPE_TEXT, android.database.sqlite.SQLiteRawStatement#SQLITE_DATA_TYPE_BLOB, or android.database.sqlite.SQLiteRawStatement#SQLITE_DATA_TYPE_NULL
                                Exceptions
                                java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
                                android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
                                android.database.sqlite.SQLiteException if a native error occurs.

                                See Also

                                  getParameterCount

                                  Added in API level 35
                                  fun getParameterCount(): Int

                                  Return the number of parameters in the statement.

                                  Return
                                  Int The number of parameters in the statement.
                                  Exceptions
                                  java.lang.IllegalStateException if the statement is closed or this is a foreign thread.

                                  See Also

                                    getParameterIndex

                                    Added in API level 35
                                    fun getParameterIndex(name: String): Int

                                    Return the index of the parameter with specified name. If the name does not match any parameter, 0 is returned.

                                    Parameters
                                    name String: The name of a parameter. This value cannot be null.
                                    Return
                                    Int The index of the parameter or 0 if the name does not identify a parameter.
                                    Exceptions
                                    java.lang.IllegalStateException if the statement is closed or this is a foreign thread.

                                    See Also

                                      getParameterName

                                      Added in API level 35
                                      fun getParameterName(parameterIndex: Int): String?

                                      Return the name of the parameter at the specified index. Null is returned if there is no such parameter or if the parameter does not have a name.

                                      Parameters
                                      parameterIndex Int: The index of the parameter.
                                      Return
                                      String? The name of the parameter. This value may be null.
                                      Exceptions
                                      java.lang.IllegalStateException if the statement is closed or this is a foreign thread.

                                      See Also

                                        getResultColumnCount

                                        Added in API level 35
                                        fun getResultColumnCount(): Int

                                        Return the number of columns in the current result row.

                                        Return
                                        Int The number of columns in the result row.
                                        Exceptions
                                        java.lang.IllegalStateException if the statement is closed or this is a foreign thread.

                                        See Also

                                          isOpen

                                          Added in API level 35
                                          fun isOpen(): Boolean

                                          Return true if the statement is still open and false otherwise.

                                          Return
                                          Boolean True if the statement is open.

                                          readColumnBlob

                                          Added in API level 35
                                          fun readColumnBlob(
                                              columnIndex: Int,
                                              buffer: ByteArray,
                                              offset: Int,
                                              length: Int,
                                              srcOffset: Int
                                          ): Int

                                          Copy the column value of the result row, interpreted as a blob, into the buffer. Column indices start at 0. This throws an exception if column is not in the result row. Bytes are copied into the buffer starting at the offset. Bytes are copied from the blob starting at srcOffset. Length bytes are copied unless the column value has fewer bytes available. The function returns the number of bytes copied. The column value will be converted if it is not of type SQLITE_DATA_TYPE_BLOB; see the sqlite documentation for details.

                                          Parameters
                                          columnIndex Int: The index of a column in the result row. It is zero-based.
                                          buffer ByteArray: A pre-allocated array to be filled with the value of the column. This value cannot be null.
                                          offset Int: An offset into the buffer: copying starts here.
                                          length Int: The number of bytes to copy.
                                          srcOffset Int: The offset into the blob from which to start copying.
                                          Return
                                          Int the number of bytes that were copied.
                                          Exceptions
                                          java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
                                          java.lang.IllegalArgumentException if the buffer is too small for offset+length.
                                          android.database.sqlite.SQLiteBindOrColumnIndexOutOfRangeException if the column is out of range.
                                          android.database.sqlite.SQLiteException if a native error occurs.

                                          See Also

                                            reset

                                            Added in API level 35
                                            fun reset(): Unit

                                            Reset the statement.

                                            Exceptions
                                            java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
                                            android.database.sqlite.SQLiteException if a native error occurs.

                                            See Also

                                              step

                                              Added in API level 35
                                              fun step(): Boolean

                                              Step to the next result row. This returns true if the statement stepped to a new row, and false if the statement is done. The method throws on any other result, including a busy or locked database. If WAL is enabled then the database should never be locked or busy.

                                              Return
                                              Boolean True if a row is available and false otherwise.
                                              Exceptions
                                              java.lang.IllegalStateException if the statement is closed or this is a foreign thread.
                                              android.database.sqlite.SQLiteDatabaseLockedException if the database is locked or busy.
                                              android.database.sqlite.SQLiteException if a native error occurs.

                                              See Also

                                                toString

                                                Added in API level 35
                                                fun toString(): String
                                                Return
                                                String a string representation of the object.