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.

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.

Observability side effect

With parameterized queries, parameter values are no longer embedded in the statement field of system:completed_requests (and system:active_requests). The statement now contains $1, $2, … placeholders regardless of the actual values.

DBAs or monitoring tools that inspect statement to retrieve query parameters must now read the separate positionalArgs field instead:

SELECT statement, positionalArgs, elapsedTime
FROM system:completed_requests
WHERE statement LIKE '%<pattern>%'

positionalArgs is always populated when querying via N1QL (the keyspace calls Format with profiling=true — see system_keyspace_request_log.go). It is absent only when hitting the REST endpoint with GET /admin/completed_requests.

This separation is a net positive for performance analysis: multiple executions with different values share the same canonical statement, making it straightforward to aggregate metrics per query pattern without manual string normalization.

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]

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

[pimpin]

Some points to check before merging this.