Database

What it is

nodabase.db is how a Node.js application talks to PostgreSQL, which is Nodabase's primary application database. The client is a thin interface over PostgreSQL: you write SQL, pass it to db.query(), and read the rows that come back.

There is no ORM, no query builder and no migrations API standing between you and the database. PostgreSQL stays PostgreSQL — joins, CTEs, JSON, window functions and the rest of the feature set are all available directly, because the API is SQL itself.

How it works

Node.js application
       |
       v
  nodabase.db
       |
       v
  PostgreSQL

The client opens a shared connection pool from DATABASE_URL using the pg driver. Every call to db.query() runs on that pool, so an application process creates one pool and reuses it for its whole lifetime.

Configuration

DATABASE_URL is the only variable this module needs:

env
DATABASE_URL=postgres://user:password@localhost:5432/mydb

When your application runs inside the Nodabase platform, this binding is provided for you. Outside the platform, point it at any PostgreSQL instance.

Without DATABASE_URL the module is not created at all: nodabase.db is simply absent from the client rather than failing at import time. Check what actually got wired up with Object.keys(nodabase).

To configure the pool itself, create the client directly — pool options pass straight through to pg.Pool:

js
import { createNodabaseClient } from "nodabase";
 
const nodabase = createNodabaseClient({
databaseUrl: process.env.DATABASE_URL,
pool: { max: 10 },
});

Basic usage

js
import { nodabase } from "nodabase";
 
const { rows } = await nodabase.db.query(
"SELECT * FROM users WHERE id = $1",
[userId]
);

$1 is a placeholder and userId is its value. Parameters are always bound separately from the SQL text, so input never changes the meaning of the query. This is the pattern for every read and write.

Common operations

Insert

js
const { rowCount } = await nodabase.db.query(
"INSERT INTO users (email, name) VALUES ($1, $2) RETURNING id",
[email, name]
);

RETURNING id puts the new row's id in rows[0].id.

Update

js
const { rowCount } = await nodabase.db.query(
"UPDATE users SET name = $1 WHERE id = $2",
[name, userId]
);

Delete

js
const { rowCount } = await nodabase.db.query(
"DELETE FROM users WHERE id = $1",
[userId]
);

Every call resolves to the standard pg result: rows holds what came back, rowCount holds how many rows the statement affected.

API surface

MemberPurpose
db.query(text, values?)run a statement, resolves to the pg result
db.connect()check out a dedicated connection from the pool
db.close()end the pool
db.poolthe underlying pg Pool, for anything query() does not cover

Any standard pg query signature works, because query() forwards its arguments to the pool exactly as given.

Closing the pool

js
await nodabase.db.close();

Long-running servers keep the pool open for the life of the process. Scripts and one-shot jobs should call close() when they are done — a process with an open pool does not exit on its own.

Important notes

  • This is a thin Node.js interface over PostgreSQL, not a proprietary database abstraction. There is no model layer to learn; knowing SQL is enough.
  • Use parameterized queries — $1, $2, … with a values array — for anything derived from input. Never build SQL by concatenating strings.
  • nodabase.db only exists when DATABASE_URL is set, so a missing binding shows up as an absent module, not a crash at import time.
  • Nodabase does not put a wall in front of your data. You can connect to the same PostgreSQL with any other tool — psql, a GUI, another service.

Next steps

  • Authentication — users and sessions through GoTrue
  • Cache — Redis-compatible caching through Dragonfly
  • Overview — how the client and the services fit together
  • Quickstart — run the platform and make the first query