fix(join): keep only the newest over-long join labels per adapter

[abnegate]

What

• Bug: 8.3.7 (feat(join): accept Appwrite table IDs as join aliases #1039) labels a joined column whose alias.column label is longer than the engine keeps (PostgreSQL: 63 bytes) as $join_<md5>. It records the original label in a static map that is never pruned. Join aliases are chosen by the caller, so a long-lived Swoole worker serving joins under ever-new long aliases keeps every label it was ever asked for, and its memory grows without bound. Reported in review on chore(deps): bump utopia-php/database to 8.3.8 (join aliases from table IDs) appwrite/appwrite#14612.

• Fix: the map is now per adapter instance and keeps the newest 1024 labels, evicting the oldest first.

• Why not reset the map per read: find() can call getDocument() partway through, via getJunctionName() and SQLite's full-text table lookup, before it remaps its own rows. A reset there would drop the outer read's labels.

• Why eviction is safe:

  • A read's own labels are always the newest when its rows are remapped.
  • An adapter owns one connection and runs one statement at a time.
  • A single read needs at most a few labels (≤ 8 joins × selected columns).

  So a read never loses its own labels.

Before / after

tests/unit/Adapter/JoinLabelRetentionTest.php uses SQLite with an 8-byte label limit, so every joined label goes through the digest path:

Test	8.3.7 (main)	This PR
1,100 reads, each under a new alias; every value is read back and the map holds ≤ 1024 labels	fails: Every overlong label ever read is still held (1,100+ labels)	passes
1,024 older labels, then a read with two joins: both values are read back after eviction	passes	passes

pint and phpstan pass locally. The full adapter matrix runs in CI.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Long labels used in joined results are now restored correctly, including after many earlier joins.
  • Join-label history is limited, preventing it from growing without bound during extended use.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: utopia-php/database/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 59935977-cc57-4a8b-8722-7154b52933bf

📥 Commits

Reviewing files that changed from the base of the PR and between 50ec3c4 and 542b8cb.

📒 Files selected for processing: 2

• src/Database/Adapter/SQL.php
• tests/unit/Adapter/JoinLabelRetentionTest.php

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

SQL adapters now keep join-label digests in an instance-level map capped at 1,024 entries. When the map exceeds the cap, the oldest mapping is removed. Tests check the cap and verify that joined-column labels are restored after eviction.

Changes: Join-label retention

Layer / File(s)	Summary
Bounded adapter-local label map src/Database/Adapter/SQL.php, tests/unit/Adapter/JoinLabelRetentionTest.php	The adapter stores join-label digests in an instance map, moves newly recorded labels to the newest position, and evicts the oldest entry above 1,024 labels. remapRow() uses that map to restore labels. Tests check the retention limit and label restoration after earlier entries are evicted.

Priority: ➖ Normal

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

Change: Bug fix

Suggested reviewers: fogelito

Merge Risk: ⚪ Minimal · up to 542b8

This change bounds join-label memory growth in long-lived workers by making the label map per adapter and capping it. No actionable merge-blocking risk was found.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: limiting retained over-long join labels to the newest entries per adapter.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ 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

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.}