Download the PHP package mongoose-studio/phobos-framework-database-sqlite without Composer

Phobos Framework - SQLite Driver

Driver SQLite para Phobos Framework Database Layer. Cero configuración de servidor: conecta a un archivo .sqlite o a una base de datos en memoria (:memory:), con las claves foráneas activadas por defecto y los PRAGMAs más útiles expuestos como opciones de conexión.

Es el driver ideal para tests (SQLite en memoria, rápido y aislado), prototipos y aplicaciones de escritorio o embebidas.

Características

• 🪶 Sin servidor - Un archivo o :memory:, sin host, puerto ni credenciales
• 🔒 Foreign keys activas por defecto - SQLite las trae apagadas; este driver las enciende
• ⚡ PRAGMAs comunes - journal_mode (WAL), busy_timeout, synchronous
• 🎯 Savepoints - Transacciones anidadas completas
• 🧪 Ideal para testing - :memory: da una BD limpia por proceso
• 🛡️ Valores validados - Los PRAGMAs pasan por lista blanca para evitar inyección
• 🏷️ Identificadores estándar - Citado con comillas dobles

Instalación

Dependencias

Este driver requiere:

• mongoose-studio/phobos-framework ^3.1
• mongoose-studio/phobos-framework-database ^3.2
• Extensión ext-pdo habilitada
• Extensión ext-pdo_sqlite habilitada

Configuración

1. Registrar el Driver

En tu config/database.php:

2. Variables de Entorno

En tu archivo .env:

Opciones de Configuración

A diferencia de MySQL, SQLite no usa host, port, username, password, charset ni collation. La única opción obligatoria es database.

database (obligatorio)

Nota sobre :memory:: cada conexión PDO nueva crea una base de datos en memoria independiente. Mientras reutilices la misma conexión (como hace el ConnectionManager), los datos persisten durante todo el proceso — perfecto para una suite de tests.

foreign_keys (por defecto true)

SQLite trae las claves foráneas desactivadas por defecto (una de las trampas más comunes del motor). Este driver las activa salvo que lo indiques explícitamente:

journal_mode

Controla el modo de journaling. WAL (Write-Ahead Logging) suele ser la mejor opción para concurrencia:

Valores válidos: DELETE, TRUNCATE, PERSIST, MEMORY, WAL, OFF.

• WAL - Mejor concurrencia (lectores no bloquean al escritor). Recomendado para archivos.
• MEMORY - Journal en RAM, más rápido pero menos seguro ante caídas.
• DELETE - Comportamiento clásico por defecto de SQLite.

busy_timeout

Milisegundos que SQLite espera ante un bloqueo antes de devolver SQLITE_BUSY:

synchronous

Nivel de sincronización con disco. Compromiso entre durabilidad y velocidad:

Valores válidos: OFF, NORMAL, FULL, EXTRA (o sus equivalentes numéricos 0, 1, 2, 3).

• FULL - Máxima durabilidad (default de SQLite).
• NORMAL - Buen equilibrio, recomendado con WAL.
• OFF - El más rápido, pero puede corromper datos ante un corte de energía.

Opciones PDO Adicionales

Características Específicas de SQLite

Identificadores con Comillas Dobles

El driver usa comillas dobles para identificadores (el estándar SQL):

SQLite también acepta backticks (por compatibilidad con MySQL), por lo que el Query Builder del núcleo funciona sin cambios sobre este driver.

Transacciones Anidadas (Savepoints)

SQLite soporta savepoints, así que las transacciones anidadas del TransactionManager funcionan igual que en MySQL:

Niveles de Aislamiento

SQLite es SERIALIZABLE de forma nativa. A diferencia de MySQL, no soporta READ COMMITTED ni REPEATABLE READ. Lo único que puede relajarse es a READ UNCOMMITTED (y solo tiene efecto en modo shared-cache):

Pedir un nivel que SQLite no soporta lanza una InvalidArgumentException explícita, en vez de generar SQL inválido silenciosamente.

Ejemplos de Uso

Testing (SQLite en memoria)

La configuración de oro para una suite de tests: rápida, aislada y sin dejar rastro en disco.

Aplicación con archivo persistente

Arquitectura

Estructura del Driver

Proceso de Conexión

1. DSN Generation: getDSN() construye la cadena

   • Archivo: sqlite:/ruta/a/app.sqlite
   • Memoria: sqlite::memory:

2. PDO Creation: Se crea la instancia PDO con las opciones seguras por defecto (modo de error por excepción, fetch asociativo, prepares nativos).

3. Post-Connection Config: configure() ejecuta los PRAGMAs
   • PRAGMA foreign_keys (ON por defecto)
   • PRAGMA journal_mode si se configuró
   • PRAGMA busy_timeout si se configuró
   • PRAGMA synchronous si se configuró

Compatibilidad

• SQLite 3.x (vía ext-pdo_sqlite)
• Soporte completo de savepoints y claves foráneas (SQLite 3.6.19+)
• WAL disponible desde SQLite 3.7.0+

🐛 Troubleshooting

Las claves foráneas no se respetan

Si esperabas que un INSERT con una FK inválida fallara y no lo hace, revisa que no hayas puesto 'foreign_keys' => false. Recuerda que SQLite las trae apagadas por defecto: este driver las activa, pero solo si no las desactivas explícitamente.

SQLSTATE[HY000]: database is locked

SQLite bloquea el archivo completo durante una escritura. Mitiga con:

unable to open database file

• Verifica que el directorio del archivo exista (SQLite crea el archivo, no las carpetas).
• Verifica permisos de escritura en el directorio.
• Usa una ruta absoluta para evitar sorpresas con el directorio de trabajo.

Los datos de :memory: desaparecen entre partes del código

Cada conexión PDO nueva a :memory: es una base distinta. Asegúrate de reutilizar la misma conexión (el ConnectionManager la cachea). No abras un PDO nuevo esperando ver los datos de otro.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para más detalles.

Autor

Marcel Rojas
[email protected]
Mongoose Studio

Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/amazing-feature)
3. Commit tus cambios (git commit -m 'Add amazing feature')
4. Push a la rama (git push origin feature/amazing-feature)
5. Abre un Pull Request

Phobos Framework by Mongoose Studio