Parameterize N1QL queries with positional parameters

[pimpin]

Summary

Replace string-interpolated values with positional parameter placeholders ($1, $2, ...) across all N1QL query paths. This makes query strings stable regardless of parameter values, enabling Couchbase prepared-statement caching.

Depends on: #33 (Fix N1QL injection in nested Hash)

Changes (6 commits)

1. Add serialize_for_binding/bind helpers and parameterize query_helper — Building blocks: type conversion for binding and $N placeholder generation. All build_match* methods accept optional params: keyword.
2. Parameterize N1QL module queries — build_where and run_query use positional parameters; debug log switches to block form with params.
3. Parameterize Relation queries — to_n1ql_with_params, build_where_with_params, build_update_with_params, build_query_options. All query paths (execute, query, first, last, update_all) use params.
4. Parameterize has_many through queries — build_index_n1ql uses $1/$2 for type and foreign key.
5. Pass arrays as single positional parameter — IN $1 instead of IN [$1, $2, ...] for stable query strings regardless of array length.
6. Support ActiveSupport::TimeWithZone — acts_like?(:time) duck-typing in serialize_for_binding.

Releasability

Queries are parameterized but adhoc remains at SDK default (true = no prepared-statement cache), so there is no behavioral change. The adhoc option will be added in a follow-up PR.

Test plan

• All existing specs pass unchanged
• New parameterized query specs verify placeholder generation
• /test --fail-fast=false

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces parameterized queries to the Couchbase ORM to replace raw string interpolation, enhancing security against N1QL injection and improving query performance. It updates query-building methods across relations, N1QL execution, and helpers to bind values into positional parameters. The review feedback highlights two important issues: first, a mismatch in spec/relation_spec.rb where the test assertions for array parameterization do not align with the actual implementation (which binds the entire array as a single parameter); second, a bug in QueryHelper#bind where returning nil for nil values leads to invalid N1QL syntax during update_all operations instead of binding nil as a positional parameter.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The test asserts that array IN conditions are parameterized as name IN [$2, $3] with individual elements in params. However, the implementation in QueryHelper#build_match binds the entire array as a single positional parameter (name IN $2 with params containing ["relation_model", ["Alice", "Bob"]]), which is also the intended behavior described in the PR description ('Pass arrays as single positional parameter'). This mismatch will cause the test to fail. Update the assertions to match the actual implementation.

            expect(n1ql).to include("name IN $2")
            expect(params).to eq(["relation_model", ["Alice", "Bob"]])

[gemini-code-assist]

Currently, bind returns nil when value is nil. In build_update_with_params, this causes update_all(field: nil) to generate invalid N1QL syntax like field = (with an empty value after the equals sign). Since build_match and build_not_match already handle nil values explicitly before calling bind, we can safely remove the nil check in bind so that nil is correctly bound as a positional parameter (e.g., field = $N with nil in params).

            def bind(value, params)
                params << serialize_for_binding(value)
                "$#{params.length}"
            end