README

A drop-in replacement for Laravel's SQLite database driver with a 3-tier fallback chain. Works even when pdo_sqlite and FFI are both unavailable.

Zero code changes needed — install via Composer and your existing 'driver' => 'sqlite' configuration works immediately.

Why?

Some hosting environments or custom PHP builds don't include the pdo_sqlite extension. This package provides the same SQLite functionality through multiple backends:

The package auto-detects the best available backend. The CLI tier auto-downloads sqlite3 from sqlite.org on first use if not found on the system.

• Works with Laravel 10, 11, and 12
• Supports migrations, Eloquent, Query Builder, Schema Builder, transactions, cursors
• Cross-platform: Linux, macOS, Windows
• Same behavior as the native driver — your application code doesn't change

Requirements

Installation

1. Install the package

composer require er-dhruvmishra/laravel-sqlite-ffi

Laravel auto-discovers the service provider. No manual registration needed.

2. Use it

No changes to your code or config. The standard Laravel SQLite configuration works as-is:

// config/database.php
'sqlite' => [
    'driver' => 'sqlite',
    'database' => database_path('database.sqlite'),
    'prefix' => '',
    'foreign_key_constraints' => true,
],

The package automatically picks the best available backend.

3. Optional: Enable specific backends

For FFI (Tier 2):

; /etc/php/8.x/cli/conf.d/20-ffi.ini
extension=ffi.so
ffi.enable=true

For CLI (Tier 3):

# Install sqlite3 binary (or let the package auto-download it)
sudo apt install sqlite3        # Debian/Ubuntu
sudo yum install sqlite         # RHEL/CentOS
brew install sqlite             # macOS

How It Works

Your Laravel App
       |
  'driver' => 'sqlite'
       |
  [SqliteFFIServiceProvider]       ← auto-discovered
       |
  [PdoFactory]                     ← picks best available backend
       |
  ┌────┴────────────┬──────────────────┐
  │                 │                  │
Tier 1           Tier 2             Tier 3
native PDO    SqlitePDO(FFI)    SqliteCliPDO
  │                 │                  │
pdo_sqlite     libsqlite3.so     sqlite3 binary
extension      via PHP FFI       via proc_open

Backend Priority Configuration

By default, the fallback order is: native → ffi → cli

You can customize this in three ways:

Force a specific backend

In config/database.php:

'sqlite' => [
    'driver' => 'sqlite',
    'database' => database_path('database.sqlite'),
    'sqlite_backend' => 'ffi',   // 'native', 'ffi', or 'cli'
],

Or via environment variable:

SQLITE_BACKEND=ffi

Custom fallback order

In config/database.php:

'sqlite' => [
    'driver' => 'sqlite',
    'database' => database_path('database.sqlite'),
    'sqlite_priority' => ['cli', 'ffi', 'native'],  // try CLI first
],

Or via environment variable:

SQLITE_PRIORITY=cli,ffi,native

Set default priority in code

use ErDhruvMishra\SqliteFFI\PdoFactory;

// In a service provider's register() method:
PdoFactory::setDefaultPriority(['ffi', 'cli', 'native']);

Check which backend is active

use ErDhruvMishra\SqliteFFI\PdoFactory;

echo PdoFactory::activeTier();  // 'native', 'ffi', 'cli', or 'none'

TNTSearch Compatibility

If you use teamtnt/tntsearch, it calls new PDO('sqlite:...') directly which fails without pdo_sqlite. This package includes a drop-in engine replacement:

$tnt->loadConfig([
    'driver'   => 'mysql',
    'host'     => config('database.connections.mysql.host'),
    'database' => config('database.connections.mysql.database'),
    'username' => config('database.connections.mysql.username'),
    'password' => config('database.connections.mysql.password'),
    'storage'  => storage_path('tnt_indices') . '/',
    'engine'   => \ErDhruvMishra\SqliteFFI\Compat\TntSearchEngine::class,
]);

The TntSearchEngine uses the same 3-tier fallback as the main driver.

Configuration Options

All standard Laravel SQLite config options are supported, plus:

'sqlite' => [
    'driver' => 'sqlite',
    'database' => database_path('database.sqlite'),
    'prefix' => '',
    'foreign_key_constraints' => true,        // PRAGMA foreign_keys = ON
    'journal_mode' => 'wal',                  // PRAGMA journal_mode = wal
    'busy_timeout' => 5000,                   // PRAGMA busy_timeout (ms)
    'sqlite_backend' => null,                 // Force: 'native', 'ffi', 'cli'
    'sqlite_priority' => null,                // Custom order: ['ffi', 'cli']
],

Environment variables

Supported Features

• CRUD — SELECT, INSERT, UPDATE, DELETE with parameter binding
• Transactions — BEGIN, COMMIT, ROLLBACK, savepoints
• Migrations — php artisan migrate works normally
• Schema Builder — create/alter/drop tables, indexes, foreign keys
• Eloquent ORM — models, relationships, eager loading
• Query Builder — where, join, aggregate, pagination
• Cursors — memory-efficient iteration via generators
• NULL handling — proper NULL value support
• BLOB support — binary data storage
• Foreign key constraints — via foreign_key_constraints config
• WAL mode — via journal_mode config
• Busy timeout — via busy_timeout config

Compatibility

* CLI tier uses client-side parameter escaping (safe, but slightly different execution model).

Troubleshooting

"No SQLite backend available"

At least one backend must be available. Check:

# Check what's available
php -r "
echo 'pdo_sqlite: ' . (extension_loaded('pdo_sqlite') ? 'YES' : 'no') . PHP_EOL;
echo 'FFI: ' . (extension_loaded('FFI') ? 'YES' : 'no') . PHP_EOL;
echo 'ffi.enable: ' . ini_get('ffi.enable') . PHP_EOL;
echo 'sqlite3 CLI: '; exec('which sqlite3 2>/dev/null', \$o, \$c); echo \$c === 0 ? 'YES' : 'no'; echo PHP_EOL;
"

"FFI API is restricted by ffi.enable"

FFI is loaded but ffi.enable is set to preload (default) instead of true:

; Change from preload to true
ffi.enable=true

Restart PHP-FPM after changing:

sudo systemctl restart php8.x-fpm

"libsqlite3 shared library not found"

Install the SQLite3 library:

# Debian/Ubuntu
sudo apt install libsqlite3-0

# RHEL/CentOS
sudo yum install sqlite-libs

# macOS
brew install sqlite

"sqlite3 binary not found"

For CLI tier, install sqlite3 or let the package auto-download it:

# Debian/Ubuntu
sudo apt install sqlite3

# Or set a custom path
export SQLITE3_BINARY_PATH=/path/to/sqlite3

The package will also auto-download from sqlite.org on first use if the bin/ directory is writable.

License

MIT License. See LICENSE for details.