# SQLite Functions

## Introduction

This is an extension for the SQLite Embeddable SQL Database Engine. SQLite is a C library that implements an embeddable SQL database engine. Programs that link with the SQLite library can have SQL database access without running a separate RDBMS process.

SQLite is not a client library used to connect to a big database server. SQLite is the server. The SQLite library reads and writes directly to and from the database files on disk.

> Note: For further information see the SQLite Website (» http://sqlite.org/).

## Installation

Read the INSTALL file, which comes with the package. Or just use the PEAR installer with pecl install sqlite. SQLite itself is already included, You do not need to install any additional software.

Windows users may download the DLL version of the SQLite extension here: (» php_sqlite.dll).

In PHP 5, the SQLite extension and the engine itself are bundled and compiled by default. However, since PHP 5.1.0 you need to manually activate the extension in php.ini (because it is now bundled as shared). Moreover, since PHP 5.1.0 SQLite depends on PDO it must be enabled too, by adding the following lines to php.ini (in order):

    extension=php_pdo.dll
    extension=php_sqlite.dll

On Linux or Unix operating systems, if you build PDO as a shared extension, you must build SQLite as a shared extension using the --with-sqlite=shared configure option.

SQLite 3 is supported through PDO SQLite.

> Note: Windows installation for unprivileged accounts On Windows operating systems, unprivileged accounts don't have the TMP environment variable set by default. This will make sqlite create temporary files in the windows directory, which is not desirable. So, you should set the TMP environment variable for the web server or the user account the web server is running under. If Apache is your web server, you can accomplish this via a SetEnv directive in your httpd.conf file. For example:

>     SetEnv TMP c:/temp

> If you are unable to establish this setting at the server level, you can implement the setting in your script:
> `putenv('TMP=C:/temp');`
> The setting must refer to a directory that the web server has permission to create files in and subsequently write to and delete the files it created. Otherwise, you may receive the following error message: malformed database schema - unable to open a temporary database file for storing temporary tables

## Requirements

In order to have these functions available, you must compile PHP with SQLite support, or load the SQLite extension dynamically from your php.ini.

## Resource Types

There are two resources used in the SQLite Interface. The first one is the database connection, the second one the result set.

## Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

The functions sqlite_fetch_array() and sqlite_current() use a constant for the different types of result arrays. The following constants are defined:

SQLite result type constants
`SQLITE_ASSOC` (int)
  Columns are returned into the array having the field name as the array index.
`SQLITE_BOTH` (int)
  Columns are returned into the array having both a numerical index and the field name as the array index.
`SQLITE_NUM` (int)
  Columns are returned into the array having a numerical index to the fields. This index starts with 0, the first field in the result.

A number of functions may return status codes. The following constants are defined:

SQLite status code constants
`SQLITE_OK` (int)
  Successful result.
`SQLITE_ERROR` (int)
  SQL error or missing database.
`SQLITE_INTERNAL` (int)
  An internal logic error in SQLite.
`SQLITE_PERM` (int)
  Access permission denied.
`SQLITE_ABORT` (int)
  Callback routine requested an abort.
`SQLITE_BUSY` (int)
  The database file is locked.
`SQLITE_LOCKED` (int)
  A table in the database is locked.
`SQLITE_NOMEM` (int)
  Memory allocation failed.
`SQLITE_READONLY` (int)
  Attempt to write a readonly database.
`SQLITE_INTERRUPT` (int)
  Operation terminated internally.
`SQLITE_IOERR` (int)
  Disk I/O error occurred.
`SQLITE_CORRUPT` (int)
  The database disk image is malformed.
`SQLITE_NOTFOUND` (int)
  (Internal) Table or record not found.
`SQLITE_FULL` (int)
  Insertion failed because database is full.
`SQLITE_CANTOPEN` (int)
  Unable to open the database file.
`SQLITE_PROTOCOL` (int)
  Database lock protocol error.
`SQLITE_EMPTY` (int)
  (Internal) Database table is empty.
`SQLITE_SCHEMA` (int)
  The database schema changed.
`SQLITE_TOOBIG` (int)
  Too much data for one row of a table.
`SQLITE_CONSTRAINT` (int)
  Abort due to constraint violation.
`SQLITE_MISMATCH` (int)
  Data type mismatch.
`SQLITE_MISUSE` (int)
  Library used incorrectly.
`SQLITE_NOLFS` (int)
  Uses of OS features not supported on host.
`SQLITE_AUTH` (int)
  Authorized failed.
`SQLITE_ROW` (int)
  Internal process has another row ready.
`SQLITE_DONE` (int)
  Internal process has finished executing.

## Predefined Classes

## SQLiteDatabase

Represents an opened SQLite database.

## Constructor

- __construct - construct a new SQLiteDatabase object

## Methods

- query - Execute a query

- queryExec - Execute a result-less query

- arrayQuery - Execute a query and return the result as an array

- singleQuery - Execute a query and return either an array for one single column or the value of the first row

- unbufferedQuery - Execute an unbuffered query

- lastInsertRowid - Returns the rowid of the most recently inserted row

- changes - Returns the number of rows changed by the most recent statement

- createAggregate - Register an aggregating UDF for use in SQL statements

- createFunction - Register a UDF for use in SQL statements

- busyTimeout - Sets or disables busy timeout duration

- lastError - Returns the last error code of the most recently encountered error

- fetchColumnTypes - Return an array of column types from a particular table

## SQLiteResult

Represents a buffered SQLite result set.

## Methods

- fetch - Fetches the next row from the result set as an array

- fetchObject - Fetches the next row from the result set as an object

- fetchSingle - Fetches the first column from the result set as a string

- fetchAll - Fetches all rows from the result set as an array of arrays

- column - Fetches a column from the current row of the result set

- numFields - Returns the number of fields in the result set

- fieldName - Returns the name of a particular field in the result set

- current - Fetches the current row from the result set as an array

- key - Return the current row index

- next - Seek to the next row number

- valid - Returns whether more rows are available

- rewind - Seek to the first row number of the result set

- prev - Seek to the previous row number of the result set

- hasPrev - Returns whether or not a previous row is available

- numRows - Returns the number of rows in the result set

- seek - Seek to a particular row number

## SQLiteUnbuffered

Represents an unbuffered SQLite result set. Unbuffered results sets are sequential, forward-seeking only.

## Methods

- fetch - Fetches the next row from the result set as an array

- fetchObject - Fetches the next row from the result set as an object

- fetchSingle - Fetches the first column from the result set as a string

- fetchAll - Fetches all rows from the result set as an array of arrays

- column - Fetches a column from the current row of the result set

- numFields - Returns the number of fields in the result set

- fieldName - Returns the name of a particular field in the result set

- current - Fetches the current row from the result set as an array

- next - Seek to the next row number

- valid - Returns whether more rows are available

## Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

SQLite Configure Options
Name | Default | Changeable | Changelog
--- | --- | --- | ---
sqlite.assoc_case | "0" | PHP_INI_ALL | Available since PHP 5.0.0.

For further details and definitions of the PHP_INI_* constants, see the php.ini directives.

Here's a short explanation of the configuration directives.

`sqlite.assoc_case` int

  Whether to use mixed case (0), upper case (1) or lower case (2) hash indexes.

  This option is primarily useful when you need compatibility with other database systems, where the names of the columns are always returned as uppercase or lowercase, regardless of the case of the actual field names in the database schema.

  The SQLite library returns the column names in their natural case (that matches the case you used in your schema). When `sqlite.assoc_case` is set to 0 the natural case will be preserved. When it is set to 1 or 2, PHP will apply case folding on the hash keys to upper- or lower-case the keys, respectively.

  Use of this option incurs a slight performance penalty, but is MUCH faster than performing the case folding yourself using PHP script.

## Table of Contents

- sqlite_array_query — Execute a query against a given database and returns an array
- sqlite_busy_timeout — Set busy timeout duration, or disable busy handlers
- sqlite_changes — Returns the number of rows that were changed by the most recent SQL statement
- sqlite_close — Closes an open SQLite database
- sqlite_column — Fetches a column from the current row of a result set
- sqlite_create_aggregate — Register an aggregating UDF for use in SQL statements
- sqlite_create_function — Registers a "regular" User Defined Function for use in SQL statements
- sqlite_current — Fetches the current row from a result set as an array
- sqlite_error_string — Returns the textual description of an error code
- sqlite_escape_string — Escapes a string for use as a query parameter
- sqlite_exec — Executes a result-less query against a given database
- sqlite_factory — Opens a SQLite database and returns a SQLiteDatabase object
- sqlite_fetch_all — Fetches all rows from a result set as an array of arrays
- sqlite_fetch_array — Fetches the next row from a result set as an array
- sqlite_fetch_column_types — Return an array of column types from a particular table
- sqlite_fetch_object — Fetches the next row from a result set as an object
- sqlite_fetch_single — Fetches the first column of a result set as a string
- sqlite_fetch_string — Alias of sqlite_fetch_single
- sqlite_field_name — Returns the name of a particular field
- sqlite_has_more — Finds whether or not more rows are available
- sqlite_has_prev — Returns whether or not a previous row is available
- sqlite_key — Returns the current row index
- sqlite_last_error — Returns the error code of the last error for a database
- sqlite_last_insert_rowid — Returns the rowid of the most recently inserted row
- sqlite_libencoding — Returns the encoding of the linked SQLite library
- sqlite_libversion — Returns the version of the linked SQLite library
- sqlite_next — Seek to the next row number
- sqlite_num_fields — Returns the number of fields in a result set
- sqlite_num_rows — Returns the number of rows in a buffered result set
- sqlite_open — Opens a SQLite database and create the database if it does not exist
- sqlite_popen — Opens a persistent handle to an SQLite database and create the database if it does not exist
- sqlite_prev — Seek to the previous row number of a result set
- sqlite_query — Executes a query against a given database and returns a result handle
- sqlite_rewind — Seek to the first row number
- sqlite_seek — Seek to a particular row number of a buffered result set
- sqlite_single_query — Executes a query and returns either an array for one single column or the value of the first row
- sqlite_udf_decode_binary — Decode binary data passed as parameters to an UDF
- sqlite_udf_encode_binary — Encode binary data before returning it from an UDF
- sqlite_unbuffered_query — Execute a query that does not prefetch and buffer all data
- sqlite_valid — Returns whether more rows are available