sqlite-vec: vector search inside SQLite, and where it stops being enough

The problem sqlite-vec solves: KNN queries without a second database

Most vector search setups bolt a second system onto an application that already has a relational database. You keep rows in SQLite or Postgres, embeddings in a dedicated vector store, and then write glue code to keep the two in sync. sqlite-vec removes that split. It is a SQLite extension written in pure C with no dependencies, so it runs wherever SQLite runs: Linux, macOS, Windows, Raspberry Pis, and in the browser through WASM. The README describes it as an "extremely small, 'fast enough' vector search SQLite extension", and as the successor to sqlite-vss.

The target user is someone building local AI features: a desktop app that searches a document collection, a CLI that clusters notes, a small service that stores embeddings beside the text they came from. The vec0 virtual table holds the vectors, and metadata, auxiliary and partition key columns hold the non-vector data, so a single query can filter on a category and rank by distance without a join across systems. If you have ever written a cron job whose only purpose was reconciling two stores, that is the problem this project addresses.

How vec0 works: virtual tables, match, and distance ordering

sqlite-vec registers a virtual table module named vec0. You declare a table with typed vector columns, for example sample_embedding float[8], and the extension manages the underlying storage. Vectors can be inserted as JSON text or in a compact binary format, which matters when you are moving thousands of embeddings and do not want to pay JSON parsing costs.

Querying is the part that differs from an ordinary SQLite table. There is no separate search function to call. You use the match operator on the vector column with the query vector as the right-hand side, then order by the distance column and apply a limit. That means the query planner sees a normal SQL statement, and the extension supplies the ranking. The README's sample output shows distances such as 2.38687372207642 and 2.38978505134583 for the two nearest rows, which is a useful reminder that these are raw distance values, not normalized similarity scores. You decide the threshold.

The repository layout also tells you something the README does not spell out. Alongside sqlite-vec.c there are files named sqlite-vec-ivf.c, sqlite-vec-ivf-kmeans.c, sqlite-vec-diskann.c and sqlite-vec-rescore.c. Those names indicate work on approximate index structures, but the README does not document how to enable or configure them. Treat them as in-progress rather than as features you can rely on.

Installing sqlite-vec and running your first KNN query

The README points to the Installing sqlite-vec page for details and lists a package per language. For Python, the install is a single pip command, and the binding loads the extension for you.

pip install sqlite-vec

For Node.js the equivalent is npm install sqlite-vec, for Ruby gem install sqlite-vec, and for Rust cargo add sqlite-vec. If you are working from C or from the sqlite3 CLI, you build the loadable extension from the Makefile, which produces dist/vec0.so on Linux, dist/vec0.dylib on macOS and dist/vec0.dll on Windows.

make loadable

With the extension built, the README's sample usage is the shortest path to a working query. It loads vec0, creates a table with an 8-dimension float column, and inserts four vectors as JSON strings.

.load ./vec0

create virtual table vec_examples using vec0(
  sample_embedding float[8]
);

insert into vec_examples(rowid, sample_embedding)
  values
    (1, '[-0.200, 0.250, 0.341, -0.211, 0.645, 0.935, -0.316, -0.924]'),
    (2, '[0.443, -0.501, 0.355, -0.771, 0.707, -0.708, -0.185, 0.362]');

The query itself uses match and orders by distance. Running it against the README's four rows returns rowids 2 and 1 with distances around 2.386 and 2.389, so you should see two rows in ascending distance order when you run the same statement with the same query vector.

select rowid, distance
from vec_examples
where sample_embedding match '[0.890, 0.544, 0.825, 0.961, 0.358, 0.0196, 0.521, 0.175]'
order by distance
limit 2;

The examples/ directory has runnable starting points per language, including simple-python, simple-node, simple-go-cgo, simple-rust and simple-wasm, plus a sqlite3-cli example. If the Python or Node binding fails to locate the extension, those directories are the place to compare against.

Where sqlite-vec is the wrong tool

The README carries an explicit warning: sqlite-vec is pre-v1, so expect breaking changes. That single sentence rules it out for projects that cannot absorb schema or API churn on a dependency upgrade. The release history supports the caution. The most recent releases are v0.1.10-alpha.4, v0.1.10-alpha.3 and v0.1.10-alpha.2, all alpha builds, and the last push to the repository was on 2026-05-18. This is not a project you pin and forget.

There is a second, quieter limitation. The interesting index code in the repository (IVF, DiskANN, rescore) has no documented configuration in the README. If your dataset is large enough that brute-force distance computation over every row is too slow, you are betting on features the documentation does not yet describe. The README's own framing, "fast enough", is honest about the trade-off: it is not positioned as a system that will beat a purpose-built vector engine on million-row collections.

A third case is concurrency and write patterns. SQLite is a single-file database with its own locking behaviour, and sqlite-vec inherits that. If your workload is many concurrent writers or a distributed cluster, the extension does not change the underlying model. And if you need the vector store to be a network service that other teams query independently of your application, embedding it in SQLite is the wrong shape.

sqlite-vec compared with a dedicated vector database

The most common alternative people weigh against sqlite-vec is a standalone vector store such as Chroma, and the difference is architectural rather than a matter of feature checklists. A standalone store runs as a process or service, owns its own storage format, and exposes a network API. You get independent scaling, a query interface other services can call, and index types designed for large collections. You also get a second thing to deploy, back up, monitor and keep in sync with your relational data.

sqlite-vec inverts that. The vectors live in the same file as the rest of your data, queries are SQL, and there is no service to run. For a desktop application, a CLI tool, or a single-node service where the embedding set fits comfortably in one database file, that is a smaller system with fewer failure modes. The cost is that you inherit SQLite's limits on concurrency and file size, and you depend on a pre-v1 extension for the vector layer.

Compared with sqlite-vss, its predecessor, the change is in dependencies and portability. sqlite-vss relied on Faiss; sqlite-vec is pure C with no dependencies, which is why the README can claim it runs anywhere SQLite runs, including WASM. If you tried sqlite-vss and were blocked by the native dependency, that is the specific problem sqlite-vec was built to remove.

Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-05-18, which is more than four months before the date of this article. Recent releases are alpha builds of v0.1.10. Budget for upgrade work: read the release notes before bumping, and expect that a schema created against one alpha may need migration for the next. The VERSION file and the release tags are the authoritative source for what you are actually running.

Licensing is straightforward but worth stating precisely. The repository contains both LICENSE-APACHE and LICENSE-MIT, and the project is listed as Apache-2.0. That dual-file layout is common in Rust-adjacent and C projects, and it means you should read both files to understand which terms apply to your use rather than assuming a single licence. This is not legal advice; if you are redistributing the extension inside a commercial product, have counsel read the files in the repository root.

Development is sponsored by Mozilla through its Builders project, with additional sponsorship from Fly.io, Turso, SQLite Cloud and Shinkai, per the README's Sponsors section. Sponsorship is not a support contract. There is no documented commercial support tier, and the SECURITY.md and TODO files in the repository root are where the maintainers record open items.

Editorial conclusion

Adopt sqlite-vec when your embeddings already live next to relational data and you want KNN queries in plain SQL without running a separate server; the Python, Node, Ruby, Go and Rust bindings plus the loadable vec0 extension cover most local and embedded cases. Do not adopt it if you need a stable API, because the README states it is pre-v1 and breaking changes are expected, or if your workload needs an index type the repository only sketches in sqlite-vec-ivf.c and sqlite-vec-diskann.c. Before committing, verify the loadable extension name for your platform, confirm your SQLite build allows extensions, and check the ARCHITECTURE.md and TODO files for the current state of index support.

Frequently asked questions

Official sources

1. asg017/sqlite-vec on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases