next-sql

library1.0.16jsnpmunverified

next-sql is a Node.js SQL connector and query builder that provides an easy way to query SQL databases and create relationship-linked objects. The current stable version is 1.0.16, released as pre-alpha. It offers a simple API for standard queries, fallback queries, batch insert/update, pagination, and transaction support. Key differentiators include built-in relationship mapping (toOne/toMany/fromOne) without schema configuration, support for multiple hosts, and compatibility with mysql, mysql2, and PlanetScale database drivers. The release cadence is irregular as it is actively developed. Compared to alternatives like Knex or Prisma, next-sql focuses on simplicity and relational linking but lacks schema migrations and advanced type safety.

database

npm install next-sql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NEXT-SQL

next-sql

databasejavascriptv1.0.16

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import nextSQL from 'next-sql'

✗ const nextSQL = require('next-sql')

Package exports ESM by default. CommonJS require() may fail or require .default.

nextSQL

✓ import nextSQL from 'next-sql'

✗ import { nextSQL } from 'next-sql'

Default export is the main connector class; named export nextSQL does not exist.

relationship

✓ import { relationship } from 'next-sql'

✗ import relationship from 'next-sql'

relationship is a named export, not default. Available since v1.0.0.

Shows basic setup with environment variables for database config and a simple query using parameterized SQL.

import nextSQL from 'next-sql'; const db = nextSQL({ host: process.env.DB_HOST ?? 'localhost', user: process.env.DB_USER ?? 'root', password: process.env.DB_PASSWORD ?? '', database: process.env.DB_NAME ?? 'test' }); async function run() { const users = await db.query('SELECT * FROM users WHERE id = ?', [1]); console.log(users); } run();

Debug

Known issues

gotchaPackage is pre-alpha; API may break without notice.

fix

Pin to specific minor version and test thoroughly before upgrading.

affects: >=0.0.0

gotchaESM-only: CommonJS require() may not work or require .default access.

fix

Use dynamic import or switch to ESM. Example: const nextSQL = (await import('next-sql')).default;

affects: >=1.0.0

gotchaRequires one of mysql, mysql2, or @planetscale/database as peer dependency.

fix

Install at least one peer dependency: npm install mysql2

affects: >=1.0.0

gotchaEdge runtime (e.g., Vercel Edge) requires PlanetScale HTTP-based connection; socket-based drivers (mysql/mysql2) will fail.

fix

Use @planetscale/database and configure HTTP connection.

affects: >=1.0.0

gotchaNo schema validation or migration support; tables must exist beforehand.

fix

Manually create tables via SQL schema before using next-sql.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'mysql2'

Missing peer dependency mysql2

fix

npm install mysql2

TypeError: nextSQL is not a function

Using named import for default export

fix

import nextSQL from 'next-sql' (no curly braces)

Error: connect ECONNREFUSED 127.0.0.1:3306

MySQL server not running or wrong host/port

fix

Start MySQL service and verify DB_HOST and DB_PORT environment variables.

RuntimeError: Cannot use 'mysql2' in edge runtime

Using socket-based driver in edge environment

fix

Switch to @planetscale/database and configure HTTP connection.

Upgrade

Version history

1.0.16latest on npm

Audit

Dependencies

@planetscale/databaseoptionalOptional peer dependency for HTTP-based connections (PlanetScale)

mysqloptionalOptional peer dependency for MySQL connections

mysql2optionalOptional peer dependency for MySQL2 connections

Agent activity

4 hits · last 30 days

node

Resources

githubgit://github.com/cow258/next-sql ↗

packagenext-sql ↗

homepagehttps://github.com/cow258/next-sql#readme ↗