@page database Database Features

# Database Features

## Overview

The Quadrix database module provides SQLite-based persistence for dendritic structure data,
decoupled from the web interface for standalone use.

## Features

- **Standalone Operation**: Database functionality without web server dependencies
- **Schema Management**: Automatic schema creation and migration
- **Batch Operations**: Optimized bulk inserts for large datasets
- **Transaction Support**: ACID-compliant transactions
- **Foreign Key Constraints**: Referential integrity enforcement

## Build

```bash
# Build with database feature only
cargo build --features database

# Build database CLI tool
cargo build --bin database_cli --features database

# Build batch processor
cargo build --bin process_swc_directory --features database
```

## Usage

### Command-Line Interface

```bash
# Create database
cargo run --bin database_cli --features database -- create neurons.db

# View statistics
cargo run --bin database_cli --features database -- stats neurons.db

# Optimize database
cargo run --bin database_cli --features database -- vacuum neurons.db
```

### Programmatic Usage

```rust
use quadrix::database::Database;

// Create or open database
let db = Database::new("neurons.db")?;

// Execute queries
let conn = db.connection();
conn.execute("SELECT * FROM neurons", [])?;

// Use transactions for batch operations
let tx = conn.transaction()?;
// ... batch operations ...
tx.commit()?;
```

## Schema

The database includes the following tables:

- `neurons`: Neuron metadata
- `vertices`: 3D points with quadric data
- `edges`: Connections between vertices
- `persistent_quadrix`: Aggregate quadric data
- `dendritic_structures`: Structural metadata
- `quadric_matrices`: Matrix storage
- `analysis_results`: Analysis outputs
- `visualization_states`: UI state persistence
- `plot_interactions`: User interaction history

## Batch Processing

Process entire directories of SWC files:

```bash
cargo run --bin process_swc_directory --features database -- /path/to/swc/files [database.db]
```

Features:
- Automatic caching of processed files
- Incremental updates on subsequent runs
- Progress reporting
- Error handling with detailed logging

## Performance

- **In-Memory Mode**: Use `:memory:` for temporary databases
- **Batch Inserts**: 10-100x faster with transactions
- **Indexing**: Automatic indexes on foreign keys
- **VACUUM**: Reclaim space after deletions

## Dependencies

- `rusqlite`: SQLite database engine with bundled library
- `serde`: Serialization framework
- `serde_json`: JSON support for metadata
- `chrono`: Timestamp handling
- `uuid`: Unique identifiers

## Integration with Web

The web feature includes database functionality:

```toml
# Web includes database automatically
quadrix = { features = ["web"] }

# Or use database standalone
quadrix = { features = ["database"] }
```

## Examples

See `examples/database_operations.rs` for comprehensive usage examples.

## References

- Source: `src/database/mod.rs`
- CLI Tool: `src/bin/database_cli.rs`
- Batch Processor: `src/bin/process_swc_directory.rs`
- SWC Batch Module: `src/swc_batch.rs`
