Appendix II: Configuration Reference

Overview

This chapter provides comprehensive documentation for all configuration options in Vektagraf. Configuration controls database behavior, performance characteristics, security settings, and multi-tenancy features. Understanding these options is essential for optimizing Vektagraf for your specific deployment requirements.

Learning Objectives

Master all configuration options and their effects
Understand environment-specific configuration patterns
Learn configuration validation and error handling
Explore performance tuning through configuration
Understand multi-tenant configuration management

Prerequisites

Basic understanding of Vektagraf architecture
Familiarity with deployment modes (embedded vs hosted)
Knowledge of multi-tenancy concepts

Core Configuration

VektagrafConfig

The main configuration class controlling database behavior and performance.

Basic Configuration

const VektagrafConfig({
  int maxMemoryBytes = 256 * 1024 * 1024,    // 256MB
  int pageSize = 4096,                        // 4KB
  bool autoIndexing = true,
  int cacheSize = 1000,
  bool enableWAL = true,
  SyncMode syncMode = SyncMode.normal,
  int? machineId,
  MultiTenancyConfig? multiTenancy,
})

Configuration Parameters

maxMemoryBytes

Type: int
Default: 256 * 1024 * 1024 (256MB)
Range: 1MB - 64GB
Description: Maximum memory usage for database operations
Impact: Higher values improve performance but increase memory usage

// Low memory configuration (mobile/embedded)
final lowMemConfig = VektagrafConfig(
  maxMemoryBytes: 64 * 1024 * 1024, // 64MB
);

// High memory configuration (server)
final highMemConfig = VektagrafConfig(
  maxMemoryBytes: 2 * 1024 * 1024 * 1024, // 2GB
);

pageSize

Type: int
Default: 4096 (4KB)
Valid Values: 1024, 2048, 4096, 8192, 16384, 32768
Description: Storage page size in bytes
Impact: Larger pages improve sequential access, smaller pages reduce memory usage

// Small page size for random access patterns
final smallPageConfig = VektagrafConfig(
  pageSize: 1024, // 1KB pages
);

// Large page size for sequential access patterns
final largePageConfig = VektagrafConfig(
  pageSize: 32768, // 32KB pages
);

autoIndexing

Type: bool
Default: true
Description: Automatically create indexes for frequently queried fields
Impact: Improves query performance but increases storage overhead

// Disable auto-indexing for write-heavy workloads
final writeHeavyConfig = VektagrafConfig(
  autoIndexing: false,
);

cacheSize

Type: int
Default: 1000
Range: 100 - 1000000
Description: Number of objects to keep in memory cache
Impact: Higher values improve read performance but increase memory usage

// High-performance read configuration
final readOptimizedConfig = VektagrafConfig(
  cacheSize: 10000,
);

// Memory-constrained configuration
final memoryConstrainedConfig = VektagrafConfig(
  cacheSize: 100,
);

enableWAL

Type: bool
Default: true
Description: Enable Write-Ahead Logging for durability
Impact: Improves crash recovery but slightly reduces write performance

// Disable WAL for maximum write performance (less durable)
final performanceConfig = VektagrafConfig(
  enableWAL: false,
);

syncMode

Type: SyncMode
Default: SyncMode.normal
Values: off, normal, full
Description: Controls durability vs performance trade-off

enum SyncMode {
  off,     // No explicit sync (fastest, least durable)
  normal,  // Sync on transaction commit (balanced)
  full,    // Sync on every write (slowest, most durable)
}

// Maximum performance configuration
final fastConfig = VektagrafConfig(
  syncMode: SyncMode.off,
);

// Maximum durability configuration
final durableConfig = VektagrafConfig(
  syncMode: SyncMode.full,
);

machineId

Type: int?
Default: null (auto-detected)
Range: 0 - 1023 (10-bit value)
Description: Machine identifier for distributed ID generation
Impact: Required for distributed deployments to ensure unique IDs

// Explicit machine ID for distributed deployment
final distributedConfig = VektagrafConfig(
  machineId: 42,
);

// Auto-detection (recommended)
final autoConfig = VektagrafConfig(
  // machineId will be auto-detected from hostname/MAC address
);

Factory Constructors

embedded()

Optimized configuration for embedded deployments.

factory VektagrafConfig.embedded({
  int? maxMemoryBytes,
  bool? autoIndexing,
  MultiTenancyConfig? multiTenancy,
})

Default Values:

maxMemoryBytes: 128MB (reduced for embedded)
autoIndexing: true
syncMode: SyncMode.full (maximum durability)
cacheSize: 1000
enableWAL: true

Example:

final embeddedConfig = VektagrafConfig.embedded(
  maxMemoryBytes: 64 * 1024 * 1024, // 64MB for mobile
);

hosted()

Optimized configuration for hosted/server deployments.

factory VektagrafConfig.hosted({
  int? maxMemoryBytes,
  int? cacheSize,
  MultiTenancyConfig? multiTenancy,
})

Default Values:

maxMemoryBytes: 512MB (increased for server)
cacheSize: 5000 (increased for better performance)
syncMode: SyncMode.normal (balanced)
autoIndexing: true
enableWAL: true

Example:

final hostedConfig = VektagrafConfig.hosted(
  maxMemoryBytes: 1024 * 1024 * 1024, // 1GB
  cacheSize: 10000,
);

multiTenant()

Optimized configuration for multi-tenant hosted deployments.

factory VektagrafConfig.multiTenant({
  int? maxMemoryBytes,
  int? cacheSize,
  Map<String, TenantLimitTierConfig>? limitTiers,
  bool strictIsolation = true,
})

Default Values:

maxMemoryBytes: 1GB (increased for multi-tenancy)
cacheSize: 10000 (increased for multiple tenants)
strictIsolation: true (enforce tenant boundaries)
Multi-tenancy enabled with default tier configurations

Example:

final multiTenantConfig = VektagrafConfig.multiTenant(
  maxMemoryBytes: 2 * 1024 * 1024 * 1024, // 2GB
  limitTiers: {
    'premium': TenantLimitTierConfig(
      name: 'premium',
      rateLimit: RateLimitConfig(maxRequests: 5000),
      storageLimit: StorageLimitConfig(maxStorageBytes: 10 * 1024 * 1024 * 1024),
      requestLimit: RequestLimitConfig(dailyLimit: 1000000),
    ),
  },
);

Multi-Tenancy Configuration

MultiTenancyConfig

Configuration for multi-tenant database deployments.

class MultiTenancyConfig {
  final bool enabled;
  final bool strictIsolation;
  final Map<String, TenantLimitTierConfig> limitTiers;
  final String defaultTier;
  final bool autoCreateTenants;
}

Parameters

enabled

Type: bool
Default: false
Description: Enable multi-tenancy features
Impact: Enables tenant isolation and limit enforcement

strictIsolation

Type: bool
Default: true
Description: Enforce strict tenant data isolation
Impact: Prevents cross-tenant data access but may reduce performance

limitTiers

Type: Map<String, TenantLimitTierConfig>
Default: {}
Description: Custom tenant limit tier definitions
Impact: Defines resource limits for different tenant types

defaultTier

Type: String
Default: 'tier1'
Description: Default tier for new tenants
Impact: Determines initial limits for new tenants

autoCreateTenants

Type: bool
Default: false
Description: Automatically create tenant configurations
Impact: Simplifies tenant onboarding but may create security risks

Example:

final multiTenancyConfig = MultiTenancyConfig(
  enabled: true,
  strictIsolation: true,
  defaultTier: 'tier2',
  autoCreateTenants: false,
  limitTiers: {
    'startup': TenantLimitTierConfig(
      name: 'startup',
      rateLimit: RateLimitConfig(maxRequests: 500),
      storageLimit: StorageLimitConfig(maxStorageBytes: 1024 * 1024 * 1024),
      requestLimit: RequestLimitConfig(dailyLimit: 100000),
    ),
  },
);

TenantLimitTierConfig

Configuration for tenant resource limits and quotas.

class TenantLimitTierConfig {
  final String name;
  final RateLimitConfig rateLimit;
  final StorageLimitConfig storageLimit;
  final RequestLimitConfig requestLimit;
  final Map<String, dynamic> customSettings;
}

Complete Example

final enterpriseTier = TenantLimitTierConfig(
  name: 'enterprise',
  rateLimit: RateLimitConfig(
    maxRequests: 10000,
    timeWindow: Duration(minutes: 1),
    slidingWindow: true,
    burstAllowance: 1000,
    operationTypes: {'read', 'write', 'query', 'vector_search'},
  ),
  storageLimit: StorageLimitConfig(
    maxStorageBytes: 100 * 1024 * 1024 * 1024, // 100GB
    maxObjects: 1000000,
    maxObjectSize: 1024 * 1024 * 1024, // 1GB
    maxVectors: 500000,
    maxVectorDimensions: 4096,
    warningThreshold: 0.8,
    hardLimits: true,
  ),
  requestLimit: RequestLimitConfig(
    dailyLimit: 10000000,
    monthlyLimit: 100000000,
    concurrentLimit: 500,
    complexityLimit: 10000,
    maxResultSize: 1000000,
    allowedOperations: {
      'read', 'write', 'delete', 'query', 
      'vector_search', 'graph_traverse'
    },
    priority: RequestPriority.critical,
  ),
  customSettings: {
    'dedicatedSupport': true,
    'slaLevel': '99.9%',
    'backupRetention': 365, // days
    'auditRetention': 2555, // days (7 years)
  },
);

RateLimitConfig

Configuration for request rate limiting.

class RateLimitConfig {
  final int maxRequests;
  final Duration timeWindow;
  final bool slidingWindow;
  final int burstAllowance;
  final Set<String> operationTypes;
}

Parameters

maxRequests

Type: int
Description: Maximum requests allowed per time window
Range: 1 - 1000000

timeWindow

Type: Duration
Default: Duration(minutes: 1)
Description: Time window for rate limiting
Common Values: Duration(seconds: 1), Duration(minutes: 1), Duration(hours: 1)

slidingWindow

Type: bool
Default: true
Description: Use sliding window (true) vs fixed window (false)
Impact: Sliding windows provide smoother rate limiting

burstAllowance

Type: int
Default: 0
Description: Additional requests allowed in short bursts
Range: 0 - maxRequests

operationTypes

Type: Set<String>
Default: {'read', 'write', 'query', 'vector_search'}
Description: Operations subject to rate limiting
Valid Values: 'read', 'write', 'delete', 'query', 'vector_search', 'graph_traverse'

Examples:

// Conservative rate limiting
final conservativeRateLimit = RateLimitConfig(
  maxRequests: 100,
  timeWindow: Duration(minutes: 1),
  slidingWindow: true,
  burstAllowance: 10,
  operationTypes: {'read', 'write'},
);

// Aggressive rate limiting for high-traffic scenarios
final aggressiveRateLimit = RateLimitConfig(
  maxRequests: 10000,
  timeWindow: Duration(minutes: 1),
  slidingWindow: true,
  burstAllowance: 1000,
  operationTypes: {'read', 'write', 'query', 'vector_search', 'graph_traverse'},
);

// Per-second rate limiting
final perSecondRateLimit = RateLimitConfig(
  maxRequests: 100,
  timeWindow: Duration(seconds: 1),
  slidingWindow: true,
  burstAllowance: 20,
);

StorageLimitConfig

Configuration for storage quotas and limits.

class StorageLimitConfig {
  final int maxStorageBytes;
  final int? maxObjects;
  final int? maxObjectSize;
  final int? maxVectors;
  final int? maxVectorDimensions;
  final double warningThreshold;
  final bool hardLimits;
}

Parameters

maxStorageBytes

Type: int
Description: Maximum storage in bytes
Range: 1MB - unlimited
Required: Yes

maxObjects

Type: int?
Description: Maximum number of objects/documents
Range: 1 - unlimited
Default: null (unlimited)

maxObjectSize

Type: int?
Description: Maximum size per individual object in bytes
Range: 1KB - 1GB
Default: null (unlimited)

maxVectors

Type: int?
Description: Maximum number of vector embeddings
Range: 1 - unlimited
Default: null (unlimited)

maxVectorDimensions

Type: int?
Description: Maximum vector dimensions allowed
Range: 1 - 4096
Default: null (unlimited up to system maximum)

warningThreshold

Type: double
Default: 0.8
Range: 0.0 - 1.0
Description: Storage usage warning threshold (80% by default)

hardLimits

Type: bool
Default: true
Description: Enforce hard limits (reject) vs soft limits (warn)

Examples:

// Basic storage limits
final basicStorageLimit = StorageLimitConfig(
  maxStorageBytes: 1024 * 1024 * 1024, // 1GB
  maxObjects: 10000,
  maxObjectSize: 10 * 1024 * 1024, // 10MB
  warningThreshold: 0.8,
  hardLimits: true,
);

// Vector-focused storage limits
final vectorStorageLimit = StorageLimitConfig(
  maxStorageBytes: 10 * 1024 * 1024 * 1024, // 10GB
  maxVectors: 100000,
  maxVectorDimensions: 1536,
  maxObjectSize: 100 * 1024 * 1024, // 100MB
  warningThreshold: 0.85,
  hardLimits: true,
);

// Soft limits configuration
final softLimitsConfig = StorageLimitConfig(
  maxStorageBytes: 5 * 1024 * 1024 * 1024, // 5GB
  maxObjects: 50000,
  warningThreshold: 0.7,
  hardLimits: false, // Only warn, don't reject
);

RequestLimitConfig

Configuration for request quotas and priorities.

class RequestLimitConfig {
  final int? dailyLimit;
  final int? monthlyLimit;
  final int? concurrentLimit;
  final int? complexityLimit;
  final int? maxResultSize;
  final Set<String> allowedOperations;
  final RequestPriority priority;
}

Parameters

dailyLimit / monthlyLimit

Type: int?
Description: Daily/monthly request quotas
Default: null (unlimited)
Range: 1 - unlimited

concurrentLimit

Type: int?
Description: Maximum concurrent requests
Default: null (unlimited)
Range: 1 - 10000

complexityLimit

Type: int?
Description: Query complexity limit (for complex graph/vector queries)
Default: null (unlimited)
Range: 1 - 100000

maxResultSize

Type: int?
Description: Maximum number of results returned
Default: null (unlimited)
Range: 1 - 1000000

allowedOperations

Type: Set<String>
Default: {'read', 'write', 'delete', 'query', 'vector_search', 'graph_traverse'}
Description: Allowed operation types for tenant

priority

Type: RequestPriority
Default: RequestPriority.normal
Values: low, normal, high, critical
Description: Request processing priority level

Examples:

// Basic tier request limits
final basicRequestLimit = RequestLimitConfig(
  dailyLimit: 10000,
  monthlyLimit: 100000,
  concurrentLimit: 5,
  complexityLimit: 100,
  maxResultSize: 1000,
  allowedOperations: {'read', 'write', 'query'},
  priority: RequestPriority.low,
);

// Enterprise tier request limits
final enterpriseRequestLimit = RequestLimitConfig(
  dailyLimit: 10000000,
  monthlyLimit: 100000000,
  concurrentLimit: 500,
  complexityLimit: 10000,
  maxResultSize: 1000000,
  allowedOperations: {
    'read', 'write', 'delete', 'query', 
    'vector_search', 'graph_traverse'
  },
  priority: RequestPriority.critical,
);

// Read-only configuration
final readOnlyRequestLimit = RequestLimitConfig(
  dailyLimit: 100000,
  concurrentLimit: 20,
  allowedOperations: {'read', 'query', 'vector_search'},
  priority: RequestPriority.normal,
);

Client Configuration

VektagrafClientConfig

Configuration for hosted mode client connections.

class VektagrafClientConfig {
  String host;
  int port;
  bool useHttps;
  final String username;
  final String password;
  final Map<String, dynamic> metadata;
  final Duration timeout;
}

Parameters

host

Type: String
Default: 'localhost'
Description: Server hostname or IP address

port

Type: int
Default: 8080
Description: Server port number

useHttps

Type: bool
Default: false
Description: Use HTTPS/WSS for secure connections

username / password

Type: String
Description: Authentication credentials
Required: Yes for hosted mode

metadata

Type: Map<String, dynamic>
Default: {}
Description: Additional client metadata sent to server

timeout

Type: Duration
Default: Duration(seconds: 30)
Description: Request timeout duration

Examples:

// Local development configuration
final devClientConfig = VektagrafClientConfig(
  host: 'localhost',
  port: 8080,
  useHttps: false,
  username: 'dev_user',
  password: 'dev_password',
  timeout: Duration(seconds: 10),
);

// Production configuration
final prodClientConfig = VektagrafClientConfig(
  host: 'vektagraf.example.com',
  port: 443,
  useHttps: true,
  username: 'api_user',
  password: 'secure_api_key',
  metadata: {
    'clientVersion': '1.0.0',
    'environment': 'production',
    'region': 'us-west-2',
  },
  timeout: Duration(seconds: 60),
);

// High-performance configuration
final highPerfClientConfig = VektagrafClientConfig(
  host: 'high-perf.vektagraf.com',
  port: 8443,
  useHttps: true,
  username: 'perf_user',
  password: 'perf_key',
  timeout: Duration(seconds: 5), // Short timeout for high-performance
  metadata: {
    'connectionPool': 'high-performance',
    'keepAlive': true,
  },
);

Environment-Specific Configurations

Development Environment

final developmentConfig = VektagrafConfig(
  maxMemoryBytes: 128 * 1024 * 1024, // 128MB
  cacheSize: 500,
  syncMode: SyncMode.normal,
  autoIndexing: true,
  enableWAL: true,
);

Testing Environment

final testingConfig = VektagrafConfig(
  maxMemoryBytes: 64 * 1024 * 1024, // 64MB
  cacheSize: 100,
  syncMode: SyncMode.off, // Fast for tests
  autoIndexing: false, // Predictable behavior
  enableWAL: false, // Not needed for tests
);

Staging Environment

final stagingConfig = VektagrafConfig.hosted(
  maxMemoryBytes: 512 * 1024 * 1024, // 512MB
  cacheSize: 2000,
);

Production Environment

final productionConfig = VektagrafConfig.hosted(
  maxMemoryBytes: 2 * 1024 * 1024 * 1024, // 2GB
  cacheSize: 10000,
);

Multi-Tenant Production

final multiTenantProdConfig = VektagrafConfig.multiTenant(
  maxMemoryBytes: 4 * 1024 * 1024 * 1024, // 4GB
  cacheSize: 20000,
  strictIsolation: true,
  limitTiers: {
    'free': TenantLimitTierConfig(
      name: 'free',
      rateLimit: RateLimitConfig(maxRequests: 100),
      storageLimit: StorageLimitConfig(maxStorageBytes: 100 * 1024 * 1024),
      requestLimit: RequestLimitConfig(dailyLimit: 1000),
    ),
    'pro': TenantLimitTierConfig(
      name: 'pro',
      rateLimit: RateLimitConfig(maxRequests: 1000),
      storageLimit: StorageLimitConfig(maxStorageBytes: 10 * 1024 * 1024 * 1024),
      requestLimit: RequestLimitConfig(dailyLimit: 100000),
    ),
    'enterprise': TenantLimitTierConfig(
      name: 'enterprise',
      rateLimit: RateLimitConfig(maxRequests: 10000),
      storageLimit: StorageLimitConfig(maxStorageBytes: 100 * 1024 * 1024 * 1024),
      requestLimit: RequestLimitConfig(dailyLimit: 1000000),
    ),
  },
);

Configuration Validation

Validation Rules

Vektagraf validates configuration parameters to ensure system stability and performance.

Memory Validation

// Valid memory configurations
final validConfigs = [
  VektagrafConfig(maxMemoryBytes: 64 * 1024 * 1024),    // 64MB minimum
  VektagrafConfig(maxMemoryBytes: 64 * 1024 * 1024 * 1024), // 64GB maximum
];

// Invalid configurations (will throw exceptions)
try {
  final invalidConfig = VektagrafConfig(
    maxMemoryBytes: 32 * 1024 * 1024, // Below 64MB minimum
  );
} catch (e) {
  print('Configuration error: $e');
}

Page Size Validation

// Valid page sizes
final validPageSizes = [1024, 2048, 4096, 8192, 16384, 32768];

// Invalid page size (will throw exception)
try {
  final invalidConfig = VektagrafConfig(
    pageSize: 3000, // Not a power of 2
  );
} catch (e) {
  print('Invalid page size: $e');
}

Cache Size Validation

// Valid cache sizes
final validCacheConfigs = [
  VektagrafConfig(cacheSize: 100),     // Minimum
  VektagrafConfig(cacheSize: 1000000), // Maximum
];

// Invalid cache size
try {
  final invalidConfig = VektagrafConfig(
    cacheSize: 50, // Below minimum
  );
} catch (e) {
  print('Invalid cache size: $e');
}

Custom Validation

class ConfigValidator {
  static List<String> validateConfig(VektagrafConfig config) {
    final errors = <String>[];
    
    // Memory validation
    if (config.maxMemoryBytes < 64 * 1024 * 1024) {
      errors.add('maxMemoryBytes must be at least 64MB');
    }
    
    // Cache size validation
    if (config.cacheSize < 100) {
      errors.add('cacheSize must be at least 100');
    }
    
    // Page size validation
    if (!_isPowerOfTwo(config.pageSize)) {
      errors.add('pageSize must be a power of 2');
    }
    
    return errors;
  }
  
  static bool _isPowerOfTwo(int value) {
    return value > 0 && (value & (value - 1)) == 0;
  }
}

// Usage
final config = VektagrafConfig(maxMemoryBytes: 32 * 1024 * 1024);
final errors = ConfigValidator.validateConfig(config);
if (errors.isNotEmpty) {
  print('Configuration errors: ${errors.join(', ')}');
}

Configuration Loading and Management

File-Based Configuration

// config.json
{
  "maxMemoryBytes": 536870912,
  "pageSize": 4096,
  "autoIndexing": true,
  "cacheSize": 5000,
  "enableWAL": true,
  "syncMode": "normal",
  "multiTenancy": {
    "enabled": true,
    "strictIsolation": true,
    "defaultTier": "tier1",
    "limitTiers": {
      "premium": {
        "name": "premium",
        "rateLimit": {
          "maxRequests": 5000,
          "timeWindowSeconds": 60,
          "burstAllowance": 500
        },
        "storageLimit": {
          "maxStorageBytes": 10737418240,
          "maxObjects": 100000,
          "warningThreshold": 0.8
        },
        "requestLimit": {
          "dailyLimit": 1000000,
          "concurrentLimit": 100,
          "priority": "high"
        }
      }
    }
  }
}

// Loading configuration from file
class ConfigLoader {
  static Future<VektagrafConfig> loadFromFile(String filePath) async {
    final file = File(filePath);
    final jsonString = await file.readAsString();
    final json = jsonDecode(jsonString) as Map<String, dynamic>;
    
    return VektagrafConfig(
      maxMemoryBytes: json['maxMemoryBytes'] as int,
      pageSize: json['pageSize'] as int,
      autoIndexing: json['autoIndexing'] as bool,
      cacheSize: json['cacheSize'] as int,
      enableWAL: json['enableWAL'] as bool,
      syncMode: _parseSyncMode(json['syncMode'] as String),
      multiTenancy: json['multiTenancy'] != null 
        ? MultiTenancyConfig.fromJson(json['multiTenancy'] as Map<String, dynamic>)
        : null,
    );
  }
  
  static SyncMode _parseSyncMode(String mode) {
    switch (mode.toLowerCase()) {
      case 'off': return SyncMode.off;
      case 'normal': return SyncMode.normal;
      case 'full': return SyncMode.full;
      default: throw ArgumentError('Invalid sync mode: $mode');
    }
  }
}

// Usage
final config = await ConfigLoader.loadFromFile('config.json');

Environment Variable Configuration

class EnvironmentConfigLoader {
  static VektagrafConfig loadFromEnvironment() {
    return VektagrafConfig(
      maxMemoryBytes: _getEnvInt('VEKTAGRAF_MAX_MEMORY', 256 * 1024 * 1024),
      pageSize: _getEnvInt('VEKTAGRAF_PAGE_SIZE', 4096),
      autoIndexing: _getEnvBool('VEKTAGRAF_AUTO_INDEXING', true),
      cacheSize: _getEnvInt('VEKTAGRAF_CACHE_SIZE', 1000),
      enableWAL: _getEnvBool('VEKTAGRAF_ENABLE_WAL', true),
      syncMode: _getEnvSyncMode('VEKTAGRAF_SYNC_MODE', SyncMode.normal),
      machineId: _getEnvInt('VEKTAGRAF_MACHINE_ID', null),
    );
  }
  
  static int _getEnvInt(String key, int defaultValue) {
    final value = Platform.environment[key];
    return value != null ? int.parse(value) : defaultValue;
  }
  
  static bool _getEnvBool(String key, bool defaultValue) {
    final value = Platform.environment[key]?.toLowerCase();
    if (value == null) return defaultValue;
    return value == 'true' || value == '1' || value == 'yes';
  }
  
  static SyncMode _getEnvSyncMode(String key, SyncMode defaultValue) {
    final value = Platform.environment[key]?.toLowerCase();
    switch (value) {
      case 'off': return SyncMode.off;
      case 'normal': return SyncMode.normal;
      case 'full': return SyncMode.full;
      default: return defaultValue;
    }
  }
}

// Usage
final config = EnvironmentConfigLoader.loadFromEnvironment();

Configuration Builder Pattern

class VektagrafConfigBuilder {
  int _maxMemoryBytes = 256 * 1024 * 1024;
  int _pageSize = 4096;
  bool _autoIndexing = true;
  int _cacheSize = 1000;
  bool _enableWAL = true;
  SyncMode _syncMode = SyncMode.normal;
  int? _machineId;
  MultiTenancyConfig? _multiTenancy;
  
  VektagrafConfigBuilder maxMemory(int bytes) {
    _maxMemoryBytes = bytes;
    return this;
  }
  
  VektagrafConfigBuilder pageSize(int size) {
    _pageSize = size;
    return this;
  }
  
  VektagrafConfigBuilder autoIndexing(bool enabled) {
    _autoIndexing = enabled;
    return this;
  }
  
  VektagrafConfigBuilder cacheSize(int size) {
    _cacheSize = size;
    return this;
  }
  
  VektagrafConfigBuilder wal(bool enabled) {
    _enableWAL = enabled;
    return this;
  }
  
  VektagrafConfigBuilder syncMode(SyncMode mode) {
    _syncMode = mode;
    return this;
  }
  
  VektagrafConfigBuilder machineId(int id) {
    _machineId = id;
    return this;
  }
  
  VektagrafConfigBuilder multiTenancy(MultiTenancyConfig config) {
    _multiTenancy = config;
    return this;
  }
  
  VektagrafConfig build() {
    return VektagrafConfig(
      maxMemoryBytes: _maxMemoryBytes,
      pageSize: _pageSize,
      autoIndexing: _autoIndexing,
      cacheSize: _cacheSize,
      enableWAL: _enableWAL,
      syncMode: _syncMode,
      machineId: _machineId,
      multiTenancy: _multiTenancy,
    );
  }
}

// Usage
final config = VektagrafConfigBuilder()
  .maxMemory(512 * 1024 * 1024)
  .cacheSize(5000)
  .syncMode(SyncMode.full)
  .autoIndexing(true)
  .build();
```## P
erformance Tuning Through Configuration

### Memory Optimization

#### Low Memory Environments (Mobile/Embedded)

```dart
final mobileConfig = VektagrafConfig(
  maxMemoryBytes: 32 * 1024 * 1024,  // 32MB
  pageSize: 1024,                     // Smaller pages
  cacheSize: 100,                     // Minimal cache
  syncMode: SyncMode.normal,          // Balanced durability
  autoIndexing: false,                // Manual index management
);

High Memory Environments (Servers)

final serverConfig = VektagrafConfig(
  maxMemoryBytes: 8 * 1024 * 1024 * 1024, // 8GB
  pageSize: 32768,                         // Large pages
  cacheSize: 50000,                        // Large cache
  syncMode: SyncMode.normal,               // Balanced
  autoIndexing: true,                      // Automatic optimization
);

Write Performance Optimization

final writeOptimizedConfig = VektagrafConfig(
  maxMemoryBytes: 1024 * 1024 * 1024, // 1GB
  pageSize: 16384,                     // Large pages for sequential writes
  cacheSize: 2000,                     // Moderate cache
  syncMode: SyncMode.off,              // Maximum write speed
  enableWAL: false,                    // Disable WAL for speed
  autoIndexing: false,                 // Manual index management
);

Read Performance Optimization

final readOptimizedConfig = VektagrafConfig(
  maxMemoryBytes: 2 * 1024 * 1024 * 1024, // 2GB
  pageSize: 8192,                          // Balanced page size
  cacheSize: 20000,                        // Large cache
  syncMode: SyncMode.normal,               // Standard durability
  enableWAL: true,                         // Keep WAL for safety
  autoIndexing: true,                      // Automatic indexing
);

Vector Search Optimization

final vectorOptimizedConfig = VektagrafConfig(
  maxMemoryBytes: 4 * 1024 * 1024 * 1024, // 4GB for vector operations
  pageSize: 32768,                         // Large pages for vectors
  cacheSize: 10000,                        // Cache for frequent vectors
  syncMode: SyncMode.normal,
  autoIndexing: true,                      // Index vector fields
);

Configuration Migration and Upgrades

Version Compatibility

v1.0.x to v1.1.x Migration

class ConfigMigrator_1_0_to_1_1 {
  static VektagrafConfig migrate(Map<String, dynamic> oldConfig) {
    // Handle removed/renamed properties
    final maxMemory = oldConfig['maxMemoryMB'] != null 
      ? (oldConfig['maxMemoryMB'] as int) * 1024 * 1024
      : oldConfig['maxMemoryBytes'] as int? ?? 256 * 1024 * 1024;
    
    // Handle new properties with defaults
    final autoIndexing = oldConfig['autoIndexing'] as bool? ?? true;
    
    return VektagrafConfig(
      maxMemoryBytes: maxMemory,
      pageSize: oldConfig['pageSize'] as int? ?? 4096,
      autoIndexing: autoIndexing,
      cacheSize: oldConfig['cacheSize'] as int? ?? 1000,
      enableWAL: oldConfig['enableWAL'] as bool? ?? true,
      syncMode: _migrateSyncMode(oldConfig['durabilityMode'] as String?),
    );
  }
  
  static SyncMode _migrateSyncMode(String? oldMode) {
    switch (oldMode) {
      case 'fast': return SyncMode.off;
      case 'balanced': return SyncMode.normal;
      case 'safe': return SyncMode.full;
      default: return SyncMode.normal;
    }
  }
}

v1.1.x to v1.2.x Migration

class ConfigMigrator_1_1_to_1_2 {
  static VektagrafConfig migrate(VektagrafConfig oldConfig) {
    // Multi-tenancy was added in v1.2.x
    MultiTenancyConfig? multiTenancy;
    
    // If old config had tenant-related settings, migrate them
    if (oldConfig.metadata.containsKey('tenantSupport')) {
      multiTenancy = MultiTenancyConfig(
        enabled: oldConfig.metadata['tenantSupport'] as bool,
        strictIsolation: true, // New default
        defaultTier: 'tier1',  // New default
      );
    }
    
    return VektagrafConfig(
      maxMemoryBytes: oldConfig.maxMemoryBytes,
      pageSize: oldConfig.pageSize,
      autoIndexing: oldConfig.autoIndexing,
      cacheSize: oldConfig.cacheSize,
      enableWAL: oldConfig.enableWAL,
      syncMode: oldConfig.syncMode,
      machineId: oldConfig.machineId,
      multiTenancy: multiTenancy,
    );
  }
}

Automated Migration

class ConfigurationMigrator {
  static VektagrafConfig migrateToLatest(
    Map<String, dynamic> config,
    String fromVersion,
  ) {
    var currentConfig = config;
    
    // Apply migrations in sequence
    if (_isVersionBefore(fromVersion, '1.1.0')) {
      final migratedConfig = ConfigMigrator_1_0_to_1_1.migrate(currentConfig);
      currentConfig = _configToMap(migratedConfig);
    }
    
    if (_isVersionBefore(fromVersion, '1.2.0')) {
      final oldConfig = _mapToConfig(currentConfig);
      final migratedConfig = ConfigMigrator_1_1_to_1_2.migrate(oldConfig);
      return migratedConfig;
    }
    
    return _mapToConfig(currentConfig);
  }
  
  static bool _isVersionBefore(String version, String target) {
    // Simple version comparison (in production, use a proper version library)
    final versionParts = version.split('.').map(int.parse).toList();
    final targetParts = target.split('.').map(int.parse).toList();
    
    for (int i = 0; i < 3; i++) {
      if (versionParts[i] < targetParts[i]) return true;
      if (versionParts[i] > targetParts[i]) return false;
    }
    return false;
  }
  
  static Map<String, dynamic> _configToMap(VektagrafConfig config) {
    return {
      'maxMemoryBytes': config.maxMemoryBytes,
      'pageSize': config.pageSize,
      'autoIndexing': config.autoIndexing,
      'cacheSize': config.cacheSize,
      'enableWAL': config.enableWAL,
      'syncMode': config.syncMode.name,
      'machineId': config.machineId,
      'multiTenancy': config.multiTenancy?.toJson(),
    };
  }
  
  static VektagrafConfig _mapToConfig(Map<String, dynamic> map) {
    return VektagrafConfig(
      maxMemoryBytes: map['maxMemoryBytes'] as int,
      pageSize: map['pageSize'] as int,
      autoIndexing: map['autoIndexing'] as bool,
      cacheSize: map['cacheSize'] as int,
      enableWAL: map['enableWAL'] as bool,
      syncMode: SyncMode.values.firstWhere((m) => m.name == map['syncMode']),
      machineId: map['machineId'] as int?,
      multiTenancy: map['multiTenancy'] != null 
        ? MultiTenancyConfig.fromJson(map['multiTenancy'] as Map<String, dynamic>)
        : null,
    );
  }
}

Configuration Error Handling

Common Configuration Errors

Invalid Memory Configuration

try {
  final config = VektagrafConfig(
    maxMemoryBytes: 16 * 1024 * 1024, // 16MB - too small
  );
} on ArgumentError catch (e) {
  print('Memory configuration error: ${e.message}');
  // Use minimum valid configuration
  final fallbackConfig = VektagrafConfig(
    maxMemoryBytes: 64 * 1024 * 1024, // 64MB minimum
  );
}

Invalid Page Size

try {
  final config = VektagrafConfig(
    pageSize: 3000, // Not a power of 2
  );
} on ArgumentError catch (e) {
  print('Page size error: ${e.message}');
  // Use default page size
  final fallbackConfig = VektagrafConfig(
    pageSize: 4096, // Default
  );
}

Multi-Tenancy Configuration Errors

try {
  final config = VektagrafConfig.multiTenant(
    limitTiers: {
      'invalid': TenantLimitTierConfig(
        name: 'invalid',
        rateLimit: RateLimitConfig(maxRequests: -1), // Invalid
        storageLimit: StorageLimitConfig(maxStorageBytes: 0), // Invalid
        requestLimit: RequestLimitConfig(),
      ),
    },
  );
} on TenantConfigException catch (e) {
  print('Multi-tenancy configuration error: ${e.message}');
}

Configuration Validation Framework

abstract class ConfigurationValidator<T> {
  List<ValidationError> validate(T config);
}

class ValidationError {
  final String field;
  final String message;
  final ValidationSeverity severity;
  
  ValidationError(this.field, this.message, this.severity);
}

enum ValidationSeverity {
  error,   // Configuration is invalid
  warning, // Configuration may cause issues
  info,    // Configuration suggestion
}

class VektagrafConfigValidator implements ConfigurationValidator<VektagrafConfig> {
  @override
  List<ValidationError> validate(VektagrafConfig config) {
    final errors = <ValidationError>[];
    
    // Memory validation
    if (config.maxMemoryBytes < 64 * 1024 * 1024) {
      errors.add(ValidationError(
        'maxMemoryBytes',
        'Memory below 64MB may cause performance issues',
        ValidationSeverity.error,
      ));
    } else if (config.maxMemoryBytes < 128 * 1024 * 1024) {
      errors.add(ValidationError(
        'maxMemoryBytes',
        'Memory below 128MB may limit performance',
        ValidationSeverity.warning,
      ));
    }
    
    // Cache size validation
    if (config.cacheSize < 100) {
      errors.add(ValidationError(
        'cacheSize',
        'Cache size below 100 may impact performance',
        ValidationSeverity.warning,
      ));
    }
    
    // Page size validation
    if (config.pageSize > 32768) {
      errors.add(ValidationError(
        'pageSize',
        'Large page sizes may increase memory usage',
        ValidationSeverity.info,
      ));
    }
    
    // Sync mode validation
    if (config.syncMode == SyncMode.off && config.enableWAL) {
      errors.add(ValidationError(
        'syncMode',
        'WAL enabled with sync off may not provide expected durability',
        ValidationSeverity.warning,
      ));
    }
    
    return errors;
  }
}

// Usage
final validator = VektagrafConfigValidator();
final config = VektagrafConfig(maxMemoryBytes: 32 * 1024 * 1024);
final errors = validator.validate(config);

for (final error in errors) {
  print('${error.severity.name.toUpperCase()}: ${error.field} - ${error.message}');
}

Configuration Best Practices

Development Best Practices

Use Environment-Specific Configurations

VektagrafConfig getConfigForEnvironment(String environment) {
  switch (environment) {
    case 'development':
      return VektagrafConfig.embedded(maxMemoryBytes: 128 * 1024 * 1024);
    case 'testing':
      return VektagrafConfig(syncMode: SyncMode.off, enableWAL: false);
    case 'staging':
      return VektagrafConfig.hosted();
    case 'production':
      return VektagrafConfig.hosted(maxMemoryBytes: 2 * 1024 * 1024 * 1024);
    default:
      throw ArgumentError('Unknown environment: $environment');
  }
}

Validate Configurations Early

void validateConfigurationAtStartup(VektagrafConfig config) {
  final validator = VektagrafConfigValidator();
  final errors = validator.validate(config);

  final criticalErrors = errors.where((e) => e.severity == ValidationSeverity.error);
  if (criticalErrors.isNotEmpty) {
    throw ConfigurationException('Critical configuration errors: ${criticalErrors.map((e) => e.message).join(', ')}');
  }

  final warnings = errors.where((e) => e.severity == ValidationSeverity.warning);
  for (final warning in warnings) {
    print('Configuration warning: ${warning.message}');
  }
}

Use Configuration Builders for Complex Setups

VektagrafConfig buildProductionConfig() {
  return VektagrafConfigBuilder()
    .maxMemory(4 * 1024 * 1024 * 1024)  // 4GB
    .cacheSize(20000)
    .pageSize(16384)
    .syncMode(SyncMode.normal)
    .autoIndexing(true)
    .multiTenancy(MultiTenancyConfig(
      enabled: true,
      strictIsolation: true,
      defaultTier: 'tier1',
    ))
    .build();
}

Multi-Tenant Best Practices

Define Clear Tier Boundaries

final tierConfigs = {
  'free': TenantLimitTierConfig(
    name: 'free',
    rateLimit: RateLimitConfig(maxRequests: 100),
    storageLimit: StorageLimitConfig(maxStorageBytes: 100 * 1024 * 1024),
    requestLimit: RequestLimitConfig(dailyLimit: 1000),
  ),
  'basic': TenantLimitTierConfig(
    name: 'basic',
    rateLimit: RateLimitConfig(maxRequests: 500),
    storageLimit: StorageLimitConfig(maxStorageBytes: 1024 * 1024 * 1024),
    requestLimit: RequestLimitConfig(dailyLimit: 10000),
  ),
  'premium': TenantLimitTierConfig(
    name: 'premium',
    rateLimit: RateLimitConfig(maxRequests: 2000),
    storageLimit: StorageLimitConfig(maxStorageBytes: 10 * 1024 * 1024 * 1024),
    requestLimit: RequestLimitConfig(dailyLimit: 100000),
  ),
};

Monitor Resource Usage

class TenantResourceMonitor {
  final Map<String, TenantUsageStats> _usage = {};

  void recordUsage(String tenantId, String operation, int resourceUnits) {
    _usage.putIfAbsent(tenantId, () => TenantUsageStats(tenantId));
    _usage[tenantId]!.recordUsage(operation, resourceUnits);
  }

  List<String> getTenantsNearingLimits(double threshold) {
    return _usage.entries
      .where((entry) => entry.value.getUsageRatio() > threshold)
      .map((entry) => entry.key)
      .toList();
  }
}

Implement Graceful Degradation

class TenantLimitEnforcer {
  Future<T> executeWithLimits<T>(
    String tenantId,
    Future<T> Function() operation,
    {bool allowDegradedMode = true}
  ) async {
    try {
      return await operation();
    } on RateLimitExceededException {
      if (allowDegradedMode) {
        // Implement degraded functionality
        return await _executeDegradedOperation<T>();
      }
      rethrow;
    }
  }
}

Summary

This chapter covered comprehensive configuration options for Vektagraf:

Core Configuration: Memory, caching, durability, and performance settings
Multi-Tenancy Configuration: Tenant limits, rate limiting, and resource quotas
Client Configuration: Connection settings for hosted mode
Environment-Specific Configurations: Development, testing, staging, and production setups
Performance Tuning: Optimization strategies for different workloads
Configuration Migration: Version compatibility and upgrade procedures
Error Handling: Validation, error recovery, and best practices
Configuration Management: Loading, validation, and monitoring

Proper configuration is essential for optimal Vektagraf performance and reliability. Use the examples and patterns in this chapter to configure Vektagraf for your specific requirements.

Next Steps

Appendix III: Error Codes and Troubleshooting - Comprehensive error handling
Appendix IV: Migration and Upgrade Guides - Version compatibility and upgrades
Appendix I: Complete API Reference - Detailed API documentation
Part IV: Advanced Topics - Performance tuning and optimization
Part V: Enterprise Deployment - Production deployment patterns

Chapter 1: Introduction and Core Concepts

Chapter 2: Getting Started and Basic Usage

Chapter 3: Schema Design and Code Generation

Chapter 4: Database Operations and Transactions

Chapter 5: Vector Search and Similarity Operations

Chapter 6: Graph Operations and Relationship Modeling

Chapter 7: Query Optimization and Performance

Chapter 8: Security Architecture and Encryption

Chapter 9: Access Control and Authentication

Chapter 10: Privacy-Preserving Features and Compliance

Chapter 11: Blockchain Attributes and Data Integrity

Chapter 13: Multi-Tenant Architecture

Chapter 14: Transport Layer Integration

Chapter 15: Monitoring and Observability

Chapter 16: Performance Tuning and Optimization

Chapter 17: Job Queue System

Chapter 18: Automation System

Chapter 19: Production Deployment Patterns

Chapter 20: Scaling and High Availability

Chapter 21: DevOps and CI/CD Integration

Chapter 22: Troubleshooting and Maintenance

Chapter 23: Building Recommendation Systems

Chapter 24: Document and Content Management

Chapter 25: Social Networks and Graph Applications

Chapter 26: AI/ML Integration Patterns

Appendix I: Complete API Reference

Appendix II: Configuration Reference

Appendix III: Error Codes and Troubleshooting

Appendix IV: Migration and Upgrade Guides

Appendix II: Configuration Reference

Overview

Learning Objectives

Prerequisites

Core Configuration

VektagrafConfig

Basic Configuration

Configuration Parameters

maxMemoryBytes

pageSize

autoIndexing

cacheSize

enableWAL

syncMode

machineId

Factory Constructors

embedded()

hosted()

multiTenant()

Multi-Tenancy Configuration

MultiTenancyConfig

Parameters

enabled

strictIsolation

limitTiers

defaultTier

autoCreateTenants

TenantLimitTierConfig

Complete Example

RateLimitConfig

Parameters

maxRequests

timeWindow

slidingWindow

burstAllowance

operationTypes

StorageLimitConfig

Parameters

maxStorageBytes

maxObjects

maxObjectSize

maxVectors

maxVectorDimensions

warningThreshold

hardLimits

RequestLimitConfig

Parameters

dailyLimit / monthlyLimit

concurrentLimit

complexityLimit

maxResultSize