Follow-up to #191 , which lands the neon connector as SDK-only: it talks to @neondatabase/serverless and requires a connection string (or a host in the ClientConfig).
An implementation of a second, neon-instant connector was prototyped in that PR and dropped before merge to keep the scope to one connector. Opening this to track the idea (perior work (ffe8fe9).
Idea
A neon-instant connector that provisions a claimable Neon Postgres database on demand via neon-new, so a project can createDatabase(neonInstant()) with no connection string and no signup during development.
import { createDatabase } from "db0";
import neonInstant from "db0/connectors/neon-instant";
const db = createDatabase(neonInstant());
Resolution order on first use (the client connects lazily):
- An explicit
url / connectionString (or a host) — never provisions.
process.env.DATABASE_URL — reuses the database an earlier run provisioned.
- Otherwise, provision via
instantPostgres() from neon-new, optionally seeding from a .sql file.
Design notes from the prototype
- Separate connector, not a flag on
neon. Picking the connector is the opt-in; it keeps neon-new out of the dependency graph of everyone who just wants to connect to an existing database.
neon-new is an optional dependency, imported lazily and only when a database actually has to be provisioned, so it stays out of production bundles (CONNECTOR_DEPENDENCIES supports optional: true).
- Refuses to provision when
NODE_ENV === "production", with an error pointing at the neon connector.
- Provisioning params (
seed, dotEnvFile, dotEnvKey, envPrefix, settings, referrer) are forwarded to instantPostgres and kept out of the ClientConfig passed to Client.
Open questions
- Is a dev-time auto-provisioning connector in scope for db0, or does it belong in a starter/CLI instead?
neon-new is pre-1.0; is pinning a ^0.x range in the connector metadata acceptable?
- Should the env var it reads (
DATABASE_URL) be configurable beyond dotEnvKey?
Follow-up to #191 , which lands the
neonconnector as SDK-only: it talks to@neondatabase/serverlessand requires a connection string (or ahostin theClientConfig).An implementation of a second,
neon-instantconnector was prototyped in that PR and dropped before merge to keep the scope to one connector. Opening this to track the idea (perior work (ffe8fe9).Idea
A
neon-instantconnector that provisions a claimable Neon Postgres database on demand vianeon-new, so a project cancreateDatabase(neonInstant())with no connection string and no signup during development.Resolution order on first use (the client connects lazily):
url/connectionString(or ahost) — never provisions.process.env.DATABASE_URL— reuses the database an earlier run provisioned.instantPostgres()fromneon-new, optionally seeding from a.sqlfile.Design notes from the prototype
neon. Picking the connector is the opt-in; it keepsneon-newout of the dependency graph of everyone who just wants to connect to an existing database.neon-newis an optional dependency, imported lazily and only when a database actually has to be provisioned, so it stays out of production bundles (CONNECTOR_DEPENDENCIESsupportsoptional: true).NODE_ENV === "production", with an error pointing at theneonconnector.seed,dotEnvFile,dotEnvKey,envPrefix,settings,referrer) are forwarded toinstantPostgresand kept out of theClientConfigpassed toClient.Open questions
neon-newis pre-1.0; is pinning a^0.xrange in the connector metadata acceptable?DATABASE_URL) be configurable beyonddotEnvKey?