Abrir una nueva conexión de base de datos

int sqlite3_open(
  const char *filename,   /* Nombre de fichero de base de datos (UTF-8) */
  sqlite3 **ppDb          /* OUT: manipulador de base de datos SQLite */
);
int sqlite3_open16(
  const void *filename,   /* Nombre de fichero de base de datos (UTF-16) */
  sqlite3 **ppDb          /* OUT: manipulador de base de datos SQLite */
);
int sqlite3_open_v2(
  const char *filename,   /* Nombre de fichero de base de datos (UTF-8) */
  sqlite3 **ppDb,         /* OUT: manipulador de base de datos SQLite */
  int flags,              /* Banderas */
  const char *zVfs        /* Nombre de módulo VFS a usar */
);

Estas funciones abren un fichero de base de datos SQLite especificado por el nombre de fichero del primer parámetro. El argumento de nombre de fichero es interpretado como UTF-8 para sqlite3_open() y sqlite3_open_v2() y como UTF-16 en el orden de bytes nativo para sqlite3_open16(). Generalmente se retorna un manipulador de conexión de base de datos en *ppDb, incluso si se produce un error. La única excepción es que si SQLite es incapaz de asignar memoria para contener el objeto sqlite3, se escribe un NULL en *ppDb en lugar de un puntero al objeto sqlite3. Si la base de datos es abierta (y/o creada) con éxito, se retorna SQLITE_OK. En caso contrario se retorna un código de error. Las funciones sqlite3_errmsg() o sqlite3_errmsg16() se pueden usar para obtener una descripción en inglés del error después de un fallo de cualquier función sqlite3_open().

La codificación por defecto para la base de datos será UTF-8 si se llama a sqlite3_open() o sqlite3_open_v2() y UTF-16 en el orden de bytes nativo si se usa sqlite3_open16().

Cuando se abre, tanto si ocurre un error como si no, los recursos asociados con el manipulador de la conexión de base de datos deben ser liberados pasándo este manipulador a sqlite3_close() cuando ya no sea necesario.

El interfaz sqlite3_open_v2() funciona igual que sqlite3_open() excepto que acepta dos parámetros adicionales para mayor control sobre la nueva conexión de base de datos. El parámetro flags para sqlite3_open_v2() puede tomar uno de los tres valores siguientes, opcionalmente combinados con los flags SQLITE_OPEN_NOMUTEX, SQLITE_OPEN_FULLMUTEX, SQLITE_OPEN_SHAREDCACHE, SQLITE_OPEN_PRIVATECACHE y/o SQLITE_OPEN_URI:

SQLITE_OPEN_READONLY

La base de datos se abre en modo de sólo lectura. Si la base de datos no existe aún, se devuelve un error.

SQLITE_OPEN_READWRITE

La base de datos se abre para lectura y escritura si es posible, o sólo para lectura si el fichero está protefido para escritura por el sistema operativo. En cualquier caso la base de datos debe existir previamente, o se retornará un error.

SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE

La base de datos se abre para lectura y escritura, y es creada si no existe previamente. Este es el comportamiento que siempre se usa por sqlite3_open() y sqlite3_open16().

Si el tercer parámetro de sqlite3_open_v2() no es una de las combinaciones mostradas arriba opcionalmente combinada con otros bits SQLITE_OPEN_* el comportamiento es impredecible.

Si la bandera SQLITE_OPEN_NOMUTEX está activada, la conexión de base de datos se abre en el modo multihilo siempre que el modo de hilo único no haya sido activado en tiempo de compilación o en el arranque. Si la bandera SQLITE_OPEN_FULLMUTEX está activa la conexión de base de datos se abre en el modo de ejecución serializado salvo que se haya seleccionado el modo de hilo único seleccionado previamente durante la compilación o en el arranque. La bandera SQLITE_OPEN_SHAREDCACHE hace que la conexión de base de datos sea candidata a usarse en modo de caché compartida, independientemente de si la caché compartida está activada o no usando sqlite3_enable_shared_cache(). La bandera SQLITE_OPEN_PRIVATECACHE hace que la conexión de base de datos no participe en el modo de caché compartida aunque esté permitida.

El cuarto parámetro de sqlite3_open_v2() es el nombre del objeto sqlite3_vfs que define el interfaz de sistema operativo que la nueva conexión de base de datos usará. Si el curato parámetro es un puntero NULL se usa el objeto sqlite3_vfs por defecto.

Si el nombre de fichero es ":memory:", se crea una base de datos privara en memoria para la conexión. Esta base de datos en memoria se destruye cuando la conexión de base de datos se cierra. Futuras versiones de SQLite podrán hacer uso de nombres de fichero especiales adicionales con el carácter ":". Se recomienda que cuando un nombre de fichero de base de datos comience con un carácter ":" se debe preceder el nombre de fichero con un nombre de camino como "./" para evitar ambigüedad.

Si el nombre de fichero es una cadena vacía, entonces se crea una base de datos temporal en disco. Esta base de datos privada será borrada automáticamente tan pronto como la conexión de base de datos se cierre.

Nombres de fichero URI

Si la interpretación de nombres de fichero URI está activa, y el argumento de nombre de fichero empieza con "file:", el nombre de fichero se interpreta como una URI. La interpretación URI está activa si el flag SQLITE_OPEN_URI está asignado en el cuarto argumento de sqlite3_open_v2(), o si ha sido activada globalmente usando la opción SQLITE_CONFIG_URI con la función sqlite3_config() o por la opción de compilación SQLITE_USE_URI. Desde la versión 3.7.7 de SQLite, la interpretación URI está apagada por defecto, pero en futuras versiones de SQLite se podría activar por defecto.

Los nombres URI se analizan de acuerdo con la norma RFC 3986. Si la URI contiene una autoridad, debe ser una cadena vacía o la cadena "localhost".Si no es así, se devuelve un error. El componente fragmento de la URI, si existe, es ignorado.

SQLite usa el componente camino de la URI como el nombre de fichero de disco que contiene la base de datos. Si la ruta empieza con el carácter '/', se interpreta como una ruta absoluta. Si no empieza con '/' (lo que significa que la sección de autoridad se omite de la URI), el camino se interpreta como una ruta relativa. En Windows, el primer componente de una ruta absoluta es la especificación de disco (por ejemplo, "C:").

La componente consulta de una URI puede contener parámetros que se interpretan por el propio SQLite, o por una implementación personalizada del VFD. SQLite interpreta los siguientes tres parámetros de consulta:

• vfs: El parámetro "vfs" se puede usar para especificar el nombre de un objeto VFS que proporcione la interfaz del sistema operativo que se debe utilizar par acceder al fichero de base de datos en el disco. Si esta opción es una cadena vacía se usa el objeto VFS por defecto. Especificar un VFS desconocido en un error. Si se usa sqlite3_open_v2() y la opción vfs está presente, entonces el VFS especificado por la opción tiene prioridad sobre el valor del cuarto parámeto de sqlite3_open_v2().
• mode: El parámetro modo puede ser asignado a "ro", "rw" o "rwc". Un intento de asignar cualquier otro valor se considera un error. Si se especifica "ro", la base de datos se abre para acceso sólo de lectura, igual que si se hubiese especificado la bandera SQLITE_OPEN_READONLY en el tercer argumento de sqlite3_prepare_v2(). Si la opción de modo es "rw", la base de datos se abre para acceso de lectura-escritura (pero no se crea), como si se hubiese especificado SQLITE_OPEN_READWRITE (pero no SQLITE_OPEN_CREATE). El valor "rwc" es equivalente a activar SQLITE_OPEN_READWRITE y SQLITE_OPEN_CREATE. Si se usa sqlite3_open_v2(), es un error especificar un valor para el parámetro modo que sea menos restrictivo que el especificado en las banderas pasadas como tercer parámetro.
• cache: El parámetro caché puede ser asignado a "shared" o "private". Asignarlo a "shared" equivale a activar el bit SQLITE_OPEN_SHAREDCACHE en el argumento de banderas pasado a sqlite3_open_v2(). Establecer el parámetro de caché a "private" equivale a activar el bit SQLITE_OPEN_PRIVATECACHE. Si se usa sqlite3_open_v2() y el parámetro "cache" está presente en el nombre de fichero URI, su valor tiene prioridad sobre cualquier comportamiento solicitado mediante la bandera SQLITE_OPEN_PRIVATECACHE o SQLITE_OPEN_SHAREDCACHE flag.

Especificar un parámetro desconocido en la componente consulta de una URI no se considera un error. Versiones futuras de SQLite podrían entender parámetros de consulta adicionales.

Ejemplos de nombres de fichero URI

Las secuencias de escape hexadecimales (%HH) están soportadas en el interior de rutas y componentes de consulta de un URI. Una secuencia de escape hexadecimal consiste en un signo de porcentaje - "%" - seguido por por exactamente dos dígitos hexadecimales que especifican un valor de un octeto. Antes de que la ruta o componentes de consulta de un nombre de fichero URI sea interpretado, se condifican usando UTF-8 y todas las secuencias de escape hexadecimanes se reemplazan por un único byte conteniendo el octeto correspondiente. Si el proceso genera una codificación UTF-8 inválida, el resultado es indefinido.

Nota para usuarios de Windows: la codificación usada para el argumento de nombre de fichero de sqlite3_open() y sqlite3_open_v2() debe ser UTF-8, no el código de página actualmente definido. Los nombres de fichero que contengan caracteres internacionales deben ser convertidos a UTF-8 antes de pasarlos a sqlite3_open() o sqlite3_open_v2().