Using Neon as Postgres provider

Author Topic
admin

Posted on #

Neon, just like Supabase, is a Postgres provider. One can use a free tier to not selfhost Postgres themselves or just for testing purposes.

1. Create a Neon project

  1. Sign up at neon.tech
  2. Create a new project (pick the region closest to your server, or your homelab)
  3. Copy the connection string from the dashboard. It looks like this:
postgresql://<user>:<password>@<endpoint>-pooler.<region>.neon.tech/<dbname>?sslmode=require

2. Configure vpub-plus

Edit your .env file and set DATABASE_URL to your Neon connection string:

DATABASE_URL=postgresql://<user>:<password>@<endpoint>-pooler.<region>.neon.tech/<dbname>?sslmode=require

Since Neon’s free tier has limited connections, set explicit pool sizes instead of letting vpub-plus auto-detect:

# On free tier, as of March 2026, the limit is 104 connections. More about that in notes section.
POSTGRES_MAX_OPEN_CONNECTIONS=80
POSTGRES_MAX_IDLE_CONNECTIONS=40
POSTGRES_MAX_LIFETIME=5

The rest of .env stays the same:

SESSION_KEY=change-this-to-a-32-byte-string!
CSRF_KEY=change-this-to-a-32-byte-string!
CSRF_SECURE=false
PORT=8080
PROXYING_ENABLED=true
HOST_PORT=1337

3. Run vpub-plus from source code

# generate embedded assets (first time only or when you change something in .gohtml files)
go generate

# load .env and run vpub-plus
export $(grep -v '^#' .env | grep -v '^$' | xargs) && go run main.go

On first launch, vpub-plus will run all migrations against your Neon database and create a default admin account (admin / admin). Change the password immediately at /admin/users.

Using Docker (without self-hosted Postgres)

If you prefer Docker, the same setup works. Just make sure docker-compose.yml does not include a local db service. The DATABASE_URL from .env will point to Neon directly:

docker compose up --build

Notes

  • Cold starts: Neon suspends idle databases on the free tier. The first request after inactivity may take a second or two while the database wakes up.
  • Connection limits: The free tier allows 104 connections through the pooler. I did not test automatic settings, but just to be safe do not use all 104 connections.
  • SSL is required: Neon enforces SSL. The sslmode=require is required.

Last edited on