|
3 | 3 | [](https://discord.gg/Ve7WeCJFXk) |
4 | 4 |
|
5 | 5 | > [!NOTE] |
6 | | -> **Community Fork:** This fork of [`asg017/sqlite-vec`](https://github.com/asg017/sqlite-vec) merges pending upstream PRs and provides continued maintenance while the original repository is inactive. |
| 6 | +> **PhotoStructure's Production Fork:** This is [PhotoStructure](https://photostructure.com)'s actively maintained fork of [`asg017/sqlite-vec`](https://github.com/asg017/sqlite-vec), optimized for production use with additional features, comprehensive testing, and ongoing maintenance funded by PhotoStructure Inc. |
7 | 7 | > |
8 | | -> Credits: [Alex Garcia](https://github.com/asg017) (original implementation), [Vlad Lasky](https://github.com/vlasky) (merged 15+ pending upstream PRs). |
| 8 | +> **Credits:** [Alex Garcia](https://github.com/asg017) (original implementation), [Vlad Lasky](https://github.com/vlasky) (community fork with 15+ merged upstream PRs), PhotoStructure Inc. (ongoing maintenance and improvements). |
| 9 | +> |
| 10 | +> **Why this fork exists:** |
| 11 | +> - PhotoStructure depends on sqlite-vec for production vector search in our photo management platform |
| 12 | +> - We've added production-critical features, security hardening, and comprehensive testing |
| 13 | +> - We're committed to maintaining this for as long as PhotoStructure exists |
| 14 | +> - All improvements remain open source (MIT/Apache-2.0) for the community |
9 | 15 | > |
10 | 16 | > **Fork improvements:** |
11 | | -> - Security hardening (safe integer parsing, vendor checksum validation, pinned CI actions, OIDC releases) |
12 | | -> - Fixed multiple memory leaks via AddressSanitizer/Valgrind testing (see [CHANGELOG](CHANGELOG-mceachen.md)) |
13 | | -> - Node.js: added Alpine/musl and Windows ARM64 prebuilds, all platforms bundled (no post-install scripts) |
14 | | -> - Updated to latest SQLite release |
| 17 | +> - **Testing:** AddressSanitizer/Valgrind/UBSan integration, 30+ error path tests, memory leak fixes |
| 18 | +> - **Security:** Safe integer parsing, vendor checksum validation, pinned CI actions, OIDC releases |
| 19 | +> - **Node.js:** Alpine/musl + Windows ARM64 prebuilds, bundled binaries (no post-install scripts) |
| 20 | +> - **Features:** Distance constraints, OPTIMIZE command, ALTER TABLE RENAME, GLOB/LIKE operators |
| 21 | +> - **Documentation:** Comprehensive error path coverage, KNN filtering behavior, production deployment guides |
15 | 22 | > |
16 | | -> Commits are kept small for easy cherry-picking back upstream. |
| 23 | +> Maintained by PhotoStructure Inc. Contributions welcome. See [CHANGELOG-mceachen.md](CHANGELOG-mceachen.md) for detailed changes. |
17 | 24 |
|
18 | 25 | An extremely small, "fast enough" vector search SQLite extension that runs |
19 | 26 | anywhere! A successor to [`sqlite-vss`](https://github.com/asg017/sqlite-vss) |
@@ -70,27 +77,38 @@ For the latest features from this fork, see "Installing from This Fork" below. |
70 | 77 | | rqlite | `rqlited -extensions-path=sqlite-vec.tar.gz` | [`sqlite-vec` with rqlite](https://alexgarcia.xyz/sqlite-vec/rqlite.html) | [](https://rqlite.io/docs/guides/extensions/) | |
71 | 78 | | `sqlite-utils` | `sqlite-utils install sqlite-utils-sqlite-vec` | [`sqlite-vec` with sqlite-utils](https://alexgarcia.xyz/sqlite-vec/sqlite-utils.html) | [](https://datasette.io/plugins/datasette-sqlite-vec) | |
72 | 79 |
|
73 | | -### Installing from This Fork |
| 80 | +### Installing from PhotoStructure's Fork |
| 81 | + |
| 82 | +Install directly from npm or GitHub to get PhotoStructure's production-ready fork with additional features and comprehensive testing. |
| 83 | + |
| 84 | +#### Node.js (Recommended) |
| 85 | + |
| 86 | +PhotoStructure publishes prebuilt binaries to npm for all major platforms: |
| 87 | + |
| 88 | +```bash |
| 89 | +npm install @photostructure/sqlite-vec |
| 90 | +``` |
| 91 | + |
| 92 | +[](https://www.npmjs.com/package/@photostructure/sqlite-vec) |
74 | 93 |
|
75 | | -Install directly from GitHub to get the latest features from this community fork. |
| 94 | +**Supported platforms:** Linux (x64, ARM64, musl), macOS (x64, ARM64), Windows (x64, ARM64) |
76 | 95 |
|
77 | | -#### Available Languages |
| 96 | +#### Other Languages (Build from Source) |
78 | 97 |
|
79 | 98 | | Language | Install Latest (main branch) | Install Specific Version | |
80 | 99 | |----------|------------------------------|--------------------------| |
81 | | -| **Go** | `go get github.com/vlasky/sqlite-vec/bindings/go/cgo@main` | `go get github.com/vlasky/sqlite-vec/bindings/go/cgo@v0.2.4-alpha` | |
82 | | -| **Lua** | `luarocks install lsqlite3` then copy [`sqlite_vec.lua`](bindings/lua/) to your project. See [Lua example](/examples/simple-lua/) | Download [`sqlite_vec.lua` at v0.2.4-alpha](https://github.com/vlasky/sqlite-vec/blob/v0.2.4-alpha/bindings/lua/sqlite_vec.lua) | |
83 | | -| **Node.js** | `npm install @mceachen/sqlite-vec` | `npm install @mceachen/sqlite-vec@0.3.0` | |
84 | | -| **Python** | `pip install git+https://github.com/vlasky/sqlite-vec.git` | `pip install git+https://github.com/vlasky/sqlite-vec.git@v0.2.4-alpha` | |
85 | | -| **Ruby** | `gem 'sqlite-vec', git: 'https://github.com/vlasky/sqlite-vec'` | `gem 'sqlite-vec', git: 'https://github.com/vlasky/sqlite-vec', tag: 'v0.2.4-alpha'` | |
86 | | -| **Rust** | `cargo add sqlite-vec --git https://github.com/vlasky/sqlite-vec` | `cargo add sqlite-vec --git https://github.com/vlasky/sqlite-vec --tag v0.2.4-alpha` | |
87 | | - |
88 | | -**Python Note:** Requires Python built with loadable extension support (`--enable-loadable-sqlite-extensions`). If you encounter an error about extension support not being available: |
89 | | -- Use `uv` to create virtual environments (automatically uses system Python which typically has extension support) |
| 100 | +| **Go** | `go get github.com/photostructure/sqlite-vec/bindings/go/cgo@main` | `go get github.com/photostructure/sqlite-vec/bindings/go/cgo@v0.4.1` | |
| 101 | +| **Lua** | `luarocks install lsqlite3` then copy [`sqlite_vec.lua`](bindings/lua/) to your project. See [Lua example](/examples/simple-lua/) | Download [`sqlite_vec.lua` at v0.4.1](https://github.com/photostructure/sqlite-vec/blob/v0.4.1/bindings/lua/sqlite_vec.lua) | |
| 102 | +| **Python** | `pip install git+https://github.com/photostructure/sqlite-vec.git` | `pip install git+https://github.com/photostructure/sqlite-vec.git@v0.4.1` | |
| 103 | +| **Ruby** | `gem 'sqlite-vec', git: 'https://github.com/photostructure/sqlite-vec'` | `gem 'sqlite-vec', git: 'https://github.com/photostructure/sqlite-vec', tag: 'v0.4.1'` | |
| 104 | +| **Rust** | `cargo add sqlite-vec --git https://github.com/photostructure/sqlite-vec` | `cargo add sqlite-vec --git https://github.com/photostructure/sqlite-vec --tag v0.4.1` | |
| 105 | + |
| 106 | +**Python Note:** Requires Python built with loadable extension support (`--enable-loadable-sqlite-extensions`). If you encounter errors: |
| 107 | +- Use `uv` to create virtual environments (uses system Python with extension support) |
90 | 108 | - Or use system Python instead of pyenv/custom builds |
91 | 109 | - Or rebuild your Python with `./configure --enable-loadable-sqlite-extensions` |
92 | 110 |
|
93 | | -**Available version tags:** See [Releases](https://github.com/vlasky/sqlite-vec/releases) |
| 111 | +**Available version tags:** See [Releases](https://github.com/photostructure/sqlite-vec/releases) |
94 | 112 |
|
95 | 113 | #### Build from Source |
96 | 114 |
|
|
0 commit comments