feat(neon): add Role resource for managing database users

[agcty]

This PR adds the NeonRole resource for managing Postgres database roles
(users) within Neon branches.

Summary

The NeonRole resource enables programmatic management of database users
with automatic password generation, secret encryption, and full lifecycle
support.

Changes

Core Implementation

• alchemy/src/neon/role.ts - Complete resource implementation with:
  • Automatic password generation and Secret encryption
  • Support for no-login roles via no_login flag
  • Full lifecycle management (create, update, delete)
  • Integration with NeonProject and NeonBranch resources
  • Proper error handling and 404 tolerance on deletion

Tests

• alchemy/test/neon/role.test.ts - Comprehensive test suite:
  • ✅ Basic role creation with auto-generated password
  • ✅ Protected role creation (no-login)
  • ✅ Custom role names
  • ✅ Integration with Branch resources
  • All 4 tests passing with full cleanup verification

Documentation

• alchemy-web/src/content/docs/providers/neon/role.md - Complete user
  documentation with 8 usage examples
• alchemy-web/src/content/docs/providers/neon/index.md - Updated
  provider overview to include Role resource
• alchemy-web/src/content/docs/providers/neon/branch.md - Added
  Branch documentation for completeness

Usage Example

import { NeonProject, NeonBranch, NeonRole } from "alchemy/neon";

const project = await NeonProject("db", {
  name: "My Database",
});

const branch = await NeonBranch("main", {
  project,
  endpoints: [{ type: "read_write" }],
});

// Create a role with automatic password generation
const role = await NeonRole("app-user", {
  project,
  branch,
});

console.log("Username:", role.name);
console.log("Password:", role.password.unencrypted);

Key Features

- 🔐 Automatic password encryption using Alchemy's Secret type
- 🚫 Protected roles for ownership without login access
- 🔄 Full lifecycle support with proper immutability handling
- 🧪 100% test coverage with real API integration tests
- 📚 Comprehensive documentation with multiple examples

Testing

All tests pass successfully against the live Neon API:

bun vitest alchemy/test/neon/role.test.ts --run

✓ alchemy/test/neon/role.test.ts (4 tests)
  ✓ NeonRole Resource > create and delete neon role
  ✓ NeonRole Resource > create no-login role
  ✓ NeonRole Resource > role with custom name
  ✓ NeonRole Resource > role with branch resource

Test Files  1 passed (1)
Tests  4 passed (4)

API Reference

- https://api-docs.neon.tech/reference/createprojectbranchrole
- https://api-docs.neon.tech/reference/getprojectbranchrole
- https://api-docs.neon.tech/reference/deleteprojectbranchrole

Checklist

- Resource implementation following Alchemy conventions
- Full test coverage with passing tests
- User documentation with examples
- Provider overview updated
- Code formatted with Biome
- No TypeScript errors
- Secret encryption for sensitive data
- Proper lifecycle management (create, update, delete)

[Mkassabov]

why does it need to expire, if this runs in a PR environment it should be torn down once the PR is merged. If a pr is open for more than 7 days this could cause problems no?

[agcty]

I guess with alchemy there isn't really a use case for expiresAt (maybe there is?) but the api supports it, your call if it should be included or not.

[agcty]

Also this was already part of the source code, this PR just fills adds a role + fills the branch documentation gap

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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