Skip to content

Add POST support for subset queries to avoid URL length limits#3809

Open
KyleAMathews wants to merge 3 commits intomainfrom
claude/document-electric-queries-rPGV5
Open

Add POST support for subset queries to avoid URL length limits#3809
KyleAMathews wants to merge 3 commits intomainfrom
claude/document-electric-queries-rPGV5

Conversation

@KyleAMathews
Copy link
Contributor

Summary

Added comprehensive documentation for using POST requests with subset parameters in Electric's shape API. This addresses the HTTP 414 Request-URI Too Long errors that occur when WHERE clauses become too large for GET requests.

Key Changes

  • New section: "Using POST for subset queries" explaining when and why to use POST
  • POST body format: Documented all subset parameters (where, params, limit, offset, order_by) with examples
  • Parameter separation: Clarified which parameters belong in URL vs POST body
  • Security guidance: Added detailed table of security-sensitive parameters that proxies must control server-side
  • Implementation example: Provided complete TypeScript proxy handler showing dual GET/POST support with proper authorization handling
  • Client configuration: Added examples for both ShapeStream and TanStack DB collections with subsetMethod: 'POST'
  • Backwards compatibility: Included migration strategy for gradual rollout

Notable Details

  • Emphasizes that proxies should never trust client-provided values for table, columns, where, params, and secret
  • Distinguishes between "shape definition" parameters (always in URL) and "subset snapshot" parameters (can be in body)
  • Includes warning about GET deprecation in Electric 2.0
  • Provides practical guidance on which protocol parameters are safe to pass through from clients

https://claude.ai/code/session_01MC34oGnC3Rqy4Jhsic59DY

Document how to implement POST support in authorization proxies to avoid
HTTP 414 errors with large WHERE clauses. Includes:

- POST body format and accepted parameters
- Security guidance: which parameters proxies must set server-side vs.
  which are safe to pass through from clients
- Complete proxy implementation example with GET/POST handling
- Client configuration examples for ShapeStream and TanStack DB

https://claude.ai/code/session_01MC34oGnC3Rqy4Jhsic59DY
Make the deprecation notice more prominent in both the warning box
and the backwards compatibility section.

https://claude.ai/code/session_01MC34oGnC3Rqy4Jhsic59DY
@netlify
Copy link

netlify bot commented Feb 2, 2026

Deploy Preview for electric-next ready!

Name Link
🔨 Latest commit c956b56
🔍 Latest deploy log https://app.netlify.com/projects/electric-next/deploys/6981155dcbd7160007de4365
😎 Deploy Preview https://deploy-preview-3809--electric-next.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@netlify
Copy link

netlify bot commented Feb 2, 2026

Deploy Preview for electric-next ready!

Name Link
🔨 Latest commit e8d332f
🔍 Latest deploy log https://app.netlify.com/projects/electric-next/deploys/698116ab2986290008a3cad2
😎 Deploy Preview https://deploy-preview-3809--electric-next.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Electric combines main shape WHERE (URL) with subset WHERE (POST body)
using AND, so subset queries can only narrow results, never widen them.
Updated documentation to:

- Explain how WHERE clauses are combined
- Clarify that POST body subset params are safe to forward from clients
- Simplify the proxy example to forward client body directly
- Move subset params to "safe to pass through" section

https://claude.ai/code/session_01MC34oGnC3Rqy4Jhsic59DY
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants