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 driver | Engines | Change |
|---|---|---|
@neondatabase/serverless (neon(), Pool, Client) | PostgreSQL, TimescaleDB | DATABASE_URL |
@planetscale/database (database-js) | MySQL, MariaDB | DATABASE_URL |
@upstash/redis | Valkey, Redis | UPSTASH_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.
Neon serverless driver
Section titled “Neon serverless driver”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 requestconst 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 derivesapi.from your host by itself), the WebSocket ofPoolandClienttowss://pg-7f3k.us-east.databasezy.com/v2. NoneonConfigsetting 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()withisolationLevel,readOnlyanddeferrable, and errors with their SQLSTATEcode,detailandconstraintall behave the same. authToken(JWT authentication) is not supported: use the password.- On a pooled instance,
neon()queries are fine through the pooler; forPoolandClientsessions that need session features (advisory locks,LISTEN), use the-directhost in the connection string.
PlanetScale database-js
Section titled “PlanetScale database-js”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
appdatabase every instance and database user starts with. Reach other databases with qualified names (otherdb.table). - Types and values arrive as on PlanetScale:
INT64andDECIMALas strings, smaller integers and floats as numbers,JSONparsed, binary columns as bytes. MariaDB storesJSONasLONGTEXT, 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 port3306.
Upstash Redis
Section titled “Upstash Redis”UPSTASH_REDIS_REST_URL="https://valkey-7f3k.us-east.databasezy.com"UPSTASH_REDIS_REST_TOKEN="<password>" # or "<user>:<password>" for a database userimport { 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-execand path-style requests (GET /get/greeting,POST /set/greetingwith 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,SUBSCRIBEand the other pub/sub subscriptions,MONITOR,CLIENT REPLY. Use a TCP client (rediss://) for pub/sub. MULTI/EXECinside/multi-execis added by the gateway; do not send them yourself there.
Security and limits
Section titled “Security and limits”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 tohttps://<instance host>/sqlwithneonConfig.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_connectionsand connection rate together with your TCP clients. A busy app gets429(too many connectionsorrate limit); use a WebSocketPool(Neon) or a pooled instance for high request rates. - Browsers: requests from web pages (with an
Originheader) 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.
| Limit | Value |
|---|---|
| Request body | 4 MiB (413 above) |
| Rows or replies per request | 16 MiB (an error above) |
One request (a Neon batch, a MULTI/EXEC, a blocking command) | 30 s, then cancelled and rolled back |
| PlanetScale transaction | 20 s idle, 2 min in total |
| TLS | 1.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.