Skip to content

Connect

Serverless drivers (Neon, PlanetScale, Upstash)

Tested with:@neondatabase/serverless 1.2 · @planetscale/database 1.19 · @upstash/redis 1.39 · Node 22 · PostgreSQL 16, MySQL 8.4, MariaDB 11.4, Valkey 8

Edge runtimes (Vercel Edge, Cloudflare Workers, Deno Deploy, Netlify Edge) cannot open TCP connections, so many apps talk to their database through an HTTP driver. Databasezy speaks the protocols of the three common ones on every instance’s own hostname. When you migrate, keep the driver and change only the URL and credentials.

Your driverEnginesChange
@neondatabase/serverless (neon(), Pool, Client)PostgreSQL, TimescaleDBDATABASE_URL
@planetscale/database (database-js)MySQL, MariaDBDATABASE_URL
@upstash/redisValkey, RedisUPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN

The credentials are always the database’s own: the instance login shown under Connect, or a database user (Database users on the instance). Project API keys do not work here.

Terminal window
DATABASE_URL="postgresql://app:<password>@pg-7f3k.us-east.databasezy.com/app?sslmode=require"
import { neon, Pool } from "@neondatabase/serverless";
const sql = neon(process.env.DATABASE_URL!); // HTTP: one query or one transaction per request
const rows = await sql`select * from notes where id = ${id}`;
const [a, b] = await sql.transaction([sql`select 1`, sql`select 2`], { isolationLevel: "RepeatableRead", readOnly: true });
const pool = new Pool({ connectionString: process.env.DATABASE_URL }); // WebSocket: sessions
  • HTTP queries go to https://api.us-east.databasezy.com/sql (the driver derives api. from your host by itself), the WebSocket of Pool and Client to wss://pg-7f3k.us-east.databasezy.com/v2. No neonConfig setting is needed.
  • Results come back with the PostgreSQL type of every column, so the driver parses numbers, booleans, dates, arrays and JSON exactly as it does on Neon. arrayMode, fullResults, transaction() with isolationLevel, readOnly and deferrable, and errors with their SQLSTATE code, detail and constraint all behave the same.
  • authToken (JWT authentication) is not supported: use the password.
  • On a pooled instance, neon() queries are fine through the pooler; for Pool and Client sessions that need session features (advisory locks, LISTEN), use the -direct host in the connection string.
Terminal window
DATABASE_URL="mysql://app:<password>@mysql-7f3k.us-east.databasezy.com/app"
import { connect } from "@planetscale/database";
const conn = connect({ url: process.env.DATABASE_URL });
const { rows, insertId } = await conn.execute("insert into items (name) values (?)", ["widget"]);
await conn.transaction(async (tx) => {
await tx.execute("update stock set n = n - 1 where id = ?", [1]);
await tx.execute("insert into orders (item) values (?)", [1]);
});
  • database-js sends no database name, so statements run in the app database every instance and database user starts with. Reach other databases with qualified names (otherdb.table).
  • Types and values arrive as on PlanetScale: INT64 and DECIMAL as strings, smaller integers and floats as numbers, JSON parsed, binary columns as bytes. MariaDB stores JSON as LONGTEXT, so there it arrives as a string.
  • Errors are DatabaseErrors whose message ends in (errno 1062) (sqlstate 23000), the form ORMs parse.
  • A transaction keeps its database connection between statements for up to 20 seconds idle and 2 minutes in total; after that it is rolled back and its next statement fails with ABORTED (never runs outside the transaction). Statements of one transaction run one at a time. Statements outside a transaction each run on a fresh connection, so session state (SET @var, USE) does not carry over between them.
  • Use the URL without a port in production. With a port, database-js connects to exactly that port, so for a test against a single-IP region use :8443, never the MySQL port 3306.
Terminal window
UPSTASH_REDIS_REST_URL="https://valkey-7f3k.us-east.databasezy.com"
UPSTASH_REDIS_REST_TOKEN="<password>" # or "<user>:<password>" for a database user
import { Redis } from "@upstash/redis";
const redis = Redis.fromEnv();
await redis.set("greeting", "hello", { ex: 60 });
const p = redis.pipeline();
p.incr("visits");
p.get("greeting");
await p.exec();
await redis.multi().set("a", "1").incr("a").exec();
  • POST / (one command), /pipeline, /multi-exec and path-style requests (GET /get/greeting, POST /set/greeting with the value as the body) work as on Upstash, including the base64 response encoding the SDK asks for by default.
  • Commands that change or take over the connection are refused: AUTH, HELLO, RESET, QUIT, SUBSCRIBE and the other pub/sub subscriptions, MONITOR, CLIENT REPLY. Use a TCP client (rediss://) for pub/sub.
  • MULTI/EXEC inside /multi-exec is added by the gateway; do not send them yourself there.

The HTTP surfaces are the instance’s own endpoint, so everything you configured for it applies unchanged:

  • IP allow-list: clients outside it are refused before TLS on the instance host. HTTP queries through the regional api. host are checked per request and get the same answer as an unknown host.
  • Client certificates (mTLS): required on the instance host as for TCP. The regional api. host cannot ask for a client certificate, so send Neon HTTP queries for such instances to https://<instance host>/sql with neonConfig.fetchEndpoint.
  • Pause and wake: a request to a sleeping instance wakes it and waits, like a TCP connection. A paused or suspended instance refuses requests.
  • Connections: every request in flight and every WebSocket session counts against the size’s max_connections and connection rate together with your TCP clients. A busy app gets 429 (too many connections or rate limit); use a WebSocket Pool (Neon) or a pooled instance for high request rates.
  • Browsers: requests from web pages (with an Origin header) are refused. Call the database from your server or edge function, never from client-side code.
  • Wrong passwords count toward the temporary IP block exactly like failed TCP logins.
LimitValue
Request body4 MiB (413 above)
Rows or replies per request16 MiB (an error above)
One request (a Neon batch, a MULTI/EXEC, a blocking command)30 s, then cancelled and rolled back
PlanetScale transaction20 s idle, 2 min in total
TLS1.2 or 1.3, the region’s wildcard certificate (or your custom domain’s)

HTTP responses count as egress of your project’s Data API in usage; WebSocket sessions count as the instance’s egress, like TCP.