CLI Configuration

Learn how to configure the Query-2jz CLI for your specific needs and environments.

Configuration Files

Query-2jz CLI supports multiple configuration file formats and locations.

Configuration File Locations

bash

# Configuration file search order:
1. ./query-2jz.config.js (default)
2. ./query-2jz.config.json
3. ./package.json (query-2jz field)

# Use specific config file
npx query-2jz dev --config ./custom-config.js
npx query-2jz dev -c ./custom-config.js

The CLI automatically creates query-2jz.config.js when you run npx query-2jz init.

Environment-Specific Configs

# Environment-specific configuration files:
./query-2jz.config.development.js
./query-2jz.config.staging.js
./query-2jz.config.production.js

# Use environment-specific config
npx query-2jz dev --config ./query-2jz.config.development.js
npx query-2jz dev --config ./query-2jz.config.production.js

Note: Environment-specific configs are planned for future releases.

Configuration Format

Learn the structure and options available in Query-2jz CLI configuration files.

Configuration Structure

Complete configuration file structure

Basic Configuration (Generated by CLI)

// query-2jz.config.js (generated by npx query-2jz init)
module.exports = {
  database: {
    type: 'sqlite',
    connection: './database.sqlite'
  },
  cache: {
    type: 'memory',
    ttl: 300
  },
  realtime: {
    enabled: true,
    transport: 'websocket'
  },
  edge: {
    enabled: false
  },
  models: [
    {
      name: 'User',
      fields: {
        id: { type: 'id' },
        name: { type: 'string', required: true },
        email: { type: 'string', required: true, unique: true },
        createdAt: { type: 'date' },
        updatedAt: { type: 'date' }
      },
      indexes: ['email']
    }
  ]
};

This is the default configuration created by npx query-2jz init. You can modify it to suit your needs.

Advanced Configuration

// query-2jz.config.js
module.exports = {
  // Database configuration
  database: {
    type: 'postgresql',
    connection: process.env.DATABASE_URL,
    pool: {
      min: 2,
      max: 20,
      idleTimeoutMillis: 30000,
      acquireTimeoutMillis: 60000,
      createTimeoutMillis: 30000,
      destroyTimeoutMillis: 5000,
      reapIntervalMillis: 1000,
      createRetryIntervalMillis: 200
    },
    ssl: {
      rejectUnauthorized: false
    },
    migrations: {
      directory: './migrations',
      tableName: 'query-2jz_migrations'
    }
  },

  // Cache configuration
  cache: {
    type: 'redis',
    connection: process.env.REDIS_URL,
    ttl: 3600,
    keyPrefix: 'query-2jz:',
    retryDelayOnFailover: 100,
    maxRetriesPerRequest: 3
  },

  // Security configuration
  security: {
    auth: {
      enabled: true,
      secret: process.env.JWT_SECRET,
      expiresIn: '24h',
      refreshTokenExpiresIn: '7d'
    },
    rateLimit: {
      enabled: true,
      windowMs: 900000, // 15 minutes
      max: 100, // limit each IP to 100 requests per windowMs
      skipSuccessfulRequests: false
    },
    cors: {
      origin: process.env.ALLOWED_ORIGINS?.split(','),
      credentials: true,
      methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
      allowedHeaders: ['Content-Type', 'Authorization']
    }
  },

  // Performance configuration
  performance: {
    queryOptimization: {
      enabled: true,
      batchSize: 100,
      maxDepth: 10
    },
    compression: {
      enabled: true,
      threshold: 1024,
      level: 6
    },
    monitoring: {
      enabled: true,
      metrics: ['cpu', 'memory', 'requests', 'response_time'],
      alerts: {
        cpu_usage: { threshold: 80, duration: '5m' },
        memory_usage: { threshold: 85, duration: '5m' },
        response_time: { threshold: 1000, duration: '2m' }
      }
    }
  }
};

Environment Variables

Configure Query-2jz CLI using environment variables for different environments.

Database Environment Variables

# Database configuration
DATABASE_URL=postgresql://user:password@localhost:5432/query-2jz
DATABASE_TYPE=postgresql
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=query-2jz
DATABASE_USER=user
DATABASE_PASSWORD=password
DATABASE_SSL=false

# Connection pool settings
DATABASE_POOL_MIN=2
DATABASE_POOL_MAX=20
DATABASE_POOL_IDLE_TIMEOUT=30000

Cache Environment Variables

# Redis configuration
REDIS_URL=redis://localhost:6379
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
REDIS_TTL=3600
REDIS_KEY_PREFIX=query-2jz:

Server Environment Variables

# Server configuration
PORT=3000
HOST=localhost
NODE_ENV=development
LOG_LEVEL=info
ALLOWED_ORIGINS=http://localhost:3000,https://example.com

# Security
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=24h
JWT_REFRESH_EXPIRES_IN=7d

# Rate limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=100

CLI-Specific Configuration

Configure CLI-specific options and behaviors.

CLI Configuration Options

// query-2jz.config.js
module.exports = {
  // CLI-specific configuration
  cli: {
    // Default command options
    defaults: {
      dev: {
        port: 3000,
        host: 'localhost',
        debug: false
      },
      build: {
        optimize: true,
        minify: true
      },
      test: {
        coverage: false,
        watch: false
      }
    },

    // Command aliases
    aliases: {
      'dev': 'development',
      'prod': 'production',
      'db': 'database'
    },

    // Custom commands
    commands: {
      'seed': {
        description: 'Seed the database with sample data',
        action: './scripts/seed.js'
      },
      'migrate': {
        description: 'Run database migrations',
        action: './scripts/migrate.js'
      }
    },

    // Output configuration
    output: {
      colors: true,
      timestamp: true,
      level: 'info'
    },

    // Backup configuration
    backup: {
      defaultPath: './backups',
      compression: true,
      encryption: false,
      retention: {
        daily: 7,
        weekly: 4,
        monthly: 12
      }
    },

    // Export configuration
    export: {
      defaultFormat: 'json',
      defaultPath: './exports',
      compression: false
    }
  }
};

Configuration Validation

Validate your configuration files and troubleshoot common issues.

Configuration Validation Commands

# Validate configuration file
query-2jz config validate

# Validate specific config file
query-2jz config validate --config ./custom-config.json

# Validate with verbose output
query-2jz config validate --verbose

# Check configuration syntax
query-2jz config check

# Show current configuration
query-2jz config show

# Show configuration for specific environment
query-2jz config show --env production

# Test database connection
query-2jz config test-db

# Test cache connection
query-2jz config test-cache

Common Configuration Issues

# Issue: Database connection failed
# Solution: Check DATABASE_URL format
DATABASE_URL=postgresql://user:password@host:port/database

# Issue: Redis connection failed
# Solution: Check REDIS_URL format
REDIS_URL=redis://user:password@host:port/database

# Issue: Port already in use
# Solution: Change port or kill existing process
PORT=3001

# Issue: CORS errors
# Solution: Configure allowed origins
ALLOWED_ORIGINS=http://localhost:3000,https://example.com

# Issue: JWT secret not set
# Solution: Set JWT_SECRET environment variable
JWT_SECRET=your-secret-key-here

Configuration Examples

Example configurations for different use cases and environments.

Development Configuration

// query-2jz.config.development.js
module.exports = {
  database: {
    type: 'sqlite',
    connection: './dev-database.sqlite'
  },
  cache: {
    type: 'memory',
    ttl: 300
  },
  server: {
    port: 3000,
    host: 'localhost'
  },
  logging: {
    level: 'debug',
    format: 'pretty'
  },
  security: {
    auth: {
      enabled: false
    },
    rateLimit: {
      enabled: false
    }
  }
};

Production Configuration

// query-2jz.config.production.js
module.exports = {
  database: {
    type: 'postgresql',
    connection: process.env.DATABASE_URL,
    pool: {
      min: 5,
      max: 50,
      idleTimeoutMillis: 30000
    },
    ssl: {
      rejectUnauthorized: false
    }
  },
  cache: {
    type: 'redis',
    connection: process.env.REDIS_URL,
    ttl: 3600
  },
  server: {
    port: process.env.PORT || 3000,
    host: '0.0.0.0'
  },
  logging: {
    level: 'info',
    format: 'json'
  },
  security: {
    auth: {
      enabled: true,
      secret: process.env.JWT_SECRET
    },
    rateLimit: {
      enabled: true,
      windowMs: 900000,
      max: 1000
    }
  },
  performance: {
    monitoring: {
      enabled: true,
      metrics: ['cpu', 'memory', 'requests']
    }
  }
};

Testing Configuration

// query-2jz.config.test.js
module.exports = {
  database: {
    type: 'sqlite',
    connection: ':memory:'
  },
  cache: {
    type: 'memory',
    ttl: 60
  },
  server: {
    port: 0 // Random port
  },
  logging: {
    level: 'error',
    format: 'json'
  },
  security: {
    auth: {
      enabled: false
    },
    rateLimit: {
      enabled: false
    }
  }
};

Best Practices

Do

• Use environment variables for sensitive data
• Create environment-specific config files
• Validate configuration before deployment
• Use version control for configuration files
• Document custom configuration options
• Use meaningful configuration file names
• Test configuration in development first

Don't

• Hardcode sensitive information
• Use production config in development
• Ignore configuration validation errors
• Skip environment-specific configurations
• Use default passwords in production
• Ignore security configuration
• Skip testing configuration changes