GRDBVector

GRDBCustom.swift with built-in sqlite-vec vector search support.

This package is an improved alternative to GRDB’s default Custom SQLite setup. It wraps GRDB with a custom SQLite build while simplifying integration, reducing boilerplate, and keeping GRDB’s internal codebase out of your search results for a cleaner project structure.

This build includes:

• sqlite-vec — vector similarity search (cosine, L2, etc.)
• FTS5 — full-text search
• Snapshots — optimized ValueObservation via SQLITE_ENABLE_SNAPSHOT

Installation

Swift Package Manager

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/otocolobus-com/grdb-vector.git", from: "1.0.0")
]

Building from source

Clone with submodules and run the install script:

git clone --recursive https://github.com/otocolobus-com/grdb-vector.git
cd grdb-vector
swift install.swift

The install script:

1. Initializes submodules (GRDB and sqlite-vec)
2. Builds the SQLite amalgamation from GRDB's bundled SQLite source
3. Generates sqlite-vec headers from the template
4. Copies GRDB's shim.h for Swift interop
5. Patches GRDB's inner Package.swift for Xcode builds

Usage

Before opening connection to GRDB, you must call initialize_sqlite3_extensions(). This method loads all extensions.

import GRDB
import SQLiteExtensions

func setupDatabase() throws -> DatabaseQueue {
    initialize_sqlite3_extensions()
    
    // Creating database
}

Then you can can continue using GRDB with new extensions

let dbQueue = try setupDatabase()

// Create a virtual table for 3-dimensional float vectors
try dbQueue.write { db in
    try db.execute(sql: """
        CREATE VIRTUAL TABLE embeddings USING vec0(
            embedding float[3]
        )
        """)

    // Insert vectors
    try db.execute(sql: """
        INSERT INTO embeddings(rowid, embedding)
        VALUES (1, '[1.0, 2.0, 3.0]'),
               (2, '[4.0, 5.0, 6.0]'),
               (3, '[7.0, 8.0, 9.0]')
        """)
}

// KNN search: find the 2 nearest neighbors
let rows = try dbQueue.read { db in
    try Row.fetchAll(db, sql: """
        SELECT rowid, distance
        FROM embeddings
        WHERE embedding MATCH '[3.0, 4.0, 5.0]'
        ORDER BY distance
        LIMIT 2
        """)
}

For full GRDB documentation, see GRDB.swift. For sqlite-vec query syntax, see sqlite-vec documentation.

Versions

Component	Version
GRDB	7.10.0
sqlite-vec	0.1.7
SQLite	3.47.2

Acknowledgements

This package builds upon the ideas and approaches from the following resources:

GRDBCustomSQLiteBuild by SwiftedMind - for inspiration on structuring a custom SQLite integration.

GRDB Custom SQLite Builds Documentation - for guidance on configuring and integrating custom SQLite builds with GRDB.

Their work helped shape the approach used in this package.

License

The glue code, build scripts, and configuration in this repository are released under the MIT License. Copyright (c) 2026 Otocolobus Sp. z o. o.

Dependencies are distributed under their own licenses:

• GRDB.swift — MIT License
• sqlite-vec — MIT License
• SQLite — Public Domain