Neon Postgres

Overview

The spike/cf-runtime branch uses Neon as the database provider. Neon is a serverless PostgreSQL offering that provides:

• HTTP driver — Works natively in Cloudflare Workers (no TCP connections)
• Database branching — Instant branches for staging and PR previews
• Auto-scaling — Compute scales to zero when idle
• S3-compatible storage — Built-in backups

Connection

The database connection is configured via DATABASE_URL environment variable. The connection string uses the Neon pooled format:

DATABASE_URL=postgresql://USER:REDACTED@ep-xxx-xxx.region.aws.neon.tech/dbname?sslmode=require

Use the real connection string from the Neon dashboard or Cloudflare Worker secrets — never commit it.

Driver

The @neondatabase/serverless package provides the HTTP driver:

import { neon } from "@neondatabase/serverless";
import { drizzle } from "drizzle-orm/neon-http";

const sql = neon(connectionString);
const db = drizzle(sql, { schema });

Bootstrap tenant (testing / pilot)

After migrations, the shared fallback database includes a seeded tenant used for smoke tests and demo.convertella.app:

Entity	Slug / hostname
Organization	demo-org
Project	demo-project
Primary hostname	demo.convertella.app (portal_domains)

Connection strings and secrets: platform/.env locally and Cloudflare Pages env vars in the dashboard — see the Database access section in platform/README.md in the monorepo. Do not commit credentials.

Migration 0022_bootstrap_demo_tenant renames legacy default-org / default-project / testing.convertella.app if present.

Branches

Two permanent branches are maintained:

Branch	Purpose	Updates
testing	Staging environment	Continuous migrations from main
production	Production environment	Migrations only during releases

Important Notes

• The Neon HTTP driver is stateless — each query is an independent HTTP round-trip
• SET LOCAL for RLS only works within a transaction (via withTenantSession)
• No persistent connection pool — ideal for serverless but different from traditional pg pools
• Consider Cloudflare Hyperdrive as an alternative if HTTP latency becomes an issue