# Local `sqlite-vec` Setup

Local Bun runtimes on macOS use Apple’s system SQLite by default, and that build does not support loading SQLite extensions. This repo now auto-detects Homebrew SQLite for local development and e2e boot paths so native `sqlite-vec` can load when a compatible library is available.

## Automatic local setup

The following entrypoints auto-detect Homebrew SQLite on macOS:

- `bun run dev`
- `bun run e2e:webserver`
- `bun run e2e:prepare`

If either of these files exists, local runtimes configure Bun to use it before any database connection is created:

- `/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib`
- `/usr/local/opt/sqlite/lib/libsqlite3.dylib`

The vector extension path is resolved from the installed `sqlite-vec` package rather than a hardcoded repository path.

## Install Homebrew SQLite

```bash
brew install sqlite
```

## Explicit overrides

You can still override the auto-detected values explicitly:

```bash
export SQLITE_CUSTOM_LIB_PATH=/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib
export SQLITE_VEC_EXTENSION_PATH=/absolute/path/to/vec0.dylib
```

- `SQLITE_CUSTOM_LIB_PATH` must point to the SQLite dynamic library, not the `sqlite3` executable.
- `SQLITE_VEC_EXTENSION_PATH` must point to the loadable `sqlite-vec` extension file.

Explicit env values take precedence over auto-detection.

## Fallback behavior

If a compatible SQLite library is not available, the app still starts and search still works:

- FTS text search remains enabled
- vector storage falls back to the table-backed implementation
- native `sqlite-vec` acceleration is simply unavailable

If explicit native paths are configured and loading still fails, startup logs keep that failure noisy so broken native configuration is visible immediately.