Frequently Asked Questions

Frequently Asked Questions #

General Questions #

What is IceFireDB? #

IceFireDB is a decentralized database infrastructure that combines Redis compatibility with advanced distributed systems capabilities. It supports multiple storage backends, P2P networking, and various consistency models for both web2 and web3 applications.

How does IceFireDB differ from Redis? #

While IceFireDB is fully compatible with Redis protocol, it offers several advanced features:

  • Multiple storage backends (LevelDB, BadgerDB, IPFS, CRDT, etc.)
  • Decentralized P2P networking
  • Pluggable storage architecture
  • Cross-region data synchronization
  • Web3 integration capabilities

Is IceFireDB production ready? #

Yes, IceFireDB is production ready for many use cases:

  • ✅ LevelDB and BadgerDB drivers are stable and production-ready
  • ✅ Redis protocol compatibility is complete
  • 🟡 IPFS and CRDT drivers are in beta
  • 🚧 Advanced web3 features are in development

What license does IceFireDB use? #

IceFireDB is open source and released under the Apache License 2.0.

Installation & Setup #

How do I install IceFireDB? #

You can install IceFireDB in several ways:

From source:

git clone https://github.com/IceFireDB/IceFireDB.git
cd IceFireDB
make build

Pre-built binaries: Download from GitHub Releases

What are the system requirements? #

Minimum:

  • 1GB RAM
  • 2CPU cores
  • 10GB disk space
  • Linux/macOS/Windows (WSL)

Recommended for production:

  • 4GB+ RAM
  • 4+ CPU cores
  • SSD storage
  • 50GB+ disk space
  • Linux

How do I configure IceFireDB? #

Create a config.yaml file:

network:
  port: 11001
  
storage:
  driver: "leveldb"
  data_dir: "./data"

log:
  level: "info"

Start with: ./icefiredb -c config.yaml

Storage & Performance #

Which storage driver should I use? #

Use CaseRecommended Driver
General purposeLevelDB
Write-intensiveBadgerDB
Decentralized storageIPFS
Conflict-free replicationCRDT
Immutable logsIPFS-LOG
Cloud integrationOSS
Tiered storageHybridDB

What performance can I expect? #

LevelDB Driver:

  • SET: 250,000+ ops/sec
  • GET: 2,000,000+ ops/sec
  • Latency: <2ms P99

BadgerDB Driver:

  • SET: 300,000+ ops/sec
  • GET: 1,800,000+ ops/sec
  • Latency: <3ms P99

IPFS Driver:

  • SET: 15,000-25,000 ops/sec
  • GET: 40,000-60,000 ops/sec
  • Latency: 5-50ms P99

How do I optimize performance? #

  1. Choose the right storage driver for your workload
  2. Allocate sufficient memory for caching
  3. Use SSD storage for disk-based drivers
  4. Enable compression for large values
  5. Tune network settings for distributed deployments
  6. Use pipelining for bulk operations

How much memory does IceFireDB need? #

Memory requirements depend on:

  • Storage driver selection
  • Cache size configuration
  • Workload characteristics
  • Data size and access patterns

Minimum: 1GB Recommended: 4GB+ Production: 8GB+

Distributed Features #

How does P2P networking work? #

IceFireDB uses libp2p for decentralized networking:

  • Nodes automatically discover each other
  • Data syncs across connected nodes
  • Supports NAT traversal
  • Works across different networks

What consistency models are supported? #

  • Strong consistency: RAFT consensus within availability zones
  • Eventual consistency: CRDT-based conflict resolution
  • Configurable consistency: Per-operation consistency levels

How do I set up a cluster? #

  1. Configure each node:
p2p:
  enable: true
  discovery_id: "my_cluster"
  listen_address: "/ip4/0.0.0.0/tcp/4001"
  1. Connect nodes:
p2p:
  bootstrap_peers:
    - "/ip4/node1-ip/tcp/4001/p2p/QmPeer1"
    - "/ip4/node2-ip/tcp/4001/p2p/QmPeer2"
  1. Verify connectivity:
P2P.PEERS

How does data replication work? #

Data replication depends on the storage driver:

  • LevelDB/BadgerDB: Single-node only
  • IPFS: Full mesh replication
  • CRDT: Automatic conflict resolution
  • RAFT: Strong consistency within groups

Operations & Maintenance #

How do I backup IceFireDB? #

For disk-based drivers:

# Stop IceFireDB
./icefiredb --stop

# Backup data directory
tar czf backup-$(date +%Y%m%d).tar.gz ./data/

# Restart IceFireDB
./icefiredb --start

For cloud drivers: Use native cloud backup tools

For decentralized drivers: Data is automatically replicated

How do I monitor IceFireDB? #

Built-in monitoring:

# Basic info
INFO

# Memory usage  
INFO memory

# Statistics
INFO stats

# Replication status
INFO replication

# Slow queries
SLOWLOG GET 10

External monitoring:

  • Prometheus metrics endpoint
  • Health check endpoints
  • Log aggregation
  • Performance monitoring tools

How do I upgrade IceFireDB? #

  1. Backup your data
  2. Stop the running instance
  3. Install the new version
  4. Verify configuration compatibility
  5. Start the new version
  6. Monitor for issues

How do I troubleshoot issues? #

Check logs:

tail -f icefiredb.log

Debug commands:

# Server info
INFO

# Connection info
CLIENT LIST

# Memory info  
MEMORY STATS

# Storage health
STORAGE.HEALTH

Common issues:

  • Port conflicts: Change network.port
  • Permission errors: Check file permissions
  • Memory issues: Adjust performance.max_memory
  • Network issues: Check firewall settings

Security #

Is IceFireDB secure? #

IceFireDB provides several security features:

  • TLS/SSL encryption for network traffic
  • Authentication support
  • IP whitelisting
  • Storage encryption (some drivers)
  • Secure P2P communications

How do I enable authentication? #

security:
  authentication:
    enable: true
    password: "your-secret-password"

Clients must authenticate:

redis-cli -h localhost -p 11001 -a your-secret-password

How do I enable TLS? #

security:
  tls:
    enable: true
    cert_file: "/path/to/cert.pem"
    key_file: "/path/to/key.pem"
    ca_file: "/path/to/ca.pem"

How do I restrict access? #

IP whitelisting:

ip_white_list:
  enable: true
  list:
    - "192.168.1.0/24"
    - "10.0.0.1"
    - "localhost"

Development #

How do I contribute to IceFireDB? #

  1. Fork the repository on GitHub
  2. Create a feature branch
  3. Make your changes
  4. Write tests
  5. Submit a pull request
  6. Address review comments

See CONTRIBUTING.md for details.

How do I create a custom storage driver? #

  1. Implement the driver interface:
type MyDriver struct{}

func (d MyDriver) Open(path string, cfg *config.Config) (driver.IDB, error) {
    // implementation
}
  1. Register your driver:
func init() {
    driver.Register(MyDriver{})
}
  1. Use your driver:
storage:
  driver: "mydriver"

What APIs are available? #

IceFireDB supports:

  • Redis RESP protocol - Full Redis compatibility
  • HTTP API - RESTful interface
  • gRPC API - High-performance RPC
  • Custom extensions - IceFireDB-specific commands

Web3 Integration #

How does IceFireDB support web3? #

IceFireDB provides several web3 features:

  • IPFS integration for decentralized storage
  • CRDT for conflict-free data sync
  • P2P automatic networking
  • Blockchain integration capabilities
  • Immutable data logging

Can I use IceFireDB with blockchain? #

Yes, IceFireDB can integrate with blockchain systems:

  • Store blockchain data in IceFireDB
  • Use IceFireDB as off-chain storage
  • Implement hybrid on-chain/off-chain architectures
  • Support decentralized applications (dApps)

How does IPFS integration work? #

IceFireDB can use IPFS as a storage backend:

  • Data stored on IPFS network
  • Local caching for performance
  • Content-addressable storage
  • Automatic data deduplication

IPLD and Data Structures #

Would you be able to write IPLD Schemas and specs for the data structures? #

Our current database storage engine implementation is divided into two categories:

  1. Instruction-based synchronization: Built on RESP instructions and SQL statements, providing immutable, append-only operation logs with decentralized instruction broadcasting and playback for data synchronization and consistency.

  2. IPFS-based KV storage: Implementing KV storage engine based on IPFS, encoding rich NoSQL data structures through KV-value coding, enabling complete database data growth on IPFS without relying solely on ipfs-log functionality.

We primarily use ipfs-log, an immutable conflict-free replicated data model for distributed systems. Based on ipfs-log, we’ve abstracted a KV engine that serves as one of IceFireDB’s storage drivers. Other projects can build upon this KV engine for their own readers/writers.

IceFireDB abstracts a data coding layer on the KV engine that supports complex data structures like hashes and lists beyond basic KV operations. While we currently implement IPFS KV storage, we’re working towards complete database data growth on IPFS and are exploring IPLD designs for NoSQL and SQL data relationships.

Database Operation #

How does the DB run? #

IceFireDB operates in server mode, running on servers and supporting:

  • Redis RESP protocol - Full Redis compatibility
  • MySQL communication protocol - SQL database access
  • Multiple client languages - Golang, JavaScript, PHP, etc.

Database Architecture

We also support framework integration for direct embedding into application code through projects like:

Server mode advantages:

  • Standard data protocols (RESP, MySQL) minimize application changes
  • Abstracts complexity of underlying IPFS, libp2p, ipfs-log, and CRDT

Data Mutability #

How do you address mutability of data? #

IceFireDB provides two implementation models for data variability:

1. Instruction Broadcast Model (ipfs-log based):

  • Immutable operation-based conflict-free replication using ipfs-log, CRDT, and libp2p pubsub
  • Encapsulates various data structures (event, kv) on ipfs-log
  • Implements multi-node database instruction broadcasting
  • Abstract variable KV engine on BadgerDB/LevelDB foundation
  • Nodes broadcast write instructions network-wide
  • Each node’s IceFireDB driver executes broadcast instructions for eventual consistency

Instruction Broadcast Model

2. Full Storage Model (IPFS based):

  • Complete data growth on IPFS
  • IPFS driver encodes upper-level commands into unified KV data structure
  • Stores and changes values with new CIDs linked to keys
  • Building towards multi-node key broadcast network and data synchronization

Full Storage Model

Programming Languages #

What program languages are you targeting? #

Primary Implementation: Golang

Client Support: All languages with Redis and MySQL clients:

  • JavaScript/Node.js
  • Python
  • Java
  • Ruby
  • PHP
  • Rust
  • And many more through standard Redis RESP and MySQL protocols

Troubleshooting #

IceFireDB won’t start #

Common causes:

  • Port already in use
  • Invalid configuration
  • Permission issues
  • Missing dependencies

Solutions:

  • Check port availability: netstat -tlnp | grep 11001
  • Validate config: ./icefiredb --check-config
  • Check permissions: ls -la ./data/
  • Review logs: tail -f icefiredb.log

High memory usage #

Solutions:

  • Reduce cache size
  • Enable key eviction
  • Monitor memory usage patterns
  • Upgrade to more memory

Configuration:

performance:
  max_memory: 4294967296  # 4GB
  max_memory_policy: "volatile-lru"

Slow performance #

Diagnosis:

  • Check system resources
  • Monitor network latency
  • Review storage performance
  • Analyze workload patterns

Solutions:

  • Choose faster storage driver
  • Increase cache size
  • Optimize configuration
  • Use pipelining for bulk operations

Connection issues #

Check:

  • Firewall settings
  • Network connectivity
  • Port availability
  • Authentication configuration

Test connectivity:

telnet localhost 11001
nc -zv localhost 11001

Community & Support #

Where can I get help? #

Community resources:

How do I report bugs? #

Create an issue on GitHub with:

  1. IceFireDB version
  2. Configuration details
  3. Steps to reproduce
  4. Error messages/logs
  5. Expected vs actual behavior

Where can I suggest features? #

Use GitHub Discussions to suggest new features or improvements.

Migration #

How do I migrate from Redis? #

  1. Install IceFireDB
  2. Configure IceFireDB with same port as Redis
  3. Stop Redis
  4. Start IceFireDB
  5. Verify data accessibility
  6. Update clients if needed

How do I migrate between storage drivers? #

  1. Backup current data
  2. Export data from current driver
  3. Import data to new driver
  4. Update configuration
  5. Verify data integrity

Can I use Redis tools with IceFireDB? #

Yes, most Redis tools work with IceFireDB:

  • redis-cli
  • redis-benchmark
  • Redis desktop managers
  • Redis client libraries

Advanced Topics #

How does IceFireDB handle large datasets? #

IceFireDB supports large datasets through:

  • Efficient storage engines
  • Memory management
  • Data compression
  • Tiered storage options
  • Distributed architecture

What monitoring tools are available? #

Built-in:

  • INFO command
  • SLOWLOG
  • STATS

External:

  • Prometheus metrics
  • Grafana dashboards
  • APM tools
  • Log aggregators

How do I tune for specific workloads? #

Read-heavy:

  • Larger cache size
  • Faster storage drivers
  • Read replicas

Write-heavy:

  • Write-optimized drivers (BadgerDB)
  • Batch operations
  • Async replication

Mixed workload:

  • Balanced configuration
  • Monitoring and adjustment
  • Hybrid approaches

Still have questions? #

If you didn’t find answers to your questions:

  1. Check the documentation
  2. Search GitHub Issues
  3. Ask in GitHub Discussions