postgres-redis-starter

Production-ready starter template for PostgreSQL + Redis — the most common database combination in production applications.

Built by polyglotstack.dev — the definitive resource for polyglot persistence.

What's included

• PostgreSQL — primary data store with connection pooling via pg
• Redis — caching and session management via ioredis
• Docker Compose — one command to start both databases locally
• Cache-aside pattern — pre-built getOrFetch helper
• Session helpers — setSession, getSession, deleteSession
• Health check endpoint — verify both databases are connected
• Express API — example routes showing the full pattern

When to use this stack

Use PostgreSQL + Redis when:

• You need a reliable relational database with ACID guarantees
• Your app has repeated read operations on the same data
• You need fast session storage with automatic expiry
• You want to add rate limiting

Quick start

1. Clone the repo

git clone https://github.com/polyglotstack-dev/postgres-redis-starter.git
cd postgres-redis-starter

2. Install dependencies

npm install

3. Set up environment

cp .env.example .env

4. Start the databases

docker compose up -d

5. Run the app

npm run dev

Visit http://localhost:3000/health — you should see both databases connected.

Project structure

├── src/
│   ├── db/
│   │   └── postgres.js      # Connection pool + query helper
│   ├── cache/
│   │   └── redis.js         # Redis client + cache-aside helpers
│   └── index.js             # Express app with example routes
├── docker-compose.yml       # PostgreSQL + Redis services
├── .env.example             # Environment variable template
└── README.md

How the cache-aside pattern works

const { getOrFetch } = require('./cache/redis');

// Check Redis first → fetch from Postgres on miss → store in Redis
const user = await getOrFetch(
  `user:${id}`,           // Redis key
  () => db.query(...),    // Fetch function (called on cache miss)
  3600                    // TTL in seconds (1 hour)
);

Session management

const { setSession, getSession, deleteSession } = require('./cache/redis');

// Store session (expires in 24 hours)
await setSession(token, { userId: 123, role: 'admin' });

// Read session
const session = await getSession(token);

// Delete on logout
await deleteSession(token);

Cache invalidation

When data changes in PostgreSQL, delete the Redis key:

// Update in Postgres
await db.query('UPDATE users SET name = $1 WHERE id = $2', [name, id]);

// Invalidate cache — next read will fetch fresh data
await redis.del(`user:${id}`);

Environment variables

Variable	Default	Description
POSTGRES_HOST	localhost	PostgreSQL host
POSTGRES_PORT	5432	PostgreSQL port
POSTGRES_DB	myapp	Database name
POSTGRES_USER	postgres	Database user
POSTGRES_PASSWORD	postgres	Database password
REDIS_HOST	localhost	Redis host
REDIS_PORT	6379	Redis port
PORT	3000	Application port

More templates

• postgres-vector-starter — PostgreSQL + pgvector + Redis for AI apps
• mongo-elasticsearch-starter — MongoDB + Elasticsearch

Learn more

Full guides and architecture explanations at polyglotstack.dev/guides.

License

MIT