docs: update service docs for connect_as

[rshoemaker]

Summary

• Removes all references to the auto-created svc_{service_id}_ro and svc_{service_id}_rw service accounts from the services docs
• Updates allow_writes description in mcp.md to describe server-side write enforcement and node routing rather than which database user is selected
• Adds database_users and connect_as fields to all MCP service examples (mcp.md and managing.md)
• Fixes stale "automatically-managed credentials" and "receives its own set of database credentials" language throughout index.md and mcp.md

PLAT-557

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes. Give us feedback}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bfa479df-2353-4324-8512-0d992c0d6d64

📥 Commits

Reviewing files that changed from the base of the PR and between f328c8c and 980ca80.

📒 Files selected for processing (3)

• docs/services/index.md
• docs/services/managing.md
• docs/services/mcp.md

✅ Files skipped from review due to trivial changes (1)

• docs/services/mcp.md

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/services/managing.md
• docs/services/index.md

---

📝 Walkthrough

Walkthrough

Docs revised to replace automatically-managed per-instance DB credentials with explicit, user-specified database users referenced by connect_as. Examples and narratives updated across service guides (MCP, PostgREST, management docs) to declare database_users, adjust allow_writes semantics, and remove prior revocation wording.

Changes

Cohort / File(s)	Summary
Service Documentation Foundation docs/services/index.md	Replaced text: services connect using the connect_as user's credentials instead of receiving per-instance auto-managed credentials; multiple-instance topology now states all per-host instances use the same connect_as credentials; RAG Server link added and MCP bullet wording adjusted.
Service Management Examples docs/services/managing.md	Updated examples to add database_users entry (e.g., username: "mcp_user", password, db_owner: true, attributes: ["LOGIN"]) and connect_as: "mcp_user" in MCP add/update examples; PostgREST example adds config.db_anon_role: "web_anon"; removed statement that Control Plane revokes service DB credentials on removal (now only stops/deletes instances).
MCP Service Guide docs/services/mcp.md	Clarified MCP authenticates by connecting as the connect_as user (no automatic per-instance credentials); adjusted allow_writes semantics to control whether query_database may perform writes (prefers standby otherwise) and expanded provisioning examples to include database_users plus connect_as: "mcp_user".

Poem

🐰 I nibble through the docs tonight,
Swapping secrets for a user bright,
connect_as hops in, tidy and clear,
database_users cheerfully appear,
A rabbit’s rhyme for changes near. 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description covers the key changes but lacks several template sections: Testing, Checklist items, and Notes for Reviewers are completely absent.	Add the missing template sections including Testing steps, completion of the Checklist items, and any relevant Notes for Reviewers to help the review process.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: updating service documentation to reflect the connect_as field for database user specification.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/PLAT-557/connect-as-service-docs

---

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]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/services/managing.md (1)

136-167: ⚠️ Potential issue | 🟡 Minor

Update example is incomplete and inconsistent with add examples.

The "Updating a Service" example is missing the database_users array and the connect_as field in the service spec. Since line 133 states that the services array is declarative and replaces the complete list, this example should include these fields for consistency with the "Adding a Service" examples and to avoid user confusion.

📝 Suggested addition

Add the database_users array and connect_as field to match the structure shown in the "Adding a Service" examples:

     curl -X POST http://host-1:3000/v1/databases/example \
         -H 'Content-Type: application/json' \
         --data '{
             "spec": {
                 "database_name": "example",
                 "nodes": [
                     { "name": "n1", "host_ids": ["host-1"] }
                 ],
+                "database_users": [
+                    {
+                        "username": "mcp_user",
+                        "password": "changeme",
+                        "db_owner": true,
+                        "attributes": ["LOGIN"]
+                    }
+                ],
                 "services": [
                     {
                         "service_id": "mcp-server",
                         "service_type": "mcp",
                         "version": "latest",
                         "host_ids": ["host-1"],
                         "port": 8080,
+                        "connect_as": "mcp_user",
                         "config": {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/services/managing.md` around lines 136 - 167, The update example omits
required fields in the service spec; modify the curl payload so the services
array in the POST body includes the same structure as the "Adding a Service"
examples by adding a database_users array and the connect_as field to the mcp
service object (the "services" array, the service object with
"service_id":"mcp-server" and its "config"), ensuring the declarative replace
behavior is clear by providing the full service entry including database_users
and connect_as values.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@docs/services/managing.md`:
- Around line 136-167: The update example omits required fields in the service
spec; modify the curl payload so the services array in the POST body includes
the same structure as the "Adding a Service" examples by adding a database_users
array and the connect_as field to the mcp service object (the "services" array,
the service object with "service_id":"mcp-server" and its "config"), ensuring
the declarative replace behavior is clear by providing the full service entry
including database_users and connect_as values.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e955abe3-8457-4a02-8660-e8b69de87a00

📥 Commits

Reviewing files that changed from the base of the PR and between a682f3e and f328c8c.

📒 Files selected for processing (3)

• docs/services/index.md
• docs/services/managing.md
• docs/services/mcp.md