# Hono CRUD API

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.

- Framework: Hono (JavaScript)
- Category: Starters / CRUD APIs
- Creates: a server app and a PostgreSQL database on the Shared tier (1 GB)
- Plan: Lite or above
- Price: Free
- Author: Light Cloud
- Page: https://templates.light-cloud.com/starters/crud-apis/hono-postgresql-crud-api
- Updated: 2026-11-21

## 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

## 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.

## Questions

### 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.
