CXXX. Funciones SQLite

Introducción

Se trata de una extensión que permite emplear el motor de base de datos embebible SQLite. SQLite es una biblioteca de C que implementa un motor de base de datos SQL embebible. Las aplicaciones que emplean la biblioteca de SQLite pueden emplear bases de datos sin necesidad de instalar un motor de bases datos externo.

SQLite no es una biblioteca cliente para acceder a un servidor de bases datos. El propio SQLite es el servidor de base datos. La biblioteca SQLite lee y escribe directamente sobre los archivos de la base de datos que se encuentran en el disco.

Nota: Para más información puede acceder al sitio web oficial de SQLite: http://sqlite.org/.

Instalación

Lea el archivo INSTALL que viene con el paquete o utilice el instalador de PEAR con el siguiente comando "pear install sqlite". El propio SQLite ya está incluido, así que no es necesario instalar ningún programa adicional.

Los usuarios de Windows pueden descargar el archivo DLL de la extensión SQLite en esta dirección: (php_sqlite.dll).

En PHP 5, la extensión SQLite y el propio motor de bases de datos está incluido y compilado por defecto.

Instalación en Windows con cuentas de usuario sin privilegios: En los sistemas operativos Windows, las cuentas sin privilegios no tienen la variable de entorno TMP establecida por defecto. Por este motivo, SQLite creará los archivos temporales en el directorio de Windows, lo que no es muy recomendable. La solución pasa por crear una variable de entorno llamada TMP para el servidor web o para la cuenta de usuario con la que se ejecuta el servidor web. Si el servidor empleado es Apache, puede establecerse esta variable mediante la directiva SetEnv del archivo de configuración httpd.conf. Por ejemplo:
SetEnv TMP c:/temp
Si no es posible establecer la variable a nivel de servidor, se puede realizar en el mismo script:
putenv('TMP=C:/temp');
La configuración debe hacer referencia a un directorio en el que el servidor web tenga permisos para crear archivos y por tanto para escribir y borrar los archivos creados. Si no tiene los permisos adecuados, se mostrará el siguiente mensaje de error: malformed database schema - unable to open a temporary database file for storing temporary tables

Requirimientos

Para poder utilizar estas funciones, se debe compilar PHP con soporte para SQLite o cargar la extensión SQLite de forma dinámica desde el archivo php.ini.

Tipos de recursos

La interfaz de SQLite utiliza 2 recursos: el primero es de la conexión con la base de datos y el segundo es el resultado.

Constantes predefinidas

Estas constantes están definidas por esta extensión y estarán disponibles solamente cuando la extensión ha sido o bien compilada dentro de PHP o grabada dinámicamente en tiempo de ejecución.

Las funciones sqlite_fetch_array() y sqlite_current() emplean una constante para seleccionar los diferentes tipos de matrices del resultado. Los diferentes constantes definidas son las siguientes:

Constantes del tipo de resultado de SQLite

SQLITE_ASSOC (int): La matriz contiene el nombre de las columnas como índice de los valores.
SQLITE_BOTH (int): La matriz contiene el nombre de las columnas y un índice numérico como índice de los valores.
SQLITE_NUM (int): La matriz contiene un índice numérico como índice de los valores. El índice empieza asignando el 0 al primer campo del resultado.

Algunas funciones devuelven códigos de estado. Se han definido los siguientes códigos:

Constantes del código de estado de SQLite

SQLITE_OK (int): Resultado exitoso.
SQLITE_ERROR (int): Error de SQL o base de datos desconocida.
SQLITE_INTERNAL (int): Error lógico interno de SQLite.
SQLITE_PERM (int): Permiso de acceso denegado.
SQLITE_ABORT (int): La función de callback solicitó una interrupción.
SQLITE_BUSY (int): El archivo de base de datos está bloqueado.
SQLITE_LOCKED (int): Una tabla de la base de datos está bloqueada.
SQLITE_NOMEM (int): Error en la reserva de memoria.
SQLITE_READONLY (int): Se intentó escribir en una base de datos de solo lectura.
SQLITE_INTERRUPT (int): La operación finalizaó internamente.
SQLITE_IOERR (int): Error de E/S en el disco.
SQLITE_CORRUPT (int): La imagen de la base de datos en el disco está corrupta.
SQLITE_NOTFOUND (int): Tabla o registro (internos) no encontrados.
SQLITE_FULL (int): No se pudo reañizar la inserción porque la base de datos está llena.
SQLITE_CANTOPEN (int): No se pudo abrir el archivo de la base de datos.
SQLITE_PROTOCOL (int): Error de bloqueo de base de datos.
SQLITE_EMPTY (int): La tabla (interna) de la base de datos está vacía.
SQLITE_SCHEMA (int): Se ha cambiado el esquema de la base de datos.
SQLITE_TOOBIG (int): Demasiados datos para una fila de la tabla.
SQLITE_CONSTRAINT (int): Interrupción debida a la violación de una restricción (constraint).
SQLITE_MISMATCH (int): Confusión en el tipo de los datos.
SQLITE_MISUSE (int): La librería se empleó de forma incorrecta.
SQLITE_NOLFS (int): Se intentó utilizar unas características de SO no soportadas en el sistema.
SQLITE_AUTH (int): Error de autenticación.
SQLITE_ROW (int): El proceso interno dispone de otra fila.
SQLITE_DONE (int): El proceso interno ha finalizado la ejecución.

Clases predefinidas

SQLiteDatabase

Representa una base de datos de SQLite abierta.

Constructor

__construct - construye un nuevo objeto de tipo SQLiteDatabase

Métodos

query - Ejecuta una consulta
queryExec - Ejecuta una consulta sin resultado
arrayQuery - Ejecuta una consulta y devuelve el resultado como una matriz
singleQuery - Ejecuta una consulta y devuelve o una matriz para una columna o el valor de la primera fila
unbufferedQuery - Ejecuta una consulta que devuelve el resultado de forma inmediata (unbuffered)
lastInsertRowid - Devuelve el identificador de la última fila que se ha insertado
changes - Devuelve el número de filas que se han modificado tras la última sentencia SQL
createAggregate - Registra una FDU (Función Definida por el Usuario) empleada para agregar resultados en las sentencias SQL
createFunction - Registra una FDU (Función Definida por el Usuario) para emplearla en las sentencias SQL
busyTimeout - Establece el valor o deshabilita la duración del temporizador de ocupado
lastErorr - Devuelve el último código de error del último error producido
fetchColumnTypes - Devuelve una matriz con los tipos de las columnas de una tabla determinada

SQLiteResult

Representa un resultado almacenado (buffered) de SQLite

Métodos

fetch - Obtiene la siguiente fila del resultado y la devuelve como una matriz
fetchObject - Obtiene la siguiente fila del resultado y la devuelve como un objeto
fetchSingle - Obtiene la primera columna del resultado y la devuelve en una cadena
fetchAll - Obtiene todas las filas del resultado y las devuelve como una matriz de matrices
column - Obtiene una columna de la fila actual del resultado
numFields - Obtiene el n´mero de campos del resultado
fieldName - Obtiene el nombre de un campo del resultado
current - Obtiene la fila actual del resultado y la devuelve como una matriz
key - Obtiene el índice de la fila actual
next - Se desplaza hasta el siguiente número de fila
valid - Indica si hay disponibles más filas
rewind - Se desplaza hasta el primer número de fila del resultado
prev - Se desplaza hasta el anterior número de fila
hasPrev - Indica si hay disponible alguna fila anterior
numRows - Obtiene el n´mero de filas en el resultado
seek - Se desplaza hasta un determinado número de fila

SQLiteUnbuffered

Representa un resultado no almacenado (unbuffered) de SQLite. Los resultados no almacenados son secuenciales y por tanto solamente se puede avanzar en ellos (no retroceder).

Métodos

fetch - Obtiene la siguiente fila del resultado y la devuelve como una matriz
fetchObject - Obtiene la siguiente fila del resultado y la devuelve como un objeto
fetchSingle - Obtiene la primera columna del resultado y la devuelve en una cadena
fetchAll - Obtiene todas las filas del resultado y las devuelve como una matriz de matrices
column - Obtiene una columna de la fila actual del resultado
numFields - Obtiene el n´mero de campos del resultado
fieldName - Obtiene el nombre de un campo del resultado
current - Obtiene la fila actual del resultado y la devuelve como una matriz
next - Se desplaza hasta el siguiente número de fila
valid - Indica si hay disponibles más filas

Configuración en tiempo de ejecución

El comportamiento de estas funciones está afectado por los valores definidos en php.ini.

Tabla 1. Configure Options de SQLite

Name	Default	Changeable	Registro de cambios
sqlite.assoc_case	"0"	PHP_INI_ALL	Disponible desde PHP 5.0.0.

For further details and definitions of the PHP_INI_* constants, see the Apéndice H.

A continuación se presenta una corta explicación de las directivas de configuración.

sqlite.assoc_case int

Uso de índices hash sin distinguir mayúsculas y minúsculas (0), solo mayúsculas (1) o solo minúsculas(2).

Esta opción se emplea cuando se requiere compatibilidad con otros sistemas de bases de datos, donde los nombres de las columnas siempre se devuelven o en mayúsculas o en minúsculas, independientemente de la forma en la que se almacenan los nombres de los campos en el esquema de la base de datos.

La librería SQLite devuelve el nombre de las columnas tal y como aparecen en el esquema de base de datos. Si el valor de sqlite.assoc_case es 0, se mantendrán los nombres originales. Si se pone a 1 o a 2, PHP convertirá los nombres originales a mayúsculas o en minúsculas respectivamente.

El uso de esta opción introduce una pequeña penalización en el rendimiento, pero es significativamente más rápida que hacerlo manualmente en el script de PHP.

Tabla de contenidos
sqlite_array_query -- Ejecuta una consulta contra una base de datos y devuelve el resultado en forma de matriz
sqlite_busy_timeout -- Establece la duración del temporizador de ocupado o deshabilita los temporizadores
sqlite_changes -- Devuelve el número de filas que se han modificado en la última sentencia SQL
sqlite_close -- Cierra una base de datos SQLite abierta
sqlite_column -- Obtiene una columna de la fila actual del resultado
sqlite_create_aggregate -- Registra una FDU (función definida por el usuario) de grupo normal para su uso en sentencias SQL
sqlite_create_function -- Registra una FDU (función definida por el usuario) normal para su uso en sentencias SQL
sqlite_current -- Obtiene la fila actual del resultado en forma de matriz
sqlite_error_string -- Devuelve la descripción del error producido a partir de un código de error
sqlite_escape_string -- Escapa una cadena de texto para poder usarla como parámetro en una consulta
sqlite_exec -- Ejecuta una consulta que no produce resultado
sqlite_factory -- Abre una base de datos SQLite y devuelve un objeto SQLiteDatabase
sqlite_fetch_all -- Obtiene todas las filas del resultado en forma de matriz de matrices
sqlite_fetch_array -- Obtiene la siguiente fila del resultado en forma de matriz
sqlite_fetch_column_types -- Obtiene una matriz con los tipos de las columnas de una tabla
sqlite_fetch_object -- Obtiene la siguiente fila del resultado en forma de objeto
sqlite_fetch_single -- Obtiene la primera columna del resultado en forma de cadena
sqlite_fetch_string -- Alias of sqlite_fetch_single()
sqlite_field_name -- Obtiene el nombre de un campo
sqlite_has_more -- Indica si existen más filas disponibles
sqlite_has_prev -- Indica si está disponible una fila anterior
sqlite_key -- Devuelve el índice de la fila actual
sqlite_last_error -- Devuelve el código de error del último error producido en la base de datos
sqlite_last_insert_rowid -- Devuelve el identificador de fila de la última fila insertada
sqlite_libencoding -- Devuelve la codificación de la librería SQLite que se está empleando
sqlite_libversion -- Devuelve la versión de la librería SQLite que se está empleando
sqlite_next -- Se desplaza hasta el siguiente número de fila
sqlite_num_fields -- Obtiene el número de campos de un resultado
sqlite_num_rows -- Obtiene el número de filas de un resultado almacenado (buffered)
sqlite_open -- Abre una base de datos de SQLite y la crea si no existía
sqlite_popen -- Abre una base de datos de SQLite de forma persistente y la crea si no existía
sqlite_prev -- Se desplaza hasta el anterior número de fila
sqlite_query -- Ejecuta una consulta sobre la base de datos y devuelve un manejador del resultado
sqlite_rewind -- Se desplaza hasta el primer número de fila
sqlite_seek -- Se desplaza hasta un determinado número de fila de un resultado almacenado (buffered)
sqlite_single_query -- Ejecuta una consulta y devuelve o una matriz para una columna o el valor de la primera fila
sqlite_udf_decode_binary -- Decodifica los datos binarios que se pasan como parámetro a las funciones FDU (función definida por el usuario)
sqlite_udf_encode_binary -- Codifica los datos binarios antes de devolverlos de una FDU (función definida por el usuario)
sqlite_unbuffered_query -- Ejecuta una consulta sobre la base de datos cuyo resultado no almacena todos los datos devueltos
sqlite_valid -- Indica si hay más filas disponibles en el resultado