chore: Fix prisma studio localhost refused (#2981)

[KATO-Hiro]

close #2981

Summary by CodeRabbit

• Documentation

  • Added detailed troubleshooting guide for Prisma Studio connectivity issues when running in Docker, including diagnostic procedures and recommended solutions.

• Chores

  • Streamlined development setup procedures for database management tools.
  • Enhanced Docker Compose configuration for improved port handling and accessibility.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This pull request fixes Prisma Studio connectivity in Docker environments by addressing port exposure issues. The changes include: modifying the development script to kill existing Studio processes and bind to port 5555, exposing port 5555 in the compose configuration, and documenting the root cause and solution.

Changes

Cohort / File(s)	Summary
Development Configuration Updates CONTRIBUTING.md, compose.yaml	Modified db:studio command to kill any running Prisma Studio processes and explicitly bind to port 5555; added 5555:5555 port mapping to expose Prisma Studio from the web container to the host.
Documentation docs/dev-notes/2025-12-20/fix-prisma-studio-localhost-refused/plan.md	New documentation explaining the localhost refused issue, root cause (missing port 5555 exposure in Docker Compose), diagnostic steps, and recommended workarounds including process cleanup and port management.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

• Straightforward port mapping addition and script modification with no complex logic changes
• Documentation addition is informational and low-risk
• All changes follow a consistent pattern addressing the same issue

Poem

🐰 A Studio caged in Docker's keep,
Port 5555 hidden far and deep,
With pkill and compose now aligned,
The gateway opens—Studio's not confined!
No more "refused," the connection thrives,
Prisma's alive in our dev-box lives! ✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: fixing the Prisma Studio localhost refused issue in Docker environment.
Linked Issues check	✅ Passed	The PR addresses the linked issue #2981 by adding port 5555 mapping to compose.yaml and updating CONTRIBUTING.md to explicitly bind Studio to port 5555 with process cleanup.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing the Prisma Studio localhost refused issue: port mapping, startup procedure, and documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch #2981

---

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: 0

🧹 Nitpick comments (1)

CONTRIBUTING.md (1)

179-181: Good defensive approach to ensure consistent port usage.

The two-step process (kill existing processes + start on fixed port) prevents the port increment issue documented in plan.md. The || true ensures robustness when no Studio process exists.

Minor consideration: The sh -lc wrapper invokes a login shell. If environment setup is not required here, you could simplify to a direct pkill call. However, the current approach is safe and functional.

💡 Optional simplification if login shell is not required

-  `sh -lc "pkill -f 'prisma.*studio' || true"`
+  `pkill -f 'prisma.*studio' || true`

Only apply this if you've confirmed that the login shell (-l) is not needed for your environment setup.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

📥 Commits

Reviewing files that changed from the base of the PR and between 3398ccd and abd0d30.

📒 Files selected for processing (3)

• CONTRIBUTING.md (1 hunks)
• compose.yaml (1 hunks)
• docs/dev-notes/2025-12-20/fix-prisma-studio-localhost-refused/plan.md (1 hunks)

🔇 Additional comments (2)

compose.yaml (1)

6-6: LGTM! Port exposure for Prisma Studio.

This change correctly exposes port 5555 to allow host browser access to Prisma Studio, resolving the "localhost refused" issue when running in Docker-only environments.

docs/dev-notes/2025-12-20/fix-prisma-studio-localhost-refused/plan.md (1)

1-119: Excellent comprehensive documentation of the issue and solution.

This documentation thoroughly explains:

• Root cause (port publishing vs. port forwarding)
• Troubleshooting steps with verification commands
• The port increment issue and persistent workaround
• Operational considerations for different environments

The distinction between Docker-only usage (requiring docker compose exec prefix and -T flag) and Dev Container usage (commands run inside container) is correctly maintained. The use of -T flag on line 76 for the kill command is appropriate for non-interactive script execution, while its absence on line 82 for Studio startup is correct for keeping the interactive process running.

[KATO-Hiro]

LGTM