Environment:Promptfoo Promptfoo SQLite Database

Knowledge Sources	Promptfoo better-sqlite3
Domains	Infrastructure, Database
Last Updated	2026-02-14 08:00 GMT

Overview

SQLite database environment using better-sqlite3 with Drizzle ORM, stored at `~/.promptfoo/promptfoo.db` with WAL mode for concurrent access.

Description

Promptfoo uses an embedded SQLite database for persistent storage of evaluation results, datasets, traces, and configuration. The database is managed through Drizzle ORM with the better-sqlite3 driver. By default, WAL (Write-Ahead Logging) mode is enabled for better concurrent read/write performance. The database is created automatically on first use in the user's config directory. For testing, an in-memory database is used when `IS_TESTING=true`.

Usage

This environment is required for all promptfoo operations that persist data: running evaluations, viewing results, retry operations, and sharing. The database initializes automatically; no manual setup is needed.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, Windows	Cross-platform via better-sqlite3
Disk	~50MB minimum	Grows with evaluation history
Filesystem	Local filesystem recommended	WAL mode may fail on network filesystems (NFS, CIFS)
Build Tools	C++ compiler	Required to compile better-sqlite3 native addon

Dependencies

Node.js Packages

`better-sqlite3` >= 12.6.2 (native SQLite3 binding)
`drizzle-orm` >= 0.45.1 (TypeScript ORM)

Build Dependencies

`node-gyp` (for compiling better-sqlite3)
C++ compiler: `build-essential` (Linux), Xcode CLI Tools (macOS), Visual Studio Build Tools (Windows)

Credentials

No credentials required. The database is local and unencrypted.

Configuration environment variables:

`PROMPTFOO_DISABLE_WAL_MODE`: Set to `true` to disable WAL mode (for network filesystems)
`PROMPTFOO_ENABLE_DATABASE_LOGS`: Set to `true` to enable Drizzle query logging
`IS_TESTING`: Set to `true` to use in-memory database

Quick Install

# The database is created automatically. No manual setup needed.
# To verify the database location:
ls ~/.promptfoo/promptfoo.db

# If on a network filesystem, disable WAL mode:
export PROMPTFOO_DISABLE_WAL_MODE=true

Code Evidence

Database initialization from `src/database/index.ts:29-76`:

export function getDb() {
  if (!dbInstance) {
    const isMemoryDb = getEnvBool('IS_TESTING');
    const dbPath = isMemoryDb ? ':memory:' : getDbPath();
    sqliteInstance = new Database(dbPath);
    sqliteInstance.pragma('foreign_keys = ON');

    if (!isMemoryDb && !getEnvBool('PROMPTFOO_DISABLE_WAL_MODE', false)) {
      try {
        sqliteInstance.pragma('journal_mode = WAL');
        // Verify WAL mode was actually enabled
        const result = sqliteInstance.prepare('PRAGMA journal_mode').get();
        if (result.journal_mode.toLowerCase() !== 'wal') {
          logger.warn('Failed to enable WAL mode. This can happen on network filesystems.');
        }
        sqliteInstance.pragma('wal_autocheckpoint = 1000');
        sqliteInstance.pragma('synchronous = NORMAL');
      } catch (err) {
        logger.warn(`Error configuring SQLite WAL mode: ${err}`);
      }
    }
  }
  return dbInstance;
}

Database path from `src/database/index.ts:21-23`:

export function getDbPath() {
  return path.resolve(getConfigDirectoryPath(true), 'promptfoo.db');
}

Common Errors

Error Message	Cause	Solution
`Failed to enable WAL mode (got 'delete')`	Network filesystem does not support WAL	Set `PROMPTFOO_DISABLE_WAL_MODE=true`
`Error configuring SQLite WAL mode`	Containerized environment or permissions issue	Set `PROMPTFOO_DISABLE_WAL_MODE=true`
`SQLITE_BUSY`	Multiple processes writing concurrently	WAL mode should resolve this; ensure WAL is enabled
`Cannot find module 'better-sqlite3'`	Native addon not compiled	Run `npm rebuild better-sqlite3` or install build tools

Compatibility Notes

Network Filesystems (NFS, CIFS): WAL mode may fail. Use `PROMPTFOO_DISABLE_WAL_MODE=true`.
Docker/Containers: Mount a volume for `~/.promptfoo` to persist data. WAL mode may fail in some container runtimes.
Read-only Filesystems: Use `IS_TESTING=true` for in-memory mode if persistence is not needed.
Concurrent Access: WAL mode enables concurrent readers with one writer. Adequate for CLI usage.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment