feat(data-access): add PostgreSQL/PostgREST backend adapter

[solaris007]

Summary

Adds a PostgreSQL/PostgREST backend to @adobe/spacecat-shared-data-access alongside the existing DynamoDB/ElectroDB backend. The backend is selectable via config (dataAccessBackend: 'postgresql') or environment variable (DATA_ACCESS_BACKEND=postgresql), allowing consumers to migrate incrementally.

Relation to @ekremney's data-access v3 (#1349)

Thanks to @ekremney for the pioneering work on #1349 which kicked off the v3 PostgREST migration and validated that the approach works. That PR was the inspiration for this one.

This PR takes an evolutionary approach rather than a clean break. The governing thoughts were:

• Instant switchability - ability to switch to/from PostgREST at runtime via an env var, without redeploying. This keeps both the migration window and rollback window as short as possible.
• Keep original DynamoDB code untouched - the existing ElectroDB path is not modified, so there is zero risk of breaking current consumers.
• Keep original IT tests and assertions - the same integration tests run against both backends. If a test passes on DynamoDB but fails on PostgreSQL, that is an adapter bug, not a test bug.
• No change in public API - consumers call the same methods, get the same return shapes. The backend switch is invisible to callers.

	#1349 (v3)	This PR (adapter)
Strategy	Replace DynamoDB entirely	Add Postgres alongside DynamoDB
Breaking change	Yes (feat!)	No - additive only
Migration	All consumers switch at once	Consumers switch individually via config flag
DynamoDB code	Removed	Kept, still the default backend
Test harness	PostgREST-only	Backend-agnostic (same tests, both backends)

Both approaches have merit. The evolutionary approach trades some code duplication (two backends coexist) for a safer rollout - we can enable Postgres per-Lambda, validate in production, and fall back to DynamoDB if anything breaks. The clean-break approach is simpler long-term but requires coordinated migration across all services.

We should decide together which path to take. This PR is ready for review and discussion.

What's in this PR

• Adds PostgresBaseCollection and PostgresBaseModel - generic PostgREST-backed persistence using @supabase/postgrest-js
• Adds Postgres-specific collection and model for every entity (Site, Audit, Organization, etc.)
• Adds PostgresEntityRegistry to wire all entities and their relationships
• Adds PostgresPatcher for update operations with proper field mapping
• Adds PostgREST field mapping utilities (camelCase <-> snake_case, schema annotations)
• Adds backend-agnostic IT test infrastructure (same tests run against both DynamoDB and Postgres)
• Adds Postgres smoke test for all collections
• Adds ECR authentication for IT tests to pull the mysticat-data-service Docker image

Documentation

• Design document - Architecture, design decisions, data flows, entity coverage, and risk analysis
• Implementation plan - Task-by-task implementation breakdown (12 tasks)
• Network architecture analysis (mysticat-data-service feat: add support for 404 report backlink #57) - VPC topology, DNS resolution findings, and E2E validation results from deploying a test Lambda against the dev PostgREST endpoint

Related infrastructure PRs

• spacecat-infrastructure #327 - Adds security group rules allowing Lambda to reach the PostgREST ALB on port 3000
• spacecat-infrastructure #328 - Fixes inline security group rules by migrating to standalone aws_security_group_rule resources (discovered during E2E testing - Terraform was silently dropping inline rules)

Outstanding: Route53 private hosted zone

During E2E validation we discovered that the data service ALB's DNS name (internal-data-svc-alb-....elb.amazonaws.com) resolves to public IPs only, even from within the VPC. This means Lambda traffic to PostgREST exits the VPC to the internet gateway and comes back in, instead of staying on the private network.

The proper fix is a Route53 private hosted zone that maps a friendly DNS name (e.g., data-service.spacecat.internal) to the ALB's private IPs via an alias record. This keeps traffic on the private network and avoids dependency on the internet gateway. This still needs to be implemented in spacecat-infrastructure.

For the E2E test we worked around this by resolving the ALB's private IPs manually and passing them directly to the Lambda.

E2E validation

This adapter was validated end-to-end against the dev PostgREST endpoint on 2026-02-15 using a temporary Lambda deployed into the VPC. The Lambda successfully called dataAccess.Site.findById() and received a correctly formatted site entity from the Postgres database. Full details (including reproducible steps) are documented in the network architecture analysis.

Test plan

• Unit tests pass (npm test in data-access package)
• Integration tests pass against both DynamoDB and Postgres backends
• Postgres smoke test validates all collections can be instantiated
• E2E validated in dev (see above)
• Route53 private hosted zone for data service ALB
• Review with @ekremney to align on migration strategy

[github-actions]

This PR will trigger a minor release when merged.

[ekremney]

@solaris007 thanks for taking this on and for the thorough write-up. I really appreciate the effort and the E2E validation.

Closing #1349 as part of this PR.

I want to share one architectural concern though: keeping DynamoDB/ElectroDB and Postgres/PostgREST in the same package (same major) creates a long-term operational burden. In practice, that means every change must preserve parity across two persistence implementations, two mapping layers, and two test paths. That tends to drift over time, even with good intentions.

When I proposed the feature flag idea, my thinking was that:

• v2 = DynamoDB/ElectroDB (frozen except critical fixes)
• v3 = Postgres/PostgREST only
• migration/rollback handled at service boundary, not inside the data-access package

I’d just place feature flag one layer up (lambda middleware/wrapper), where services can switch between v2 and v3 cleanly without coupling both backends into one library.

Here is an example pattern at lambda level (same wrapper style as other context injectors):

// support/data-access.js
import { getDataAccess as getDataAccessV2 } from '@adobe/spacecat-shared-data-access-v2';
import { getDataAccess as getDataAccessV3 } from '@adobe/spacecat-shared-data-access-v3';

/**
 * Wrapper function to inject data-access capabilities via context.
 * When wrapped, client code reads from context.dataAccess.
 *
 * @param {UniversalAction} fn
 * @returns {function(object, UniversalContext): Promise<Response>}
 */
export function dataAccessWrapper(fn) {
  return async (request, context) => {
    if (!context.dataAccess) {
      const backend = context.env.DATA_ACCESS_BACKEND || 'dynamodb';
      context.dataAccess = backend === 'postgresql'
        ? getDataAccessV3(context)
        : getDataAccessV2(context);
    }

    return fn(request, context);
  };
}

// action.js
import { dataAccessWrapper } from './support/data-access.js';

async function action(request, context) {
  const site = await context.dataAccess.Site.findById('...');
  // ...
}

export const main = dataAccessWrapper(action);

[solaris007]

Ekrem's PR, given #1351 (comment) is the cleaner solution. @ekremney please pull from this PR some of the fixes made that are bugs in your PR.