Merge pull request #15 from couchbase-examples/chore/streamline-dependencies

chore: Remove SQLite and streamline dependencies

Author: teetangh

.github/workflows/ci.yml

@@ -38,6 +38,9 @@ jobs:
           fi
           echo "Couchbase configuration validated successfully"
 
+      - name: Setup Couchbase indexes
+        run: RAILS_ENV=test bundle exec rake couchbase:setup_indexes
+
       - name: Run integration tests
         run: bundle exec rspec spec/requests/api/v1
 

Gemfile

@@ -5,24 +5,9 @@ ruby '3.4.1'
 # Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
 gem 'rails', '~> 7.1.3', '>= 7.1.3.2'
 
-# The original asset pipeline for Rails [https://github.com/rails/sprockets-rails]
-gem 'sprockets-rails'
-
-# Use sqlite3 as the database for Active Record
-gem 'sqlite3', '~> 1.4'
-
 # Use the Puma web server [https://github.com/puma/puma]
 gem 'puma', '>= 5.0'
 
-# Use JavaScript with ESM import maps [https://github.com/rails/importmap-rails]
-gem 'importmap-rails'
-
-# Hotwire's SPA-like page accelerator [https://turbo.hotwired.dev]
-gem 'turbo-rails'
-
-# Hotwire's modest JavaScript framework [https://stimulus.hotwired.dev]
-gem 'stimulus-rails'
-
 # Build JSON APIs with ease [https://github.com/rails/jbuilder]
 gem 'jbuilder'
 
@@ -72,7 +57,5 @@ group :development do
 end
 
 group :test do
-  # Use system testing [https://guides.rubyonrails.org/testing.html#system-testing]
-  gem 'capybara'
-  gem 'selenium-webdriver'
+  # API-only testing with RSpec (no system/browser testing needed)
 end

README.md

@@ -91,6 +91,91 @@ production:
 
 > Note: The connection string expects the `couchbases://` or `couchbase://` part.
 
+## Couchbase Index Management
+
+This application requires specific N1QL indexes on the `travel-sample` bucket to function correctly. These indexes optimize the SQL++ queries used by the application for filtering and joining documents.
+
+### Automatic Index Setup
+
+Indexes are automatically created when you:
+
+- Run `bin/setup` for local development setup
+- Run tests in CI/CD (GitHub Actions automatically creates indexes before running tests)
+
+The application uses idempotent index creation (using `CREATE INDEX IF NOT EXISTS`), so it's safe to run the setup multiple times.
+
+### Required Indexes
+
+The application requires the following indexes on the `travel-sample` bucket:
+
+1. **`idx_type`** - General index on the `type` field for all document queries
+2. **`idx_type_country`** - Index for airline queries filtered by country (`Airline.list_by_country_or_all`)
+3. **`idx_type_destinationairport`** - Index for route queries by destination airport (`Airline.to_airport`)
+4. **`idx_type_sourceairport_stops`** - Index for route queries by source airport and stops (`Route.direct_connections`)
+5. **`idx_type_airlineid`** - Index for airline queries by airline ID (used in joins with routes)
+
+### Manual Index Management
+
+You can manually manage indexes using the following Rake tasks:
+
+#### Create All Required Indexes
+
+```sh
+bundle exec rake couchbase:setup_indexes
+```
+
+This command creates all required indexes on the `travel-sample` bucket. It's idempotent and safe to run multiple times.
+
+#### List All Indexes
+
+```sh
+bundle exec rake couchbase:list_indexes
+```
+
+This command lists all indexes currently present in the `travel-sample` bucket, including their state, type, and indexed fields.
+
+#### Drop Application Indexes
+
+```sh
+bundle exec rake couchbase:drop_indexes
+```
+
+This command drops all application-managed indexes. It requires confirmation before executing. For automated scripts, you can force the operation:
+
+```sh
+FORCE_DROP=true bundle exec rake couchbase:drop_indexes
+```
+
+> **Warning**: Use with caution! Dropping indexes will cause queries to fail until indexes are recreated.
+
+### Troubleshooting Index Issues
+
+If you encounter index-related errors:
+
+1. **Verify indexes exist**:
+   ```sh
+   bundle exec rake couchbase:list_indexes
+   ```
+
+2. **Check index state**: Indexes should be in "online" state. If they're "building" or "pending", wait for them to complete.
+
+3. **Recreate indexes**:
+   ```sh
+   bundle exec rake couchbase:drop_indexes
+   bundle exec rake couchbase:setup_indexes
+   ```
+
+4. **Check permissions**: Ensure your Couchbase user has "Query Manage Index" permission to create and drop indexes.
+
+### Index Creation in CI/CD
+
+The GitHub Actions workflow automatically creates indexes before running tests. If index creation fails in CI:
+
+1. Check the "Setup Couchbase indexes" step in the GitHub Actions log
+2. Verify that `DB_CONN_STR`, `DB_USERNAME`, and `DB_PASSWORD` secrets/variables are correctly set
+3. Ensure the Couchbase user has "Query Manage Index" permission
+4. Check that the Couchbase cluster is accessible from GitHub Actions runners
+
 ## Running The Application
 
 ### Directly on machine

app/channels/application_cable/channel.rb

@@ -29,6 +29,6 @@ class Airline < CouchbaseOrm::Base
   }
 
   n1ql :to_airport, query_fn: proc { |bucket, values, options|
-    cluster.query("SELECT raw META(air).id FROM (SELECT DISTINCT META(airline).id AS airlineId FROM `#{bucket.name}` AS route JOIN `#{bucket.name}` AS airline ON route.airlineid = META(airline).id WHERE route.destinationairport = #{quote(values[0])}) AS subquery JOIN `#{bucket.name}` AS air ON META(air).id = subquery.airlineId LIMIT #{values[1]} OFFSET #{values[2]}", options)
+    cluster.query("SELECT raw META(air).id FROM (SELECT DISTINCT META(airline).id AS airlineId FROM `#{bucket.name}` AS route JOIN `#{bucket.name}` AS airline ON route.airlineid = META(airline).id AND airline.type = 'airline' WHERE route.type = 'route' AND route.destinationairport = #{quote(values[0])} ORDER BY META(airline).id) AS subquery JOIN `#{bucket.name}` AS air ON META(air).id = subquery.airlineId AND air.type = 'airline' LIMIT #{values[1]} OFFSET #{values[2]}", options)
   }
 end