Hono PostgreSQL CRUD API Starter

A Hono 4 CRUD API starter for Node.js 22 in plain JavaScript, served by @hono/node-server, that stores one resource, items, in PostgreSQL through postgres.js. It is for developers who want a tested create, read, update and delete service to rename, with input validation, limit and offset paging, JSON errors and a /health check that queries the database.

by Light CloudCRUD APIs

Features

  • GET, POST, PUT and DELETE on /items, with GET /items?limit=20&offset=0 paging oldest first and limit capped at 100
  • Queries are postgres.js tagged templates, so values go to the server as parameters with no $1 placeholders to write
  • The items table is created on start with CREATE TABLE IF NOT EXISTS, so there is no migration step to run
  • Validation without a library: name is trimmed and must be 1 to 200 characters, description a string or absent
  • JSON errors: 400 for bad input or a malformed body, 404 for unknown items and routes, and a logged 500 from app.onError
  • GET /health runs SELECT 1 and answers 200, or 503 when the database does not answer
  • src/db.js drops the uselibpqcompat and sslaccept URL parameters that postgres.js would otherwise send to the server
  • 12 node:test tests with app.request(): HTTP tests use a fake client, and a full CRUD test runs when DATABASE_URL is set

Tech stack

What you need

  • A paid plan: deploying creates a PostgreSQL database, which the Free plan does not include
  • To run it locally: Node.js 22 or newer, npm, and Docker for a local PostgreSQL
  • No API keys: it starts with nothing to configure
  • DATABASE_URL: Light Cloud sets it on deploy; locally it falls back to postgres://localhost:5432/postgres unless you export your own

About

src/app.js builds a Hono app around a postgres.js client and never listens, so the tests call app.request() with no server or port. Only src/server.js is Node.js specific: it creates the items table, starts @hono/node-server and, on SIGTERM, lets requests finish before closing the database client. The client is capped at 5 connections with a 5 second connect timeout in src/db.js, next to the CREATE TABLE you would change first when renaming items. On Light Cloud the deploy runs npm start with DATABASE_URL set, and every push to your copy redeploys.

FAQ

How do I connect Hono to a PostgreSQL database?

This starter uses postgres.js: src/db.js builds the client from DATABASE_URL and the routes run queries as sql tagged templates. Locally, start postgres:16 in Docker and export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres before npm run dev.

How do I add a new resource to a Hono API?

Add a routes file in src/routes/ modelled on items.js, a check in src/lib/validation.js and its CREATE TABLE in src/db.js, then mount it in src/app.js with app.route('/things', thingsRoutes(sql)).

Can I run this Hono API on Cloudflare Workers or Bun?

The routes in src/app.js use only Hono, so they port as they are. You replace src/server.js, which uses @hono/node-server, and check that the runtime supports postgres.js TCP connections or swap in a driver that it does.

How do I deploy a Hono app with a PostgreSQL database?

Press Deploy on this template: Light Cloud copies the repo into your GitHub account, creates a PostgreSQL database and sets DATABASE_URL on the app. Databases need a paid plan.

Can I host this Hono API without Light Cloud?

Yes. It has no Light Cloud code: any host with Node.js 22 and a reachable PostgreSQL runs it with npm install --omit=dev and npm start, given DATABASE_URL and PORT.

Price
Free
Framework
Hono · JavaScript
Updated