# tauri-plugin-libsql

**Repository Path**: sternelee/tauri-plugin-libsql

## Basic Information

- **Project Name**: tauri-plugin-libsql
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-13
- **Last Updated**: 2025-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Tauri Plugin LibSQL

A [Tauri](https://tauri.app) plugin for SQLite database access using [LibSQL](https://libsql.org/), providing local and remote synchronization capabilities.

## Installation

### Rust

```toml
# Cargo.toml
[dependencies]
tauri-plugin-libsql = { git = "https://github.com/yourusername/tauri-plugin-libsql" }
```

### JavaScript

```js
import { connect } from 'tauri-plugin-libsql-api';
```

## Usage

### Rust

```rust
use tauri_plugin_libsql::*;

fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_libsql::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
```

### JavaScript

```js
import { connect, execute, query, sync, close } from 'tauri-plugin-libsql-api';

// Connect to a database
const connectionId = await connect({
  url: 'libsql://your-database.turso.io',
  authToken: 'your-auth-token',
  localPath: 'path/to/local/db.sqlite', // Optional for local-first mode
});

// Execute a SQL statement
const result = await execute({
  connectionId,
  sql: 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)',
});

// Insert data with positional parameters
await execute({
  connectionId,
  sql: 'INSERT INTO users (name, age) VALUES (?, ?)',
  params: [
    { type: 'Text', value: 'John Doe' },
    { type: 'Integer', value: 30 }
  ],
});

// Insert data with named parameters (recommended)
await execute({
  connectionId,
  sql: 'INSERT INTO users (name, age) VALUES (:name, :age)',
  namedParams: {
    ':name': { type: 'Text', value: 'Jane Smith' },
    ':age': { type: 'Integer', value: 25 }
  },
});

// Query data
const queryResult = await query({
  connectionId,
  sql: 'SELECT * FROM users',
});
console.log(queryResult.rows);

// Sync changes with the remote database (if in replica mode)
await sync({ connectionId });

// Close the connection when done
await close({ connectionId });
```

## Features

- Local SQLite database access
- Remote SQLite database access via LibSQL's HTTP protocol
- Local-first with remote syncing capabilities
- Full SQL query support
- **Enhanced parameter handling** with support for both positional (`?`) and named (`:name`) parameters
- **Vector embeddings and AI support** - Native vector similarity search with indexing
- **6 vector types** - From high precision (FLOAT64) to ultra-compact (FLOAT1BIT)
- **Vector operations** - Cosine distance, L2 distance, and vector extraction
- **Vector indexing** - DiskANN algorithm for fast nearest neighbor queries
- Ergonomic parameter API - no need to specify types explicitly
- Parameterized queries for safe data handling
- Cross-platform support (Windows, macOS, Linux, Android, iOS)

## Parameter Handling

The plugin supports both positional and named parameters for maximum flexibility:

### Positional Parameters
```rust
let options = ExecuteOptions {
    connection_id: "your-connection-id".to_string(),
    sql: "INSERT INTO users (name, age) VALUES (?, ?)".to_string(),
    params: Some(vec![
        Value::Text("John Doe".to_string()),
        Value::Integer(30),
    ]),
    named_params: None,
};
```

### Named Parameters (Recommended)
```rust
let mut named_params = HashMap::new();
named_params.insert(":name".to_string(), Value::Text("John Doe".to_string()));
named_params.insert(":age".to_string(), Value::Integer(30));

let options = ExecuteOptions {
    connection_id: "your-connection-id".to_string(),
    sql: "INSERT INTO users (name, age) VALUES (:name, :age)".to_string(),
    params: None,
    named_params: Some(named_params),
};
```

Named parameters provide better readability, maintainability, and are less error-prone than positional parameters.

## Vector Embeddings & AI

This plugin provides full support for LibSQL's native vector similarity search capabilities, perfect for AI applications like RAG (Retrieval Augmented Generation), recommendation systems, and semantic search.

### Quick Vector Example

```javascript
// Create a vector-enabled database
const connectionId = await invoke('create_vector_demo');

// Perform similarity search
const results = await invoke('vector_top_k', {
  options: {
    connectionId: connectionId,
    indexName: 'movies_idx',
    queryVector: [0.1, 0.2, 0.3, 0.4], // Your embedding
    k: 10,
    vectorType: 'Float32'
  }
});
```

For comprehensive vector operations guide, see [Vector Embeddings Guide](examples/vector-embeddings-guide.md).

### Supported Vector Operations

- **6 Vector Types**: FLOAT64, FLOAT32, FLOAT16, FLOATB16, FLOAT8, FLOAT1BIT
- **Distance Functions**: Cosine distance, L2 (Euclidean) distance  
- **Vector Indexing**: DiskANN algorithm for fast approximate nearest neighbor search
- **Integration Ready**: Works seamlessly with OpenAI, Hugging Face, and other embedding providers

Based on [Turso's AI & Embeddings documentation](https://docs.turso.tech/features/ai-and-embeddings).

## Mobile Platform Implementation

The plugin provides **full vector operations support** on mobile platforms through Tauri's mobile plugin system. All vector operations (vector_top_k, distance calculations, indexing) work identically across desktop and mobile.

### Android Support

The plugin uses Kotlin for Android implementation with LibSQL Android SDK integration:

```gradle
// app/build.gradle
dependencies {
    implementation 'org.libsql:libsql-android:0.9.6'
}
```

**Mobile Vector Features:**
- ✅ All 6 vector types (FLOAT64, FLOAT32, FLOAT16, etc.)
- ✅ Vector similarity search with indexing  
- ✅ Distance functions (cosine, L2)
- ✅ Mobile-optimized storage options

### iOS Support

The plugin uses Swift for iOS implementation with LibSQL Swift SDK:

```swift
// Package.swift
dependencies: [
    .package(url: "https://github.com/tursodatabase/libsql-swift", from: "0.9.6")
]
```

### Mobile Vector Optimization

For mobile devices, consider using compressed vector types:

```rust
// Recommended for mobile apps
VectorType::Float16   // 50% storage reduction vs Float32
VectorType::Float8    // 75% storage reduction  
VectorType::Float1Bit // 96% storage reduction (binary embeddings)
```

**Mobile-Specific Guide:** See [Mobile Vector Operations Guide](examples/mobile-vector-guide.md)

## License

MIT