fix(pgsql): Escape Cypher Characters in Literals - BED-7883

[LawsonWillard]

Description

• Escapes cypher literals at the PGSQL translation layer.
• Adds unit tests to ensure escaping works as expected.

Resolves: BED-7883

Type of Change

• Bug fix (a change that fixes an issue)

Testing

Added new unit tests

• Unit tests added / updated
• Integration tests added / updated
• Manual integration tests run (go test -tags manual_integration ./integration/...)

Screenshots (if appropriate):

Driver Impact

• PostgreSQL driver (drivers/pg)
• Neo4j driver (drivers/neo4j)

Checklist

• Code is formatted
• All existing tests pass
• go.mod / go.sum are up to date if dependencies changed

Summary by CodeRabbit

• Bug Fixes

  • Cypher string literals now properly escape special characters (backslashes and single quotes) when formatted.
  • Cypher-to-PostgreSQL translation now decodes Cypher string escape sequences and reports errors for invalid escapes.

• Tests

  • Added comprehensive tests for string literal escaping and in-query rendering.
  • Added tests for escape-sequence decoding covering valid cases and expected error conditions.

[coderabbitai]

Caution

Review failed

Failed to post review comments

Walkthrough

The PR adds escaping for Cypher single-quoted string literals via NewStringLiteral, updates formatter tests to assert escaped rendering, and changes the PostgreSQL translator to decode Cypher escape sequences (with tests covering decode success and failure).

Changes

String Literal Escaping and Decoding

Layer / File(s)	Summary
Escaping API cypher/models/cypher/model.go	Adds NewStringLiteral which escapes backslashes and single quotes for Cypher single-quoted literals; documents literal escaping contract.
Format / Emit Tests cypher/models/cypher/format/format_test.go	Adds TestNewStringLiteral_Escaping and TestNewStringLiteral_InQuery to verify escaped literal Value and full-query rendering.
PostgreSQL Decoding cypher/models/pgsql/translate/translator.go	String-literal translation now calls decodeCypherStringLiteral to validate, strip quotes, and decode backslash escapes (e.g., \\, \', control chars); errors propagate on invalid input.
Decoding Tests cypher/models/pgsql/translate/translator_test.go	Adds TestDecodeCypherStringLiteral covering successful decodes (quotes, escapes, UTF-8) and error cases (missing/mismatched quotes, dangling/unsupported escapes).

Sequence Diagram

sequenceDiagram
    participant User
    participant CypherModel as Cypher Model
    participant Formatter as Cypher Formatter
    participant Translator as PostgreSQL Translator
    participant PG as PostgreSQL Literal

    User->>CypherModel: provide raw string
    CypherModel->>CypherModel: escape backslashes and single quotes
    CypherModel-->>User: return Cypher `Literal` (escaped)

    User->>Formatter: include Literal in query
    Formatter->>Formatter: render Literal with quotes
    Formatter-->>User: emit Cypher query string

    User->>Translator: pass Cypher literal value
    Translator->>Translator: decode escape sequences and strip quotes
    Translator-->>PG: produce decoded Postgres literal

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐇 I nibble at backslashes, hug each quote with care,

I tuck them safe in strings and ferry them elsewhere.
From Cypher curl to Postgres nest, decoded, neat, and bright,
A rabbit's tiny triumph — escaped and rendered right.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: escaping Cypher characters in literals at the PGSQL translation layer, with reference to the ticket BED-7883.
Description check	✅ Passed	The description covers all essential sections: clear explanation of changes, correct issue reference, appropriate bug fix classification, unit tests documented, PostgreSQL driver impact indicated, and all checklist items completed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch BED-7883

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@cypher/models/pgsql/translate/translator.go`:
- Around line 479-500: The decodeCypherStringLiteral function currently rejects
\u and \U Unicode escapes; update the escape handling in translator.go (inside
decodeCypherStringLiteral switch) to support '\u' followed by exactly 4 hex
digits and '\U' followed by exactly 8 hex digits: validate there are enough
bytes remaining, parse the hex digits, return an error on non-hex digits or
incomplete sequences, validate the resulting code point is a legal Unicode
scalar (<= 0x10FFFF and not a surrogate 0xD800–0xDFFF), and append the
corresponding UTF-8 encoding to the output buffer; keep existing error behavior
for other invalid escapes and update tests that previously expected failure for
\u/\U.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0a0681da-6b00-4182-93b8-3dd9d31aae5e

📥 Commits

Reviewing files that changed from the base of the PR and between 1eace19 and ac616cc.

📒 Files selected for processing (4)

• cypher/models/cypher/format/format_test.go
• cypher/models/cypher/model.go
• cypher/models/pgsql/translate/translator.go
• cypher/models/pgsql/translate/translator_test.go

[zinic]

We should really consider auto-parameterization of literals. Escaping is often a game of edge cases and pushing these into parameters such that $1 is substituted with the given literal may be the best line of defense here.

[LawsonWillard]

We should really consider auto-parameterization of literals. Escaping is often a game of edge cases and pushing these into parameters such that $1 is substituted with the given literal may be the best line of defense here.

Completely agree! Took a quick look into what it would take to implement this and seems like the majority of the work will be in ensuring tests are updated and working as expected. Its been a bit since I was in DAWGS and don't want to hold up the corresponding bug ticket as I implement this. I've created https://specterops.atlassian.net/browse/BED-8219 as a follow up. It should be refined on Friday and if possible, we'll pull it into the current sprint, otherwise itll be brought into the next one

Ticket I just created is a duplicate of https://specterops.atlassian.net/browse/BED-8047

[seanjSO]

LGTM!