sqlite-cr

SQLite with the cr-sqlite CRDT extension pre-loaded. Zero installation required!

✅ Fully tested - Comprehensive test suite with TDD methodology
✅ Fast & streaming - Direct output streaming, no buffering delays
✅ Multi-platform - macOS (arm64/x86_64) and Linux (x86_64/arm64)
✅ Easy updates - Simple version bump script included

🚀 Quick Start

Run directly from GitHub with a single command:

# Run sqlite-cr directly
nix run github:subtleGradient/sqlite-cr -- :memory: "SELECT hex(crsql_site_id())"

That's it! No clone, no install, just run.

Usage Examples

# Interactive session
nix run github:subtleGradient/sqlite-cr -- mydb.db

# Quick query
nix run github:subtleGradient/sqlite-cr -- :memory: "SELECT 1+1;"

# Create a CRDT-enabled table
nix run github:subtleGradient/sqlite-cr -- :memory: "
  CREATE TABLE items(id INTEGER PRIMARY KEY NOT NULL, name TEXT);
  SELECT crsql_as_crr('items');
  INSERT INTO items VALUES (1, 'Hello CRDT!');
  SELECT * FROM items;
"

# CSV output
nix run github:subtleGradient/sqlite-cr -- -csv :memory: "SELECT 'hello' as greeting, 42 as answer;"

What is cr-sqlite?

cr-sqlite adds CRDT (Conflict-free Replicated Data Type) support to SQLite, enabling:

Multi-writer replication
Automatic conflict resolution
Offline-first applications
Distributed SQLite databases

Installation Options

While you can run directly with nix run, you can also install it:

Install to User Profile

# From GitHub
nix profile install github:subtleGradient/sqlite-cr

# From local clone
nix profile install .

# Now use directly
sqlite-cr mydb.db

Build Locally

git clone https://github.com/subtleGradient/sqlite-cr
cd sqlite-cr
nix build
./result/bin/sqlite-cr :memory: "SELECT crsql_site_id();"

NixOS Configuration

{
  inputs.sqlite-cr.url = "github:subtleGradient/sqlite-cr";

  # In your system configuration
  environment.systemPackages = [
    inputs.sqlite-cr.packages.${pkgs.system}.default
  ];
}

Development

# Clone and enter dev shell
git clone https://github.com/subtleGradient/sqlite-cr
cd sqlite-cr
nix develop  # or use direnv

# Run tests
make test

# See all available tasks
make help

# Common development tasks
make build          # Build sqlite-cr
make test           # Run test suite  
make check          # Run flake checks
make dev            # Enter dev shell
make ci             # Simulate CI locally

How It Works

This flake:

Downloads pre-built cr-sqlite binaries from official releases
Verifies downloads with Nix-provided SHA256 hashes
Wraps SQLite with the extension pre-loaded
Provides a clean CLI interface
Works on macOS (arm64/x86_64) and Linux (x86_64/arm64)
Streams output directly without buffering for better performance
Surgically filters the harmless sqlite3_close() error on successful execution

Updating cr-sqlite Version

To update to a new cr-sqlite version:

nix develop -c ./update-version.sh 0.17.0  # ensures Bash ≥ 4 and nix tools

This script automatically fetches new hashes and runs tests.

CI/CD

This project includes comprehensive GitHub Actions workflows:

CI - Builds and tests on all platforms (Linux/macOS × x86_64/ARM64)
Monthly checks - Monitors for outdated dependencies and placeholder hashes
Releases - Automatically builds platform binaries for tagged releases

Error Handling

sqlite3_close() returns 5 Error

By default, sqlite-cr automatically filters the harmless sqlite3_close() returns 5 error that appears on successful execution. This error is related to cr-sqlite's internal state management and does not affect functionality or data integrity.

Behavior:

Success (exit code 0): The error line is filtered out automatically
Error (non-zero exit): All error messages are shown as-is for debugging
Opt-out: Set SQLITE_CR_SHOW_CLOSE5=1 to see the error even on success

# Normal usage - close5 error filtered
sqlite-cr :memory: "SELECT 1;"

# Show the close5 error for debugging
SQLITE_CR_SHOW_CLOSE5=1 sqlite-cr :memory: "SELECT 1;"

The filtering is surgical - only the exact error line is removed, preserving all other stderr output.

Platform Support

Platform	Architecture	Status
macOS	arm64 (Apple Silicon)	✅ Verified
macOS	x86_64 (Intel)	✅ Verified
Linux	x86_64	✅ Verified
Linux	arm64/aarch64	✅ Built (runtime unverified in CI)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Components:

sqlite-cr wrapper: MIT License (this project)
SQLite: Public domain
libcrsqlite binaries: Redistributed under MIT License from vlcn-io/cr-sqlite

Note: This project redistributes pre-built binaries from the cr-sqlite project. Please refer to the upstream project for their complete license terms.