Skip to main content

Source: ocean/docs/adr/025-postgresql-17-standardization.md | ✏️ Edit on GitHub

ADR-025: PostgreSQL 17 Standardization

Status​

Accepted

Context​

Our multi-tenant SaaS platform uses PostgreSQL across multiple services:

  • Supabase for global user database and authentication
  • Neon for tenant-specific databases
  • CrunchyBridge (planned) for master database and industry enrichment

During the baseline system analysis, we discovered version inconsistencies:

  • Supabase local development: PostgreSQL 15
  • Neon provisioning code: Mixed PostgreSQL 16 and 17
  • Documentation references: PostgreSQL 17

This inconsistency created several issues:

  1. Development/production parity violations
  2. Potential compatibility issues during provisioning
  3. Unable to leverage PostgreSQL 17 features consistently
  4. Confusion in documentation and implementation

Decision​

We are standardizing all PostgreSQL instances to version 17 across the entire platform.

Implementation Details​

  1. Supabase Local Development: Updated supabase/config.toml from v15 to v17
  2. Neon Provisioning: Updated all provisioning services to use v17
  3. Documentation: Already referenced v17 as the standard
  4. Future Services: CrunchyBridge will use v17 when implemented

Version Support Status​

  • Neon: Full PostgreSQL 17 support (available since release day)
  • Supabase Cloud: PostgreSQL 17 support in active development (expected late 2025)
  • CrunchyBridge: PostgreSQL 17 fully supported

Consequences​

Positive​

  1. Consistency: Single PostgreSQL version across all services
  2. Modern Features: Access to PostgreSQL 17 improvements:
    • Better performance for partitioned tables
    • Improved query planner
    • Enhanced JSON/JSONB operations
    • Better parallel query execution
  3. Future-Proof: Latest stable version ensures longer support lifecycle
  4. Development Parity: Local development matches production targets

Negative​

  1. Supabase Cloud Timing: Current Supabase cloud projects may still run v15
    • Mitigation: PostgreSQL 17 is backward compatible for our use cases
    • Supabase actively working on v17 rollout
  2. Local Development: Developers need to update local Supabase CLI
    • Mitigation: Clear documentation and setup instructions

Neutral​

  1. No Feature Dependencies: We don't currently use PostgreSQL 17-specific features
  2. Backward Compatibility: Our queries and schemas work across v15-17

Implementation Timeline​

  1. ✅ Immediate (Completed August 26, 2025):

    • Updated all configuration files
    • Standardized provisioning code
    • Validated with type checking and linting

  2. Short-term (Q3 2025):

    • Monitor Supabase cloud v17 rollout
    • Update developer documentation
    • Test tenant provisioning extensively

  3. Long-term (Q4 2025):

    • Migrate Supabase cloud to v17 when available
    • Implement CrunchyBridge with v17
    • Leverage v17-specific features

Technical Changes​

Files Modified​

  1. /supabase/config.toml:

    major_version = 17  # Changed from 15

  2. /supabase/functions/graphql-v2/services/atomic-provisioning.ts:

    pg_version: 17,  // Changed from 16

  3. /supabase/functions/graphql-v2/services/provisioning.ts:

    pg_version: 17,  // Changed from 16

  4. /supabase/functions/provision-tenant-resources/index.ts:

    • Already using v17 (no change needed)

Verification​

  • ✅ TypeScript compilation successful
  • ✅ ESLint validation passed
  • ✅ All provisioning services aligned
  • ⏳ End-to-end testing pending

References​

Decision Makers​

  • CTO: Approved standardization on latest stable version
  • Engineering Lead: Confirmed backward compatibility
  • DevOps: Validated deployment process compatibility

Review Date​

September 2025 - Reassess after Supabase cloud v17 rollout