ops: data residency configuration for multi-region deployments

[daveades]

What

Support deploying Fluid with separate databases per region to comply with data residency requirements (GDPR EU isolation).

How it works

Region selection per instance

Set DATABASE_REGION=EU (or US) on each server instance. Every response carries an X-Fluid-Region header so load balancers and operators can verify routing.

Per-region connection strings

DATABASE_URL_EU=postgresql://...eu-host.../fluid
DATABASE_URL_US=postgresql://...us-host.../fluid

If a regional URL is not set, DATABASE_URL is used as fallback, so single-region deployments require no changes.

Regional DB pool (regionRouter service)

Lazily creates one Prisma client per configured region and caches it for the process lifetime. getDbForRegion(region) always returns the correct client.

Cross-region key bootstrap

findApiKeyAcrossRegions() searches all configured regional DBs in parallel. This solves the bootstrap problem: on the very first request we find the API key regardless of which regional DB it lives in. The resolved region is then cached in Redis so subsequent requests route directly.

Request-level DB routing (apiKeyMiddleware)

After resolving an API key, the middleware attaches res.locals.db (the tenant's regional Prisma client) so all downstream handlers write data to the correct region without any changes to handler code.

Schema

Tenant gains a region field (default "US") with an index. The migration is a non-destructive ALTER TABLE … ADD COLUMN safe to run per-region independently.

Per-region migration

# EU region
DATABASE_URL=$DATABASE_URL_EU npx prisma migrate deploy

# US region
DATABASE_URL=$DATABASE_URL_US npx prisma migrate deploy

Files changed

• server/src/services/regionRouter.ts — regional DB pool, URL resolution, cross-region key lookup
• server/prisma/schema.prisma — region field on Tenant
• server/prisma/migrations/20260329180000_add_tenant_region/ — migration SQL
• server/src/middleware/apiKeys.ts — attaches res.locals.db and region to ApiKeyConfig
• server/src/models/tenantStore.ts — region field on Tenant interface
• server/src/index.ts — calls initializeRegionalDbs() on startup; stamps X-Fluid-Region header
• server/.env.example — documents DATABASE_REGION, DATABASE_URL_EU, DATABASE_URL_US

Tests

18 unit tests covering:

• resolveDbUrl: regional URL priority, DATABASE_URL fallback, dev.db fallback
• DEFAULT_REGION: env var reading and uppercase normalisation
• getDbForRegion: client pool caching (same instance per region, distinct across regions)
• isRegionIsolated / getConfiguredRegions: correct region set based on env
• findApiKeyAcrossRegions: null for missing key, resilience when one regional DB errors, multi-region parallel search

closes #211

[drips-wave]

@daveades Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[github-actions]

🎉 This PR is included in version 1.21.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀