n8n-nodes-planetscale

[Velocity BPA Licensing Notice]

This n8n node is licensed under the Business Source License 1.1 (BSL 1.1).

Use of this node by for-profit organizations in production environments requires a commercial license from Velocity BPA.

For licensing information, visit https://velobpa.com/licensing or contact licensing@velobpa.com.

A comprehensive n8n community node for PlanetScale, the serverless MySQL-compatible database platform built on Vitess. This node enables workflow automation for database management, branch operations, deploy requests, and connection credential management through PlanetScale's REST API.

Features

• 12 Resource Categories: Organizations, Databases, Branches, Deploy Requests, Passwords, Backups, Deploy Queue, Service Tokens, Webhooks, Organization Members, Regions, Users
• 60+ Operations: Full CRUD operations across all resources
• Dual Authentication: Support for Service Token and OAuth authentication
• Trigger Node: Real-time webhook events for branches and deploy requests
• Cursor-based Pagination: Efficient handling of large datasets
• Rate Limit Handling: Built-in 600 req/min rate limit management
• Signature Verification: HMAC-SHA256 webhook signature verification

Installation

Community Nodes (Recommended)

1. Open n8n
2. Go to Settings > Community Nodes
3. Select Install
4. Enter n8n-nodes-planetscale in the input field
5. Click Install

Manual Installation

# Navigate to your n8n installation directory
cd ~/.n8n

# Install the package
npm install n8n-nodes-planetscale

Development Installation

# Clone the repository
git clone https://github.com/Velocity-BPA/n8n-nodes-planetscale.git
cd n8n-nodes-planetscale

# Install dependencies
npm install

# Build the project
npm run build

# Create symlink to n8n custom nodes
mkdir -p ~/.n8n/custom
ln -s $(pwd) ~/.n8n/custom/n8n-nodes-planetscale

# Restart n8n
n8n start

Credentials Setup

Service Token Authentication

To create a service token:

1. Log into PlanetScale Dashboard
2. Navigate to Organization Settings > Service tokens
3. Click "New service token"
4. Name the token and click "Create service token"
5. Copy the SERVICE_TOKEN_ID and SERVICE_TOKEN (shown only once)
6. Grant appropriate permissions (read_branch, create_branch, etc.)

OAuth Authentication

To use OAuth:

1. Create an OAuth application in Organization Settings > Beta features
2. Implement the OAuth 2.0 authorization code flow
3. Use the resulting access token

Resources & Operations

Organizations

Databases

Branches

Deploy Requests

Passwords (Connection Credentials)

Backups

Deploy Queue

Service Tokens

Webhooks

Organization Members

Regions

Users

Trigger Node

The PlanetScale Trigger node enables real-time workflow automation by receiving webhook events from PlanetScale.

Supported Events

Configuration

Webhook Signature Verification

The trigger node verifies webhook signatures using HMAC-SHA256 to ensure authenticity. This is enabled by default and uses the x-planetscale-signature header.

Usage Examples

Create a Branch and Deploy Request

// Step 1: Create a feature branch
{
  "resource": "branch",
  "operation": "create",
  "organizationName": "my-org",
  "databaseName": "my-database",
  "name": "feature-add-users-table",
  "parentBranch": "main"
}

// Step 2: Create a deploy request
{
  "resource": "deployRequest",
  "operation": "create",
  "organizationName": "my-org",
  "databaseName": "my-database",
  "branch": "feature-add-users-table",
  "intoBranch": "main"
}

Create Connection Credentials

{
  "resource": "password",
  "operation": "create",
  "organizationName": "my-org",
  "databaseName": "my-database",
  "branchName": "main",
  "name": "production-app",
  "role": "readwriter"
}

Get Schema Diff

{
  "resource": "branch",
  "operation": "getDiff",
  "organizationName": "my-org",
  "databaseName": "my-database",
  "branchName": "feature-branch",
  "compareBranch": "main"
}

PlanetScale Concepts

Branches

PlanetScale databases use a Git-like branching model. Each branch is an isolated copy of your database schema that can be modified independently.

• Production branches: Protected branches that receive production traffic
• Development branches: Used for schema development and testing
• Safe migrations: Automatic schema migration safeguards

Deploy Requests

Deploy requests are similar to pull requests. They allow you to:

1. View schema differences between branches
2. Request reviews from team members
3. Deploy schema changes to production safely
4. Automatically rollback if issues occur

Connection Credentials (Passwords)

PlanetScale generates unique connection credentials for each branch. Credentials can have different roles:

• Admin: Full database access
• Reader: Read-only access
• Writer: Write-only access
• ReadWriter: Read and write access

Error Handling

The node handles the following error scenarios:

All operations support the Continue on Fail option to handle errors gracefully in workflows.

Rate Limiting

PlanetScale API enforces a rate limit of 600 requests per minute per authentication token. The node automatically handles rate limit errors with descriptive messages.

For webhook test endpoints, there's an additional limit of 1 request per 20 seconds per webhook.

Security Best Practices

1. Use Service Tokens with Minimal Permissions: Only grant the permissions your workflow needs
2. Rotate Credentials Regularly: Periodically regenerate service tokens
3. Enable Webhook Signature Verification: Always verify webhook signatures in production
4. Use Separate Tokens per Environment: Don't share tokens between development and production
5. Protect Connection Strings: Never expose database passwords in logs or outputs

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run linting
npm run lint

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode for development
npm run dev

Author

Velocity BPA

• Website: velobpa.com
• GitHub: Velocity-BPA

Licensing

This n8n community node is licensed under the Business Source License 1.1.

Free Use

Permitted for personal, educational, research, and internal business use.

Commercial Use

Use of this node within any SaaS, PaaS, hosted platform, managed service,
or paid automation offering requires a commercial license.

For licensing inquiries:
licensing@velobpa.com

See LICENSE, COMMERCIAL_LICENSE.md, and LICENSING_FAQ.md for details.

Contributing

Contributions are welcome! Please ensure:

1. All changes pass linting (npm run lint)
2. All tests pass (npm test)
3. New features include appropriate tests
4. Documentation is updated as needed

Support

• Issues: GitHub Issues
• Documentation: PlanetScale API Docs
• n8n Community: n8n Community Forum

Acknowledgments

• PlanetScale for their excellent serverless database platform
• n8n for the powerful workflow automation platform
• Vitess for the underlying database technology