DocumentationFauxDB Documentation

FauxDB Troubleshooting

Connection & Authentication

Validate listener status, port exposure, and backend credentials.

Connection Diagnostics

Check connections and logs

# Check if ports are listening
ss -ltn | egrep '27017|3306'

# Check FauxDB service logs
journalctl -u fauxdb -n 100 | grep ERROR

# Verify service is running
systemctl status fauxdb
# or
docker ps | grep fauxdb

Fix Authentication Failures

  • Ensure PostgreSQL backend users exist and have privileges for the FauxDB database
  • Match FauxDB configuration auth_mechanisms with client expectations (e.g. SCRAM vs. plaintext)
  • Review credentials stored in /etc/fauxdb/fauxdb.toml or secrets manager

Protocol Translation Issues

Address MongoDB/MySQL compatibility errors and schema mismatches.

Inspect Backend Schema

Check PostgreSQL tables

SELECT schemaname, relname
  FROM pg_catalog.pg_tables
 WHERE schemaname IN ('public', 'fauxdb');

Common Compatibility Fixes

  • Enable convert_objectid_to_uuid for MongoDB drivers expecting ObjectId types
  • Set mysql_collation to match application expectations (e.g. utf8mb4_general_ci)
  • Map JSON attributes to PostgreSQL columns using FauxDB mapping rules

Performance Bottlenecks

Optimize caching, connection pools, and worker threads to prevent saturation.

MongoDB/SQL Query Latency

  • Enable query caching: set query_cache.enabled = true and tune query_cache.max_items
  • Create PostgreSQL indexes for frequent filters surfaced by EXPLAIN (ANALYZE)
  • Batch write-heavy workloads to reduce chattiness

High Memory or CPU Usage

  • Reduce pool_max_size or isolate noisy tenants into dedicated pools
  • Lower query_cache.max_bytes for memory pressure
  • Increase worker_threads when CPU is underutilized but worker queue grows

Debug Logging

Collect detailed traces for troubleshooting and support.

Enable Debug Logging

fauxdb.toml snippet

[logging]
level = "debug"
format = "json"
output = "file"
file_path = "/var/log/fauxdb/debug.log"

View Logs

Tail logs

# View logs in real-time
tail -f /var/log/fauxdb/debug.log

# Search for errors
grep ERROR /var/log/fauxdb/debug.log

# View last 100 lines
tail -n 100 /var/log/fauxdb/debug.log

Related Resources

PreviousProduction