FAQ

Frequently Asked Questions (FAQ)

General Questions

What is Flow.db?

Flow.db is a modern, lightweight JSON document database designed for Node.js applications. It provides built-in features like schema validation, encryption, and automatic backups while maintaining a simple and intuitive API.

Why choose Flow.db over other databases?

• Simplicity: Easy to set up and use with minimal configuration
• Type Safety: Built with TypeScript for better development experience
• Performance: In-memory caching for fast data access
• Security: Built-in encryption for sensitive data
• Reliability: Automatic backup system
• Zero Dependencies: Minimal external dependencies

Is Flow.db suitable for production use?

Yes, Flow.db is designed for both development and production environments. However, consider these factors:

• Data size and scaling requirements
• Backup and recovery needs
• Security requirements
• Performance requirements

Technical Questions

How does the encryption work?

Flow.db uses AES encryption to secure your data. When encryption is enabled:

1. Data is encrypted before writing to disk
2. Data is automatically decrypted when read
3. Encryption key is required for all operations

const db = new Database({
  encryption: true,
  encryptionKey: process.env.ENCRYPTION_KEY
});

How can I implement custom validation?

You can combine schema validation with custom validation functions:

function validateUser(user: any): boolean {
  // Schema validation
  const isValidSchema = db.validateSchema(user, userSchema);
  if (!isValidSchema) return false;

  // Custom validation
  if (user.age < 18) return false;
  if (!isValidEmail(user.email)) return false;

  return true;
}

How do I handle concurrent operations?

Flow.db handles basic concurrency through file system locks. For advanced cases:

// Use transactions for atomic operations
await db.transaction(async () => {
  const user = await db.get('user:1');
  user.points += 10;
  await db.set('user:1', user);
});

Can I use Flow.db with JavaScript (non-TypeScript)?

Yes, Flow.db works with both JavaScript and TypeScript:

const { Database } = require('flow.db');

const db = new Database({
  path: '.flow'
});

Performance Questions

How can I optimize performance?

1. Use Caching:

const db = new Database({
  cacheEnabled: true,
  maxCacheSize: 1000
});

2. Batch Operations:

// Instead of multiple sets
users.forEach(user => db.set(`user:${user.id}`, user));

// Use a single operation
db.set('users', users);

3. Index Frequently Queried Fields:

db.createIndex('users', 'email');

What are the size limitations?

• Individual document: Up to 16MB
• Total database size: Limited by available disk space
• Cache size: Configurable through options

Error Handling

Common Error Messages

1. "Cannot initialize database"

   • Check directory permissions
   • Verify path exists
   • Ensure sufficient disk space

2. "Invalid encryption key"

   • Key length must be 32 characters
   • Key must be properly formatted
   • Key must be consistent across restarts

3. "Schema validation failed"

   • Check data structure matches schema
   • Verify required fields are present
   • Ensure data types are correct

How to handle errors properly?

try {
  await db.set('key', value);
} catch (error) {
  if (error.code === 'EACCES') {
    console.error('Permission denied');
  } else if (error.code === 'ENOSPC') {
    console.error('No space left');
  } else {
    console.error('Unknown error:', error);
  }
}

Backup and Recovery

How do automatic backups work?

Backups are created based on your configuration:

const db = new Database({
  autoBackup: true,
  backupInterval: 3600, // Every hour
  maxBackups: 5 // Keep last 5 backups
});

How to restore from backup?

const db = new Database();
await db.restore('backup-2024-03-01');

Where are backups stored?

By default, backups are stored in:

.flow/backups/
  ├── backup-2024-03-01/
  ├── backup-2024-03-02/
  └── backup-2024-03-03/

Migration and Updates

How to migrate from older versions?

1. Backup your data
2. Update Flow.db package
3. Run migration script if provided
4. Test functionality
5. Update application code if needed

How to upgrade encryption keys?

async function reEncrypt(newKey: string) {
  const data = await db.export();
  
  const newDb = new Database({
    encryption: true,
    encryptionKey: newKey
  });
  
  await newDb.import(data);
}

Contributing

How can I contribute to Flow.db?

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Where can I report bugs?

• Use GitHub Issues
• Provide reproduction steps
• Include error messages
• Share relevant code snippets

How can I request new features?

• Open a GitHub Discussion
• Describe your use case
• Provide example code
• Explain benefits