# Class: Statement

Defined in: | coffee/api.coffee

## Overview

Represents an prepared statement.

Prepared statements allow you to have a template sql string, that you can execute multiple times with different parameters.

You can't instantiate this class directly, you have to use a Database object in order to create a statement.

Warning: When you close a database (using db.close()), all its statements are closed too and become unusable.

### See also:

- Database.html#prepare-dynamic
- https://en.wikipedia.org/wiki/Prepared_statement

## Instance Method Summary

- # (Boolean) bind(values) Bind values to the parameters, after having reseted the statement

  SQL statements can have parameters, named '?', '?NNN', ':VVV', '@VVV', '$VVV', where NNN is a number and VVV a string.

- # (Boolean) step() Execute the statement, fetching the the next line of result, that can be retrieved with Statement.get() .
- # (Array<String,Number,Uint8Array,null>) get(params) Get one row of results of a statement.
- # (Array<String>) getColumnNames() Get the list of column names of a row of result of a statement.
- # (Object) getAsObject(params) Get one row of result as a javascript object, associating column names with their value in the current row.
- # (void) run(values) Shorthand for bind + step + reset Bind the values, execute the statement, ignoring the rows it returns, and resets it
- # (void) reset() Reset a statement, so that it's parameters can be bound to new values It also clears all previous bindings, freeing the memory used by bound parameters.
- # (void) freemem() Free the memory allocated during parameter binding
- # (Boolean) free() Free the memory used by the statement

## Instance Method Details

# (Boolean) bind(values)

Bind values to the parameters, after having reseted the statement

SQL statements can have parameters, named '?', '?NNN', ':VVV', '@VVV', '$VVV', where NNN is a number and VVV a string. This function binds these parameters to the given values.

Warning: ':', '@', and '$' are included in the parameters names

## Binding values to named parameters

- Create a statement that contains parameters like '$VVV', ':VVV', '@VVV'
- Call Statement.bind with an object as parameter

## Binding values to parameters

- Create a statement that contains parameters like '?', '?NNN'
- Call Statement.bind with an array as parameter

## Value types

Javascript type | SQLite type
--- | ---
number | REAL, INTEGER
boolean | INTEGER
string | TEXT
Array, Uint8Array | BLOB
null | NULL

### Examples:

#### Bind values to named parameters

      var stmt = db.prepare("UPDATE test SET a=@newval WHERE id BETWEEN $mini AND $maxi");
      stmt.bind({$mini:10, $maxi:20, '@newval':5});

#### Bind values to anonymous parameters

      var stmt = db.prepare("UPDATE test SET a=? WHERE id BETWEEN ? AND ?");
      stmt.bind([5, 10, 20]);

### Parameters:

- values ( `Array,Object` ) — The values to bind

### Throws:

- ( `String` ) — SQLite Error

### Returns:

- ( `Boolean` ) — true if it worked

### See also:

- http://www.sqlite.org/datatype3.html
- http://www.sqlite.org/lang_expr.html#varparam

# (Boolean) step()

Execute the statement, fetching the the next line of result, that can be retrieved with Statement.get() .

### Throws:

- ( `String` ) — SQLite Error

### Returns:

- ( `Boolean` ) — true if a row of result available

# (Array<String,Number,Uint8Array,null>) get(params)

Get one row of results of a statement. If the first parameter is not provided, step must have been called before get.

### Examples:

#### Print all the rows of the table test to the console

      var stmt = db.prepare("SELECT * FROM test");
      while (stmt.step()) console.log(stmt.get());

### Parameters:

- Optional: ( `Array,Object` ) — If set, the values will be bound to the statement, and it will be executed

### Returns:

- ( `Array<String,Number,Uint8Array,null>` ) — One row of result

# (Array<String>) getColumnNames()

Get the list of column names of a row of result of a statement.

### Examples:

####

      var stmt = db.prepare("SELECT 5 AS nbr, x'616200' AS data, NULL AS nothing;");
      stmt.step(); // Execute the statement
      console.log(stmt.getColumnNames()); // Will print ['nbr','data','nothing']

### Returns:

- ( `Array<String>` ) — The names of the columns

# (Object) getAsObject(params)

Get one row of result as a javascript object, associating column names with their value in the current row.

### Examples:

####

      var stmt = db.prepare("SELECT 5 AS nbr, x'616200' AS data, NULL AS nothing;");
      stmt.step(); // Execute the statement
      console.log(stmt.getAsObject()); // Will print {nbr:5, data: Uint8Array([1,2,3]), nothing:null}

### Parameters:

- Optional: ( `Array,Object` ) — If set, the values will be bound to the statement, and it will be executed

### Returns:

- ( `Object` ) — The row of result

### See also:

- [Statement.get](#get-dynamic)

# (void) run(values)

Shorthand for bind + step + reset Bind the values, execute the statement, ignoring the rows it returns, and resets it

### Parameters:

- Value ( `Array,Object` ) — to bind to the statement

# (void) reset()

Reset a statement, so that it's parameters can be bound to new values It also clears all previous bindings, freeing the memory used by bound parameters.

# (void) freemem()

Free the memory allocated during parameter binding

# (Boolean) free()

Free the memory used by the statement

### Returns:

- ( `Boolean` ) — true in case of success

Quickly fuzzy find classes, mixins, methods, file:

- T Open fuzzy finder dialog

Control the navigation frame:

- L Toggle list view
- C Show class list
- I Show mixin list
- F Show file list
- M Show method list
- E Show extras list

You can focus and blur the search input:

- S Focus search input
- Esc Blur search input