limbo/sqlite3/README.md

SQLite3 Implementation for Turso

This directory contains a Rust implementation of the SQLite3 C API. The implementation serves as a compatibility layer between SQLite's C API and Turso's native Rust database implementation.

Purpose

This implementation provides SQLite3 API compatibility for Turso, allowing existing applications that use SQLite to work with Turso without modification. The code:

1. Implements the SQLite3 C API functions in Rust
2. Translates between C and Rust data structures
3. Maps SQLite operations to equivalent Turso operations
4. Maintains API compatibility with SQLite version 3.42.0

Testing Strategy

We employ a dual-testing approach to ensure complete compatibility with SQLite:

Test Database Setup

Before running tests, you need to set up a test database:

# Create testing directory
mkdir -p ../../testing

# Create and initialize test database
sqlite3 ../../testing/testing.db ".databases"

This creates an empty SQLite database that both test suites will use.

1. C Test Suite (/tests)

• Written in C to test the exact same API that real applications use
• Can be compiled and run against both:
  • Official SQLite library (for verification)
  • Our Rust implementation (for validation)
• Serves as the "source of truth" for correct behavior

To run C tests against official SQLite:

cd tests
make clean
make LIBS="-lsqlite3"
./sqlite3-tests

To run C tests against our implementation:

cd tests
make clean
make LIBS="-L../target/debug -lsqlite3"
./sqlite3-tests

2. Rust Tests (src/lib.rs)

• Unit tests written in Rust
• Test the same functionality as C tests
• Provide better debugging capabilities
• Help with development and implementation

To run Rust tests:

cargo test

Why Two Test Suites?

1. Behavior Verification: C tests ensure our implementation matches SQLite's behavior exactly by running the same tests against both
2. Development Efficiency: Rust tests provide better debugging and development experience
3. Complete Coverage: Both test suites together provide comprehensive testing from both C and Rust perspectives

Common Test Issues

1. Missing Test Database

   • Error: SQLITE_CANTOPEN (14) in tests
   • Solution: Create test database as shown in "Test Database Setup"

2. Wrong Database Path

   • Tests expect database at ../../testing/testing.db
   • Verify path relative to where tests are run

3. Permission Issues

   • Ensure test database is readable/writable
   • Check directory permissions

Implementation Notes

• All public functions are marked with #[no_mangle] and follow SQLite's C API naming convention
• Uses unsafe blocks for C API compatibility
• Implements error handling similar to SQLite
• Maintains thread safety guarantees of SQLite

Contributing

When adding new features or fixing bugs:

1. Add C tests that can run against both implementations
2. Add corresponding Rust tests
3. Verify behavior matches SQLite by running C tests against both implementations
4. Ensure all existing tests pass in both suites
5. Make sure test database exists and is accessible

Status

This is an ongoing implementation. Some functions are marked with stub!() macro, indicating they're not yet implemented. Check individual function documentation for implementation status.