mirror of
https://github.com/tursodatabase/limbo.git
synced 2025-08-04 01:58:16 +00:00
105 lines
No EOL
3.3 KiB
Markdown
105 lines
No EOL
3.3 KiB
Markdown
# SQLite3 Implementation for Limbo
|
|
|
|
This directory contains a Rust implementation of the SQLite3 C API. The implementation serves as a compatibility layer between SQLite's C API and Limbo's native Rust database implementation.
|
|
|
|
## Purpose
|
|
|
|
This implementation provides SQLite3 API compatibility for Limbo, allowing existing applications that use SQLite to work with Limbo 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 Limbo 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:
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
cd tests
|
|
make clean
|
|
make LIBS="-lsqlite3"
|
|
./sqlite3-tests
|
|
```
|
|
|
|
To run C tests against our implementation:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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. |