Laravel Couchdb Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require an3/laravel-couchdb
   

   Publish the config file:

   php artisan vendor:publish --provider="An3\LaravelCouchdb\CouchdbServiceProvider"
   

2. Configuration Edit .env with CouchDB connection details:

   COUCHDB_CONNECTION=default
   COUCHDB_HOST=127.0.0.1
   COUCHDB_PORT=5984
   COUCHDB_USERNAME=admin
   COUCHDB_PASSWORD=password
   

3. First Model Extend An3\LaravelCouchdb\Eloquent\Model:

   use An3\LaravelCouchdb\Eloquent\Model;
   
   class User extends Model
   {
       protected $connection = 'default';
       protected $database = 'my_app_db';
       protected $primaryKey = '_id';
   }
   

4. First Query

   $users = User::all(); // Returns Collection
   $user = User::find('user123');
   

First Use Case: CRUD Operations

// Create
$user = User::create([
    'name' => 'John Doe',
    'email' => 'john@example.com'
]);

// Read
$users = User::where('email', 'like', '%@example.com')->get();

// Update
$user->update(['name' => 'Updated Name']);

// Delete
$user->delete();

Implementation Patterns

Query Builder Integration

• Basic Queries

  User::where('name', 'John')
      ->orderBy('created_at', 'desc')
      ->limit(10)
      ->get();
  

• Complex Conditions

  User::where(function($query) {
      $query->where('age', '>', 25)
            ->orWhere('status', 'active');
  })->get();
  

• Joins (via _include) CouchDB lacks traditional joins, but you can use _include for document references:

  User::with('_posts')->find('user123');
  

Model Events

Leverage Eloquent events for side effects:

User::created(function($user) {
    // Log or notify
});

User::updated(function($user) {
    // Sync external systems
});

Migrations & Schema

Define schema in up():

Schema::create('users', function($collection) {
    $collection->string('_id', 36)->primary();
    $collection->string('name');
    $collection->string('email')->unique();
    $collection->timestamps();
});

Run migrations:

php artisan migrate

Pagination

$users = User::paginate(15); // Uses CouchDB's `_changes` feed

Transactions

Use beginTransaction for atomic operations (CouchDB supports MangoIndex transactions):

DB::beginTransaction();
try {
    User::create([...]);
    Profile::create([...]);
    DB::commit();
} catch (\Exception $e) {
    DB::rollBack();
}

Gotchas and Tips

Pitfalls

1. No Traditional Joins

   • CouchDB lacks SQL-style joins. Use _include or denormalize data.
   • Example: Store user_id in posts and fetch users separately.

2. Primary Key Conflicts

   • CouchDB auto-generates _id if not provided. Override incrementing:

     public $incrementing = false;
     

3. Case Sensitivity

   • CouchDB queries are case-sensitive by default. Use ilike for case-insensitive searches:

     User::where('name', 'ilike', '%john%')->get();
     

4. Bulk Operations

   • Avoid bulk inserts in loops. Use bulkInsert:

     User::bulkInsert([['name' => 'A'], ['name' => 'B']]);
     

Debugging

• Enable Query Logging Add to config/couchdb.php:

  'log' => env('COUCHDB_LOG', true),
  

• Check Raw Queries Use toCouchQuery() to inspect generated queries:

  $query = User::where('active', true)->toCouchQuery();
  

• Common Errors

  • 404 Not Found: Verify database config and permissions.
  • 401 Unauthorized: Check username/password in .env.
  • 400 Bad Request: Validate JSON payloads for create/update.

Extension Points

1. Custom Query Macros Add reusable query logic:

   User::addGlobalScope('active', function($builder) {
       $builder->where('active', true);
   });
   

2. Observers Sync data to other systems:

   class UserObserver {
       public function saved(User $user) {
           // Webhook or cache update
       }
   }
   

   Register in AppServiceProvider:

   User::observe(UserObserver::class);
   

3. Custom Accessors/Mutators Transform data on-the-fly:

   public function getFullNameAttribute() {
       return "{$this->first_name} {$this->last_name}";
   }
   

Performance Tips

• Indexing Define Mango indexes for frequent queries:

  Schema::createIndex('users', 'name', 'text');
  

• Bulk Fetching Use _all_docs with include_docs=true for large datasets:

  User::allDocs(['include_docs' => true]);
  

• Caching Cache frequent queries with remember:

  $users = User::where('role', 'admin')->remember(60)->get();