Skip to content

fix(entity): an arrayOf(uuid()) column reads on a real Postgres; every column kind round-trips on both drivers - #752

Merged
sebyx07 merged 2 commits into
mainfrom
fix/entity-pg-array-decode
Oct 10, 2026
Merged

sebyx07 merged 2 commits into
mainfrom
fix/entity-pg-array-decode

Conversation

@sebyx07

@sebyx07 sebyx07 commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Bun.SQL returns uuid[] (and arrays of types it has no parser for) as the Postgres
array literal; decodeRow handed that string to arrayOf's parser, which refused it
(X_INVARIANT_VIOLATED column.array). PGlite parses them, so only a real Postgres
showed it: a row with a uuid[] could be written and never read back.

  • decodeRow reads a declared array column through arrayFromDriver: an Array passes,
    a typed array becomes one, a string goes through the array-literal grammar and
    each element through its declared kind. A non-array column is never inspected.
  • One array-literal reader (parsePgArray), shared with @ultimat3/realtime.
  • column-matrix: every column kind and an array of every accepted element kind,
    insert/read/update on Bun.SQL against Postgres (gate live) and on PGlite (unit).

Co-Authored-By: Claude Opus 5.5 noreply@anthropic.com

Summary by CodeRabbit

  • Bug Fixes
    • PostgreSQL array columns now decode consistently whether returned as JavaScript arrays, typed arrays, or text literals. Element values follow their declared types, including nullable elements; unsupported values report the affected entity and property.
  • Documentation
    • Clarified supported array element types and documented consistent row shapes across database drivers.
  • Tests
    • Added coverage for array round trips and comparisons across embedded and live PostgreSQL drivers.

…y column kind round-trips on both drivers

Bun.SQL returns uuid[] (and arrays of types it has no parser for) as the Postgres
array literal; decodeRow handed that string to arrayOf's parser, which refused it
(X_INVARIANT_VIOLATED column.array). PGlite parses them, so only a real Postgres
showed it: a row with a uuid[] could be written and never read back.

- decodeRow reads a declared array column through arrayFromDriver: an Array passes,
  a typed array becomes one, a string goes through the array-literal grammar and
  each element through its declared kind. A non-array column is never inspected.
- One array-literal reader (parsePgArray), shared with @ultimat3/realtime.
- column-matrix: every column kind and an array of every accepted element kind,
  insert/read/update on Bun.SQL against Postgres (gate live) and on PGlite (unit).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@developerz-ai

developerz-ai Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

✅ Reviewed — nothing blocking

0 actionable comment(s) · grounded on your code

⏱ 2m 23s wall clock · MiniMax-M3 via minimax · 3 model call(s) · 24,441 output token(s)

🤖 developerz.ai — automated review, running on your model and your box.

@coderabbitai

coderabbitai Bot commented Oct 10, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Warning

Review limit reached

The included review limit has been reached and this organization has disabled usage-based review continuation. Wait for reviews to reset or ask a billing admin to change After included review limits.

  • Ask an admin to enable usage-based reviews

Open in CodeRabbit

Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing.

Next included review available in 2 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available. Your 103 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: Repository: developerz-ai/ultimate/.coderabbit.yml
  • Review profile: ASSERTIVE
  • Plan: Essentials
  • Run ID: c91cfaa2-8b01-4d5c-b8bf-e60150ce1bd7

📥 Commits

Reviewing files that changed from the base of the PR and between 27bed25 and 411ca72.


📒 Files selected for processing (2)
  • packages/cli/src/serve-graph.test.ts
  • packages/entity/src/pg-array-decode.test.ts

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Repository: developerz-ai/ultimate/.coderabbit.yml
  • Review profile: ASSERTIVE
  • Plan: Essentials
  • Run ID: 963a6826-f911-49e5-a4ed-5f26ee31e08c


📥 Commits

Reviewing files that changed from the base of the PR and between deae5a9 and 27bed25.



📒 Files selected for processing (17)
  • CHANGELOG.md
  • docs/history/entity.md
  • packages/entity/CLAUDE.md
  • packages/entity/README.md
  • packages/entity/src/column-matrix-fixture.ts
  • packages/entity/src/column-matrix-parity.test.ts
  • packages/entity/src/column-matrix.live.test.ts
  • packages/entity/src/index.ts
  • packages/entity/src/pg-array-decode.test.ts
  • packages/entity/src/pg-array-decode.ts
  • packages/entity/src/pg-array-literal.test.ts
  • packages/entity/src/pg-array-literal.ts
  • packages/entity/src/pg-row.ts
  • packages/realtime/src/pg-array.ts
  • packages/realtime/src/pg-values.test.ts
  • packages/realtime/src/pg-values.ts
  • wiki/Entities-And-Migrations.md


Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.




📝 Walkthrough
📝 Walkthrough

Walkthrough

PostgreSQL array columns are decoded according to their declared element kind from JavaScript arrays, typed arrays, or PostgreSQL array literals. The entity package now provides the literal parser, and the realtime WAL decoder uses it. New tests cover decoding and cross-driver behavior.

Changes

Postgres array handling

Layer / File(s) Summary
Parse and decode array cells
packages/entity/src/pg-array-literal.ts, packages/entity/src/pg-array-literal.test.ts, packages/entity/src/pg-array-decode.ts, packages/entity/src/pg-array-decode.test.ts, packages/entity/src/pg-row.ts, packages/entity/src/index.ts, packages/entity/README.md, packages/entity/CLAUDE.md, wiki/Entities-And-Migrations.md, CHANGELOG.md
The entity package parses PostgreSQL array literals and converts driver values according to the declared element kind. Row decoding applies this conversion to unsealed array columns and reports unsupported values with entity and property context. Documentation describes the array behavior.
Validate cross-driver array behavior
packages/entity/src/column-matrix-fixture.ts, packages/entity/src/column-matrix-parity.test.ts, packages/entity/src/column-matrix.live.test.ts, CHANGELOG.md
A shared matrix checks round trips and array comparisons against memory and PostgreSQL drivers. PGlite tests run the matrix, and live PostgreSQL tests run it when configured.
Share the parser with realtime
packages/realtime/src/pg-array.ts, packages/realtime/src/pg-values.ts, packages/realtime/src/pg-values.test.ts, docs/history/entity.md
Realtime imports parsePgArray from the entity package and retains its WAL element-decoder lookup. The history documents the parser move and observed driver representations.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant decodeRow
  participant cellOf
  participant arrayFromDriver
  participant parsePgArray
  decodeRow->>cellOf: Pass array-column metadata and value
  cellOf->>arrayFromDriver: Decode the driver value
  arrayFromDriver->>parsePgArray: Parse a text literal
  parsePgArray-->>arrayFromDriver: Return parsed elements
  arrayFromDriver-->>cellOf: Return a decoded array
  cellOf-->>decodeRow: Return the normalized cell
Loading


Merge Risk: ⚪ Minimal · up to 27bed

This change makes Postgres array columns such as uuid[] decode correctly when Bun.SQL returns them as text literals, and it shares the parser with realtime. No merge-blocking risk was identified in the supplied changes.

Pre-merge checks | Passed 4 | Failed 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 12 files. (5 skipped: … Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly identifies the primary fix: reading arrayOf(uuid()) values from real Postgres and validating round trips across both drivers.
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.


Full details: Docstring Coverage

Explanation

Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 12 files. (5 skipped: 5 unsupported.)




✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Commit to this branch
  • Create a new PR



🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR



  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

@developerz-ai developerz-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review summary — 17 file(s), 0 finding(s).

No findings from: pg-array-refactor, entity-docs, concern-security (nothing to review: Adversarial review of the diff against the security concern set: no injection sink added (arrayLiteral/arrayElement writer is unchanged; the new parsePgArray/arrayFromDriver parse driver-returned cells into JS values before the column's $parse, never into SQL), no authn/authz boundary widened, no n…), concern-tests, concern-api-contract.

(Some reviewers completed only 0 of 1 review samples; findings are the union of the samples that completed.)


🤖 developerz.ai review — automated, running on your model and your box. What is this?
Reviewed by minimax/MiniMax-M3 on box sebby-ovh-2 — 1.22M in / 252.8k out over 10 calls, ~$0.62 on your key (estimate: list price x reported tokens).

…graph pins follow the two entity modules (measured)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@developerz-ai developerz-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review summary — 2 file(s), 0 finding(s).

Incremental diff: ceiling raises (+2 each) for two new entity modules and a type-explicit update to the date-array test assertion. Both changes are internally consistent and align with the PR description.

No findings from: concern-security (nothing to review: Both changed files are tests. serve-graph.test.ts only updates module-count pins and their explanatory comments — no behaviour, no input boundary, no privileged operation.), concern-tests (nothing to review: Every behaviour changed by this PR is asserted by a test that would fail on revert. The diff only renames a date[] element to its branded form, which is a typescript-level follow-up with the same runtime check.).

Reviewed the 1 new commit(s) since the last review (27bed25…411ca72). Earlier commits were reviewed on this PR already.


🤖 developerz.ai review — automated, running on your model and your box. What is this?
Reviewed by minimax/MiniMax-M3 on box sebby-ovh-1 — 89.8k in / 24.4k out over 3 calls, ~$0.06 on your key (estimate: list price x reported tokens).

@sebyx07
sebyx07 merged commit 934a792 into main Oct 10, 2026
17 checks passed
@sebyx07
sebyx07 deleted the fix/entity-pg-array-decode branch October 10, 2026 20:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant