db/ourdb/MIGRATION.md

OurDB Migration Guide: V to Rust

This guide helps you migrate from the V implementation of OurDB to the new Rust implementation.

Overview

The Rust implementation of OurDB maintains the same core functionality and data format as the V implementation, allowing for a smooth transition. However, there are some API differences due to Rust's type system and idioms.

Key Differences

1. Configuration

V Implementation:

// Create a new OurDB instance
mut db := ourdb.new_db(path: '/path/to/db', incremental_mode: true)

Rust Implementation:

// Create a new OurDB instance
let config = OurDBConfig {
    path: PathBuf::from("/path/to/db"),
    incremental_mode: true,
    file_size: None,     // Use default (500MB)
    keysize: None,       // Use default (4 bytes)
};
let mut db = OurDB::new(config)?;

2. Setting Values

V Implementation:

// Set a value with auto-generated ID
id := db.set(data: 'Hello, World!'.bytes())!

// Set a value with explicit ID
db.set(id: 42, data: 'Hello, World!'.bytes())!

Rust Implementation:

// Set a value with auto-generated ID
let id = db.set(OurDBSetArgs { 
    id: None, 
    data: b"Hello, World!" 
})?;

// Set a value with explicit ID
db.set(OurDBSetArgs { 
    id: Some(42), 
    data: b"Hello, World!" 
})?;

3. Getting Values

V Implementation:

// Get a value
data := db.get(42)!

Rust Implementation:

// Get a value
let data = db.get(42)?;

4. Getting History

V Implementation:

// Get history (up to 5 versions)
history := db.get_history(42, 5)!

Rust Implementation:

// Get history (up to 5 versions)
let history = db.get_history(42, 5)?;

5. Deleting Values

V Implementation:

// Delete a value
db.delete(42)!

Rust Implementation:

// Delete a value
db.delete(42)?;

6. Error Handling

V Implementation:

// V uses the ! operator for error propagation
result := db.operation()!

Rust Implementation:

// Rust uses the ? operator for error propagation
let result = db.operation()?;

7. Closing the Database

V Implementation:

// Close the database
db.close()!

Rust Implementation:

// Close the database
db.close()?;

Data Migration

The Rust implementation uses the same file format as the V implementation, so your existing database files should be compatible. However, it's always recommended to back up your data before migrating.

To migrate an existing database:

1. Back up your existing database directory
2. Point the Rust implementation to the same directory
3. Test that all your data is accessible

Example:

// Open an existing database created with the V implementation
let config = OurDBConfig {
    path: PathBuf::from("/path/to/existing/db"),
    incremental_mode: true,  // Must match the original configuration
    file_size: None,
    keysize: None,
};
let mut db = OurDB::new(config)?;

// Verify data access
let data = db.get(some_known_id)?;
println!("Retrieved: {:?}", data);

Performance Considerations

The Rust implementation may have different performance characteristics compared to the V implementation. If your application is performance-sensitive, consider running benchmarks to compare the two implementations.

Additional Features in Rust Implementation

The Rust implementation includes some additional features not present in the V implementation:

1. More comprehensive error types
2. Better memory management
3. Improved thread safety
4. More extensive testing

Need Help?

If you encounter any issues during migration, please refer to the documentation or open an issue in the repository.