Pomm Cli Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require conserto/pomm-cli:^4.0
   

   Ensure pomm-project/pomm is also installed (core dependency). This version now includes Symfony 8 compatibility.

2. First Command Run the basic Pomm CLI to verify installation:

   php artisan pomm:cli
   

   This initializes an interactive Pomm shell with updated Symfony 8 integration.

3. Quick Use Case Connect to a PostgreSQL server via CLI:

   php artisan pomm:cli --server=postgresql://user:pass@localhost:5432/dbname
   

   Then use Pomm’s shell commands (e.g., describe, execute) to interact with the database.

Where to Look First

• Documentation: Check the Pomm Project docs for Pomm-specific syntax.
• Artisan Commands: Run php artisan to list available pomm:cli options.
• Interactive Shell: Use php artisan pomm:cli --help for CLI-specific flags.
• Symfony 8 Compatibility: Verify compatibility with Symfony 8 applications by checking for updated dependency constraints in composer.json.

Implementation Patterns

Workflow Integration

1. Database Migration Scripts Use the CLI to automate schema checks or data validation before migrations:

   php artisan pomm:cli --server=postgresql://... --execute="SELECT * FROM migrations WHERE applied = false;"
   

2. Testing Environments Spin up disposable Pomm connections for tests (ensure Symfony 8 components are compatible):

   // In a test case
   $this->artisan('pomm:cli', [
       '--server' => 'postgresql://test:test@localhost:5432/test_db',
       '--execute' => 'SELECT 1;'
   ]);
   

3. Debugging Queries Pipe query results to a file for analysis:

   php artisan pomm:cli --server=... --execute="SELECT * FROM large_table;" --output=query_results.json
   

Common Patterns

• Dynamic Server Connections: Store connection strings in .env and reference them via --server=$DB_CONNECTION.
• Scripting: Chain commands using shell pipes or scripts:

  php artisan pomm:cli --server=... --execute="SELECT id FROM users;" | xargs -I{} php artisan pomm:cli --execute="DELETE FROM users WHERE id={};"
  

• Custom Commands: Extend the CLI by creating custom Artisan commands that leverage PommCliServiceProvider (ensure compatibility with Symfony 8 components).

Gotchas and Tips

Pitfalls

1. Connection Timeouts

   • Issue: Long-running queries may time out in the CLI.
   • Fix: Use --timeout=300 to increase the timeout (default: 30s).

2. Output Formatting

   • Issue: Large result sets may truncate or overflow.
   • Fix: Use --format=json for machine-readable output or --limit=100 to cap results.

3. Shell Escaping

   • Issue: Special characters in queries (e.g., ' or ;) may break the CLI.
   • Fix: Escape queries or use --file=query.sql to load from a file.

4. Symfony 8 Dependency Conflicts

   • Issue: Potential conflicts with Symfony 8 components or dependencies.
   • Fix: Run composer why-not symfony/... to check for conflicts and update composer.json constraints accordingly.

Debugging Tips

• Verbose Mode: Enable with --verbose to see raw Pomm logs.
• Dry Runs: Use --dry-run to simulate queries without execution.
• Error Handling: Wrap CLI calls in try-catch blocks for programmatic use:

  try {
      $this->artisan('pomm:cli', ['--execute' => 'INVALID_QUERY;']);
  } catch (\Exception $e) {
      // Handle error (e.g., log or notify)
  }
  

Extension Points

1. Custom Commands Register new CLI commands by extending PommCliServiceProvider:

   // app/Providers/PommCliServiceProvider.php
   public function register()
   {
       $this->commands([
           \App\Console\Commands\CustomPommCommand::class,
       ]);
   }
   

   Ensure custom commands are compatible with Symfony 8 components.

2. Query Templates Store reusable queries in resources/pomm/ and reference them via --file=path/to/query.sql.

3. Environment Variables Dynamically load server configs from .env:

   php artisan pomm:cli --server=${DB_DSN} --execute="${QUERY}"
   

Config Quirks

• Default Server: Set a default connection in config/pomm.php:

  'default' => [
      'server' => env('DB_DSN', 'postgresql://default:user@localhost'),
  ],
  

• Authentication: For password prompts, use --interactive or configure ~/.pommrc for credentials.
• Symfony 8 Configuration: Ensure config/pomm.php aligns with Symfony 8’s dependency injection and configuration standards.