libsql-sqlite3

libsql-sqlite3 is a Swift package that provides a native wrapper around the libSQL fork of SQLite. This package delivers the power of libSQL – a community-driven, open-contribution fork of SQLite – as a pre-built binary (xcframework).

libSQL is designed to extend SQLite's capabilities while maintaining full compatibility with its file format and C API. With this package, you can harness those improvements directly in your Swift applications.

Requirements

• iOS: 11.0 or later (adjustable in Package.swift)
• Swift: 5.3 or later
• Xcode: 12 or later

⚠️ Does not support iOS x86_64 simulator

Installation

Using Xcode (Swift Package Manager)

1. Open your Xcode project.
2. Navigate to File > Swift Packages > Add Package Dependency…
3. Enter the repository URL:
   https://github.com/emarashliev/libsql-sqlite3.git
4. Choose your version rule (e.g., "Up to Next Major" starting from 1.0.0) and finish the setup.

Adding via Package.swift

Include the package dependency in your Package.swift file as shown below:

// swift-tools-version:5.3
import PackageDescription

let package = Package(
    name: "YourProject",
    dependencies: [
        .package(url: "https://github.com/emarashliev/libsql-sqlite3.git", branch: "main")
    ],
    targets: [
        .target(
            name: "YourProject",
            dependencies: ["SQLite3"]
        )
    ]
)

Example Project

The repository includes an Example project that demonstrates how to use libsql-sqlite3 in a real iOS application. This sample project shows best practices for integrating and using SQLite with vector extensions in your Swift projects.

To run the example:

1. Clone the repository
2. Open the Example/Example.xcodeproj file in Xcode
3. Build and run the project

The example demonstrates using vector extensions for similarity search

Use this example as a reference when implementing libsql-sqlite3 in your own projects.

SQLite3 iOS Build Script Documentation

Overview

This script builds SQLite3 libraries with vector extension support for iOS platforms. It creates a universal XCFramework that can be used in iOS applications, supporting both device and simulator architectures.

Features

• Clones the libsql repository with vector extensions
• Builds SQLite3 with common extensions (FTS5, JSON1, RTREE, COLUMN_METADATA)
• Creates a universal XCFramework for iOS (arm64) and iOS Simulator (arm64)
• Provides clean-up functionality for build artifacts
• Supports verbose mode for debugging

Prerequisites

• macOS development environment
• Xcode command-line tools
• Git

Usage

./build.sh [options]

Options

Option	Description
-h, --help	Show help message
-c, --clean-only	Clean build artifacts without building
-v, --verbose	Enable verbose output
-s, --skip-clone	Skip repository cloning (use existing)

Build Process

The script performs the following steps:

1. Repository Cloning: Clones the libsql repository from GitHub, specifically the "vector" branch
2. Building:
   • Configures and builds the base SQLite3 version
   • Builds for iOS device (arm64) with required flags
   • Builds for iOS Simulator (arm64) with required flags
3. XCFramework Creation: Packages the libraries into a universal XCFramework
4. Cleanup: Removes temporary build artifacts

Output

The script generates sqlite3.xcframework in the current directory, which includes:

• Dynamic libraries for iOS (arm64) and iOS Simulator (arm64)
• Headers for SQLite3

Configuration

The script uses these main configuration variables:

REPO_URL="https://github.com/tursodatabase/libsql.git"
BRANCH="vector"
BUILD_DIR="bld"
OUTPUT_FRAMEWORK="sqlite3.xcframework"
SQLITE_FLAGS="-DSQLITE_ENABLE_FTS5 -DSQLITE_ENABLE_JSON1 -DSQLITE_ENABLE_RTREE -DSQLITE_ENABLE_COLUMN_METADATA"

Examples

Standard Build

./build.sh

Clean Before Building

./build.sh --clean-only
./build.sh

Verbose Output

./build.sh --verbose

Using Existing Repository

./build.sh --skip-clone

Troubleshooting

If you encounter issues:

1. Check that Xcode and command-line tools are installed
2. Ensure you have internet access for repository cloning
3. Run in verbose mode for detailed output: ./build.sh --verbose
4. Clean build artifacts and try again: ./build.sh --clean-only && ./build.sh

License

MIT