# excelstream Examples
Clean, organized examples demonstrating the excelstream library's capabilities.
## 📚 Quick Start Examples
### 1. basic_read.rs
Read a basic Excel file and display its contents.
```bash
cargo run --example basic_read
```
### 2. basic_write.rs
Write a basic Excel file with header and data rows.
cargo run --example basic_read
``````bash
cargo run --example basic_write
### 3. streaming_write.rs```
Write large Excel files (10,000 rows) efficiently.
```bash### 3. streaming_read.rs
cargo run --example streaming_writeRead large Excel files with streaming for memory optimization.
```
```bash
### 4. streaming_read.rs# Create large file first
Read large Excel files with minimal memory usage.cargo run --example streaming_write
```bash# Then read it
cargo run --example streaming_readcargo run --example streaming_read
``````
## 🚀 Advanced Features### 4. streaming_write.rs
Write large Excel files (10,000 rows) with streaming.
### 5. multi_sheet.rs
Create workbooks with multiple sheets.```bash
```bashcargo run --example streaming_write
cargo run --example multi_sheet```
```
## Performance Comparison Examples
### 6. cell_formatting.rs
Apply various cell styles and formatting options.### 5. three_writers_comparison.rs ⭐ **RECOMMENDED**
```bashComprehensive comparison of all 3 writer types with 1 million rows × 30 columns:
cargo run --example cell_formatting- `ExcelWriter.write_row()` - String-based writing (baseline)
```- `ExcelWriter.write_row_typed()` - Typed value writing (1-5% faster, Excel formulas work)
- `FastWorkbook` - Custom fast writer (25-44% faster for large datasets)
### 7. column_width_row_height.rs
Customize column widths and row heights.```bash
```bash# Run full comparison (1M rows, takes ~90 seconds)
cargo run --example column_width_row_heightcargo run --release --example three_writers_comparison
```
# Results show:
### 8. csv_to_excel.rs# - write_row(): 31.08s (32,177 rows/s)
Convert CSV files to Excel format with streaming.# - write_row_typed(): 30.63s (32,649 rows/s) +1% faster
```bash# - FastWorkbook: 24.80s (40,329 rows/s) +25% faster
cargo run --example csv_to_excel```
```
**This example demonstrates:**
## ⚡ Performance & Comparison- Real-world mixed data types (strings, integers, floats, booleans)
- Performance at scale (1M rows)
### 9. writers_comparison.rs ⭐ **RECOMMENDED**- Memory efficiency
Comprehensive comparison of 4 writer methods with 100K-1M rows:- Feature comparison matrix
**Writer Methods Compared:**### 6. write_row_comparison.rs
1. `write_row()` - String-based (baseline)Demonstrates the difference between string-based and typed value writing.
2. `write_row_typed()` - Typed values (Excel formulas work)Creates 3 Excel files to show:
3. `write_row_styled()` - With conditional formatting (FASTEST! +15%)- String-based: All values stored as text (formulas don't work)
4. `FastWorkbook` - Direct low-level API- Typed: Numbers stored as numbers (formulas work correctly)
- Financial report example with proper types
```bash
# Quick test (100K rows, ~7 seconds)```bash
cargo run --release --example writers_comparisoncargo run --example write_row_comparison
# Full test (1M rows, ~90 seconds) - Uncomment in code# Creates 3 files:
# Results with 1M rows × 30 columns:# - examples/string_output.xlsx
# - write_row(): 22.58s (44,293 rows/s)# - examples/typed_output.xlsx
# - write_row_typed(): 21.77s (45,931 rows/s) +4% faster# - examples/financial_report.xlsx
# - write_row_styled(): 19.51s (51,266 rows/s) +15% faster ⚡```
# - FastWorkbook: 20.62s (48,497 rows/s) +9% faster
```### 7. writer_comparison.rs
Compare standard ExcelWriter vs FastWorkbook performance with different dataset sizes.
**Key Insights:**
- `write_row_styled()` is fastest because it avoids intermediate string conversions```bash
- All methods use FastWorkbook internallycargo run --release --example writer_comparison
- Memory usage is constant (streaming architecture)```
## 💾 Memory Management### 8. fast_writer_test.rs
Fast writer performance benchmarks with 1 million rows.
### 10. memory_constrained_write.rs
Optimize for memory-limited environments (Kubernetes, containers).```bash
```bashcargo run --release --example fast_writer_test
# Simulate 512MB memory limit```
MEMORY_LIMIT_MB=512 cargo run --release --example memory_constrained_write
```## Advanced Features
### 11. auto_memory_config.rs### 9. csv_to_excel.rs
Automatic memory configuration based on environment.Convert CSV files to Excel format.
```bash
# With memory limit```bash
MEMORY_LIMIT_MB=256 cargo run --release --example auto_memory_configcargo run --example csv_to_excel
```
# Auto-detect
cargo run --release --example auto_memory_config### 10. multi_sheet.rs
```Create Excel workbooks with multiple sheets.
## 📊 Large Datasets```bash
cargo run --example multi_sheet
### 12. large_dataset_multi_sheet.rs```
Handle datasets exceeding Excel's 1,048,576 row/sheet limit.
Automatically splits data across multiple sheets.### 11. memory_constrained_write.rs
Test memory-constrained writing with different flush intervals.
```bashIdeal for Kubernetes pods with limited memory.
# Test with 10 million rows (takes ~3-5 minutes)
cargo run --release --example large_dataset_multi_sheet```bash
cargo run --release --example memory_constrained_write
# Results:```
# - 10 sheets created (1M rows each)
# - ~62,000 rows/sec sustained throughput### 12. auto_memory_config.rs
# - ~1.7 GB output fileDemonstrates automatic memory configuration based on environment variables.
# - Constant memory usage
``````bash
# Auto-detect memory limit
**Features:**MEMORY_LIMIT_MB=512 cargo run --release --example auto_memory_config
- Automatic sheet splitting at 1M rows
- Progress reporting every 100K rows# Default behavior (no limit)
- ZIP64 support for large files (>4GB)cargo run --release --example auto_memory_config
- Excel hard limit safe (1,048,576 rows/sheet)```
## 🐘 PostgreSQL Integration## PostgreSQL Integration Examples
Export data from PostgreSQL to Excel (basic synchronous version).
### 13. postgres_streaming.rs
Memory-efficient streaming export from PostgreSQL.```bash
```bash# Setup database first
# Setup database./setup_postgres_test.sh
./setup_postgres_test.sh# or
psql -U postgres -f setup_test_db.sql
# Run export
export DATABASE_URL="postgresql://rustfire:password@localhost/rustfire"# Run example
cargo run --example postgres_streaming --features postgresexport DATABASE_URL="postgresql://rustfire:password@localhost/rustfire"
```cargo run --example postgres_to_excel --features postgres
```
### 14. postgres_to_excel_advanced.rs
Async export with connection pooling and optimizations.### 14. postgres_streaming.rs
```bashMemory-efficient streaming export from PostgreSQL for very large datasets.
export DB_HOST=localhost
export DB_USER=rustfire```bash
export DB_PASSWORD=passwordexport DATABASE_URL="postgresql://rustfire:password@localhost/rustfire"
export DB_NAME=rustfirecargo run --example postgres_streaming --features postgres
```
cargo run --example postgres_to_excel_advanced --features postgres-async
```### 15. postgres_to_excel_advanced.rs
Advanced async PostgreSQL export with connection pooling and multiple sheets.
### 15. verify_postgres_export.rs
Quick verification tool for PostgreSQL exports.```bash
```bashexport DB_HOST=localhost
cargo run --example verify_postgres_exportexport DB_PORT=5432
```export DB_USER=rustfire
export DB_PASSWORD=password
## 📖 Recommended Learning Pathexport DB_NAME=rustfire
**For Beginners:**cargo run --example postgres_to_excel_advanced --features postgres-async
1. `basic_write.rs` → `basic_read.rs` - Understand the basics```
2. `streaming_write.rs` → `streaming_read.rs` - Larger datasets
3. `cell_formatting.rs` - Add stylingSee [POSTGRES_EXAMPLES.md](POSTGRES_EXAMPLES.md) for detailed PostgreSQL examples documentation.
4. `multi_sheet.rs` - Multiple sheets
## Performance Testing Examples
**For Performance:**
1. `writers_comparison.rs` - See all methods side-by-sideAll performance examples should be run in release mode for accurate results:
2. `large_dataset_multi_sheet.rs` - Push the limits
3. `memory_constrained_write.rs` - Production deployments```bash
# Full writer comparison (recommended)
**For Production:**cargo run --release --example three_writers_comparison
1. `postgres_streaming.rs` - Database integration
2. `memory_constrained_write.rs` - Container environments# Specific comparisons
3. `large_dataset_multi_sheet.rs` - Large exportscargo run --release --example write_row_comparison
cargo run --release --example writer_comparison
## 📝 Output Filescargo run --release --example fast_writer_test
Examples create output files in the `examples/` directory:# Memory testing
- `output.xlsx` - Basic write outputcargo run --release --example memory_constrained_write
- `large_output.xlsx` - Streaming write output```
- `comparison_*.xlsx` - Writer comparison outputs
- `test_10m_multi_sheet.xlsx` - Large dataset multi-sheet output## Output Files
- `postgres_export*.xlsx` - PostgreSQL export outputs
Examples will create output files in this directory:
## 🔧 Performance Tips- `output.xlsx` - From basic_write
- `large_output.xlsx` - Large file from streaming_write
**Always use `--release` mode for performance testing:**- `converted.xlsx` - Converted file from CSV
```bash- `multi_sheet.xlsx` - Multi-sheet file
cargo run --release --example writers_comparison- `string_output.xlsx` - String-based writing example
```- `typed_output.xlsx` - Typed value writing example
- `financial_report.xlsx` - Financial report with proper types
**Key Performance Factors:**- `comparison_*.xlsx` - Files from performance comparisons
- `write_row_styled()` is fastest (+15% over baseline)- `memory_test_*.xlsx` - Files from memory testing
- FastWorkbook provides true streaming (constant memory)- `postgres_export.xlsx` - PostgreSQL export results
- ZIP64 automatically enabled for large files
- Typical throughput: 40K-60K rows/sec with 30 columns## Sample Data
## 🗑️ Removed Examples- `data.csv` - Sample CSV file for conversion testing
- `sample.xlsx` - Sample Excel file (created by basic_write)
The following redundant examples were removed in cleanup:
- `write_row_comparison.rs` - Merged into `writers_comparison.rs`## Recommended Learning Path
- `debug_write_row_fast.rs` - Debug file, not needed
- `fast_writer_test.rs` - Covered by `writers_comparison.rs`1. Start with **basic_write.rs** and **basic_read.rs** to understand the basics
- `fast_writer_validation.rs` - Not necessary2. Try **streaming_write.rs** and **streaming_read.rs** for larger datasets
- `memory_usage_test.rs` - Covered by `memory_constrained_write.rs`3. Run **three_writers_comparison.rs** to see performance differences
- `performance_optimized.rs` - Covered by `writers_comparison.rs`4. Explore **write_row_comparison.rs** to understand typed vs string writing
- `performance_test_with_sizing.rs` - Covered by `writers_comparison.rs`5. Test **memory_constrained_write.rs** if deploying to Kubernetes
6. Check PostgreSQL examples if integrating with databases
All functionality from removed examples is preserved in the remaining, better-organized examples.