Skip to main content

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

  1. 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');
  }
}

  2. 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}');
  }
}

  3. 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

  1. 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),
  ),
};

  2. 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();
  }
}

  3. 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

  • Chapter 25: Error Codes and Troubleshooting - Comprehensive error handling
  • Chapter 26: Migration and Upgrade Guides - Version compatibility and upgrades
  • Chapter 23: Complete API Reference - Detailed API documentation
  • Part IV: Advanced Topics - Performance tuning and optimization
  • Part V: Enterprise Deployment - Production deployment patterns
Back to top