DEV Community: ZyVOP

Beyond Autocomplete: How AI Editors Actually Understand Your Codebase

ZyVOP — Fri, 29 May 2026 05:49:04 +0000

The first time an AI editor suggests the exact function signature you needed — one that lives three files away in a utility module you half-forgot existed — it feels like magic. Then it happens again. And again.

It's not magic. It's not luck. And it's definitely not just autocomplete with a fancier model.

This post is the no-hand-waving answer to: how does it actually know that?

The Old World: Single-File Thinking

Classic IntelliSense worked on Abstract Syntax Trees. You type:

const user = new User();
user.
//    ^ IDE parses User class → offers .id, .email, .save()

Useful. But it only answered: "given what I can see in this one file, what tokens are syntactically valid next?"

It couldn't answer: "the *parseUser() helper in utils/auth.ts has a null-email edge case — your test in __tests__/auth.spec.ts already covers it, so don't re-invent it."*

That's not a subtle difference. That's the difference between a dictionary and a colleague.

The first ML-based tools (TabNine early models, Kite) tried to go further — training on millions of GitHub repos to predict likely next tokens. But they had the same blind spot:

# TabNine circa 2020 — knows that catch blocks often contain:
try:
    result = fetch_user(user_id)
except Exception as e:
    # → suggests: logger.error(e) / raise / return None
    # Based on: "what do most codebases do here?"
    # NOT based on: "what does THIS codebase do here?"

The model was a well-read stranger. Knowledgeable about programming in general. Completely ignorant about your code in particular.

The Shift: What Goes Into the Context Window

The core change in modern AI editors is deceptively simple: the model sees more of your codebase at once. But "more" isn't just quantity — it's a qualitative shift in what reasoning becomes possible.

Here's how the context window has grown:

Era	Window	What fits
Codex / early Copilot (2021)	4k tokens	~1 file
GPT-4 Turbo (2023)	128k tokens	~30–40 files
Claude 3.5 / Gemini 1.5 (2024)	200k tokens	~entire small project

When you trigger a suggestion today, the context window assembled for the model typically looks like this:

[CONTEXT ASSEMBLED FOR: "write a sendWelcomeEmail function"]

1. Current file (full):          api/users.ts
2. Recently visited:             services/email.ts, db/models/user.ts
3. Imported by current file:     utils/auth.ts, config/constants.ts
4. Type definitions:             types/User.d.ts, types/Email.d.ts
5. Related tests:                __tests__/users.spec.ts
6. Config:                       tsconfig.json, package.json
7. RAG-retrieved chunks:         [see next section]

The model never sees your whole repo. It sees a curated slice — assembled by a retrieval pipeline that runs before the model ever processes your query.

RAG: The Invisible Brain Before the Brain

Retrieval-Augmented Generation is the engine behind every "how did it know that?" moment. Here's exactly what happens.

Step 1 — Indexing: Your Codebase Becomes Vectors

When you open a project, the editor quietly builds a semantic index. Every function, class, type, and docstring gets converted into a vector embedding — a list of numbers representing its meaning, not its syntax.

// Source code chunk:
function validateEmail(email: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

// After embedding model processes it:
→ [0.23, -0.87, 0.44, 0.91, -0.12, 0.67, ...]
//  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
//  768 numbers encoding "email validation logic"

// Another chunk, completely different file:
it('should reject emails without @ symbol', () => {
  expect(validateEmail('notanemail')).toBe(false);
});

→ [0.21, -0.83, 0.48, 0.88, -0.09, 0.71, ...]
//  Similar vector = semantically related

Chunks with similar meaning cluster near each other in vector space — even if they share zero literal words.

The chunking isn't by line count. It uses Tree-sitter (a structural parser) to split at meaningful code boundaries: one function per chunk, one class per chunk. This ensures each chunk is a semantically complete unit, not an arbitrary slice of text.

Step 2 — Retrieval: Semantic Search at Query Time

When you write a comment or ask a question, your query gets embedded the same way:

Your query: "write a function that sends a welcome email to new users"

→ Query vector: [0.19, -0.79, 0.51, 0.85, -0.14, 0.63, ...]

Vector DB finds nearest neighbours:
  ✓ validateEmail()         — distance: 0.12  (email logic)
  ✓ UserProfile interface   — distance: 0.18  (user data shape)  
  ✓ emailService.sendGrid() — distance: 0.21  (email sending)
  ✓ NEW_USER_TEMPLATE const — distance: 0.24  (email templates)
  ✓ user.spec.ts fixture    — distance: 0.31  (test patterns)

None of those results contain the words "welcome" or "send." The retrieval found them because they're conceptually related — not textually matched.

This is what separates modern AI editors from grep. Grep finds literal matches. RAG finds conceptual neighbours.

Most editors also run a BM25 lexical search in parallel (a fast keyword search) and merge both result sets — so you get the best of semantic understanding and exact-name matching.

Step 3 — Reranking: Quality Filtering

Raw retrieval returns the 50-100 most similar chunks. A reranker model then re-scores them by reading the query and each chunk together:

Bi-encoder retrieval (fast, less accurate):
  → Scores chunks independently against query vector

Cross-encoder reranking (slow, highly accurate):
  → Reads query + chunk together
  → Models their actual interaction
  → Re-ranks the candidate set

Final top-10 chunks injected into context window ✓

The model sees only the reranked top results. It never knows a 50-candidate shortlist was assembled and filtered before it got involved.

Tree-sitter: The Structural Skeleton

Tree-sitter is an incremental, error-tolerant parser that maintains a live syntax tree of your code — updated character-by-character as you type, even when your code has syntax errors.

// You type this (incomplete, invalid syntax):
function processOrder(order: Order) {
  const items = order.li
  //                   ^ cursor here, code is broken

// Tree-sitter still produces:
FunctionDeclaration
  name: "processOrder"
  parameters:
    Parameter { name: "order", type: "Order" }
  body:
    VariableDeclaration
      name: "items"
      initializer: MemberExpression (incomplete)
        object: Identifier "order"
        property: Identifier "li" [ERROR]

Even broken code gets a useful tree. This does three critical things for AI editors:

1. Precise chunk boundaries for RAG. Instead of splitting on line 50, line 100, line 150... the RAG pipeline splits at FunctionDeclaration ends. Every embedded chunk is a complete, coherent unit.

2. Scope and symbol resolution.

const userId = 'admin';           // scope: module

function getUser(userId: string) { // scope: function (shadows outer)
  return db.find(userId);          // which userId? Tree-sitter knows.
}

The AI gets precise scope information, not guesses.

3. Surgical edits. When applying a suggested change, the editor uses Tree-sitter node ranges to replace exactly lines 14-28, columns 2-47 — not fragile line-number approximations.

The Semantic Graph: Thinking in Relationships

Beyond RAG, the best editors maintain a live semantic graph — a map of every relationship between every symbol in your project.

Nodes:  functions, classes, types, constants, interfaces
Edges:  calls, imports, implements, uses, tests

Example subgraph:
  checkout()
    ├─ calls → validateCart()
    │            ├─ calls → getInventory()
    │            └─ uses  → CartItem (type)
    ├─ calls → processPayment()
    │            └─ calls → stripe.charge()
    ├─ uses  → Order (type)
    │            └─ uses  → LineItem (type)
    └─ tested by → checkout.spec.ts
                     ├─ uses fixture → mockCart
                     └─ uses fixture → mockPayment

This graph enables reasoning that no single file can provide.

Impact analysis before you change anything:

// You're about to change:
interface User {
  id: number;
  email: string;
  // adding:
  accountId: string;  // ← new field
}

// Semantic graph instantly knows:
// → 23 files reference this interface
// → 4 will have type errors (missing accountId)
// → 2 tests use User fixtures that need updating
// → 1 DB migration needs to add the column
// → GraphQL schema needs a new field

Without the graph, the AI infers this from whatever's in the context window. With the graph, it knows it precisely.

Parametric vs. Retrieved Knowledge

The model has two completely different sources of "knowledge" — and confusing them explains most AI editor failures.

Parametric knowledge — baked into weights during training:

// Ask: "how does Promise.allSettled differ from Promise.all?"
// Model answers from parametric knowledge — reliable, no retrieval needed

Promise.all([p1, p2, p3])
// → Rejects immediately if ANY promise rejects
// → Returns values array only on full success

Promise.allSettled([p1, p2, p3])
// → Waits for ALL promises to finish
// → Returns [{status, value/reason}, ...] always

Retrieved knowledge — read fresh from your codebase every request:

// Ask: "write a new admin route using our middleware pattern"
// Model reads YOUR code to understand YOUR conventions:

// Retrieved chunk from api/users.ts:
router.get('/users', authenticate, authorize('admin'), async (req, res) => {
  const users = await UserService.getAll();
  res.json({ data: users, meta: buildMeta(req) });
});

// Retrieved chunk from api/orders.ts:
router.get('/orders', authenticate, authorize('admin'), async (req, res) => {
  const orders = await OrderService.getAll(req.query);
  res.json({ data: orders, meta: buildMeta(req) });
});

// Now generates for your new route — matching YOUR patterns:
router.get('/products', authenticate, authorize('admin'), async (req, res) => {
  const products = await ProductService.getAll(req.query);
  res.json({ data: products, meta: buildMeta(req) });
});
// ✓ Same middleware order
// ✓ Same response shape
// ✓ Same meta helper
// ✓ Same query-forwarding pattern

The dangerous gap: asking about a library where parametric knowledge is version 3.x but your project uses version 4.x. The model will confidently generate wrong code. Always check suggestions involving third-party libraries against your actual installed version.

Agentic Loops: When the AI Iterates Like You Do

Static suggestions work for small tasks. Complex tasks need feedback. Agentic mode closes the loop:

Task: "Add input validation to the POST /orders endpoint"

Loop iteration 1:
  AI reads:  api/orders.ts, types/Order.ts, existing validators
  AI writes: validation middleware using zod schema
  AI runs:   npm test -- orders
  AI reads:  "FAIL: missing validation for lineItems array"

Loop iteration 2:
  AI reads:  types/LineItem.ts (retrieved by semantic search)
  AI writes: adds lineItems schema to zod validator
  AI runs:   npm test -- orders
  AI reads:  "FAIL: test expects 422 status, got 400"

Loop iteration 3:
  AI reads:  api/users.ts (how validation errors are returned elsewhere)
  AI writes: changes error status to match project convention (422)
  AI runs:   npm test -- orders
  AI reads:  "PASS: 8 tests passed"
  AI done ✓

Each iteration, the model re-reads the codebase with fresh context informed by what it just learned. It's not lucky — it's using the same feedback loop you use, powered by everything we've described: retrieval to find related code, Tree-sitter to apply precise edits, the semantic graph to understand what else might be affected.

Where the Seams Show

None of this is perfect. Each failure mode maps to a specific architectural layer.

Retrieval miss: The AI ignores code you know exists.

Cause: RAG didn't retrieve the right chunks.
Fix:   @mention the file explicitly in your prompt.
       "In the style of @api/users.ts, write a..."

Stale index: The AI reasons about code you deleted last week.

Cause: Background indexing lagged after a large refactor.
Fix:   Trigger a manual reindex. Start a fresh chat session.

Parametric version mismatch: Confident but wrong API usage.

// AI generates (using parametric knowledge of Mongoose v5):
User.findOne({ email }).exec().then(...)

// Your project uses Mongoose v8 (async/await preferred):
await User.findOne({ email })  // ← no .exec() needed

Cause: Parametric knowledge doesn't match your installed version.
Fix:   Include your package.json or the actual function signature
       in your prompt context.

Context window saturation: The AI "forgets" things in long sessions.

Cause: Window is full. Old context gets dropped.
Fix:   Start a new conversation for each new task.
       Don't rely on the AI retaining earlier context indefinitely.

The Gap Has Closed Farther Than Most Developers Realise

The developer who tried Copilot in 2022, found it useful for boilerplate, and formed the opinion "AI coding = fancy tab complete" is working with a two-year-old mental model.

The current generation — used well — doesn't feel like a faster way to type. It feels like a collaborator who has read your entire codebase, understands your architecture, follows your conventions, and can reason about your specific system rather than code in general.

That's not because models got smarter (though they did). It's because of the full stack:

Your query
    ↓
RAG pipeline        — finds relevant code across your entire repo
    ↓
Tree-sitter         — provides precise structural grounding
    ↓
Semantic graph      — maps relationships between symbols
    ↓
Long context window — holds enough to reason coherently
    ↓
Language model      — combines parametric + retrieved knowledge
    ↓
Agentic loop        — iterates until tests pass
    ↓
Your editor

Every layer compounds. Remove any one of them and the experience degrades sharply.

The autocomplete era is genuinely over.

Originally published on ZyVOP

pg.Pool vs PgBouncer: When Client-Side Pooling Is Not Enough

ZyVOP — Thu, 28 May 2026 14:37:14 +0000

Every Node.js PostgreSQL tutorial shows you pg.Pool. You set max: 20, you get 20 reusable connections, and that works fine for a single-server app with moderate traffic. The problems start when you add a second server, or scale to 10 pods, or deploy to Lambda, or hit the PostgreSQL default connection limit of 100.

pg.Pool is per-process. PgBouncer is per-database. That distinction determines everything about when you need one versus the other.

This guide covers exactly when pg.Pool alone is sufficient, when PgBouncer becomes necessary, how to configure each correctly, and the tradeoffs you accept when adding PgBouncer's transaction pooling mode.

What pg.Pool Actually Does

pg.Pool maintains a pool of TCP connections from a single Node.js process to PostgreSQL. When your code calls pool.query(), it borrows a connection from the pool, runs the query, and returns the connection. No connection setup overhead on every query — the TCP handshake and authentication happen once at pool startup.

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max:             20,   // 20 connections from THIS process to Postgres
});

The key word is "this process." If you run 5 Node.js processes (5 pods, 5 PM2 workers, 5 Lambda cold starts), you have 5 × 20 = 100 connections to PostgreSQL. Postgres's default max_connections is 100. You just hit the ceiling on the first query burst.

The Connection Math That Breaks Production

PostgreSQL, by default, allows 100 simultaneous connections. On a 2GB server, each connection uses around 5–10MB of memory — meaning a theoretical maximum of around 180–200 connections before memory becomes the constraint, though conservative guidance is 20–30 application connections with PgBouncer handling the multiplexing.

Scenario: 10 Node.js pods, each with pool.max = 20

10 pods × 20 connections = 200 connections → exceeds Postgres default limit

Result: "FATAL: sorry, too many clients already"

A pool is not global — it is per-process and often per-container. Pools multiply with pods and processes. PgBouncer can smooth spikes, but it fundamentally changes what "pooling" means.

The moment you run more than one process, pg.Pool alone is no longer sufficient to control the total connection count to Postgres.

What PgBouncer Actually Does

PgBouncer sits between your application and Postgres as a TCP proxy. Your application connects to PgBouncer (port 6432). PgBouncer maintains a small pool of actual Postgres connections and queues application requests against them.

10 Node.js pods × 20 connections = 200 connections to PgBouncer
PgBouncer                         = 20 connections to Postgres

Postgres sees 20 connections regardless of how many pods you run

PgBouncer in transaction mode handles the multiplexing — you trade an extra network hop for a hard ceiling on actual Postgres connections. The things you lose — session-level SET, advisory locks, LISTEN/NOTIFY — are real, but for standard API workloads they are not typically on the critical path.

The Three Pooling Modes

Session mode — one Postgres connection per client session. Same as no pooling. Not useful.

Transaction mode — one Postgres connection per transaction. Released back to the pool after COMMIT or ROLLBACK. This is the mode to use. It prevents connection-aging issues with certain Postgres extensions and forces natural, gradual connection recycling rather than a single big reset event.

Statement mode — one Postgres connection per statement. Breaks anything using multi-statement transactions. Avoid.

When pg.Pool Alone Is Sufficient

You do not need PgBouncer if all of the following are true:

You run a single Node.js process (one server, one container, no horizontal scaling)
Your total connections (max × process count) stay *under 80% of Postgres *max_connections
You do not use serverless or autoscaling (Lambda, Fargate, Cloud Run)
Your queries are short-lived (under 5 seconds) — long queries holding connections are less dangerous with a single process

For a single VPS running one Node.js container with pool.max = 20, pg.Pool is all you need. Keep it simple.

When PgBouncer Becomes Necessary

Add PgBouncer when any of these apply:

Multiple processes or pods. Even two PM2 workers double your connection count. Four PM2 workers with connection_limit = 22 each = 88 connections. With PgBouncer, all 4 workers share 20 server connections in transaction mode. PostgreSQL is never overwhelmed.

Serverless or autoscaling. When deployed on Lambda, which opens a new connection on every cold start, adding PgBouncer in front of Postgres to multiplex connections drops connection overhead from 50ms per request to near-zero. Lambda functions cannot maintain persistent pools — PgBouncer provides the persistence layer.

Connection count approaching **max_connections.** The signal that tells you something is wrong is pg_stat_activity showing a pile of idle connections next to a handful of active ones. Check it:

SELECT state, count(*)
FROM pg_stat_activity
WHERE datname = 'yourdb'
GROUP BY state;
-- If idle >> active, you have idle connections wasting Postgres memory

Configuring pg.Pool Correctly

The pool size formula: (CPU cores × 2) + effective spindle count, as a starting point — but for most web API workloads, 10–20 per process is the right range.

// src/lib/db.ts
import { Pool } from 'pg';

export const pool = new Pool({
  connectionString: process.env.DATABASE_URL,

  // Maximum connections this process will open
  // For a single-process app: 10-20 is the right range
  // For multi-process: (Postgres max_connections × 0.8) / process_count
  max: parseInt(process.env.DB_POOL_SIZE || '20'),

  // Kill queries running longer than 5 seconds
  // The most important guard against connection exhaustion
  statement_timeout: 5000,

  // Fail fast if no connection available — do not queue indefinitely
  connectionTimeoutMillis: 3000,

  // Release idle connections after 30 seconds
  idleTimeoutMillis: 30_000,

  // Recycle connections after 7,500 queries
  // Prevents slow memory drift in long-running Postgres backends
  // Documented 2026 recommendation: set this for stable long-running servers
  maxUses: 7500,
});

// Log pool errors — do not let them disappear silently
pool.on('error', (err) => {
  console.error('Pool error:', err.message);
});

maxUses prevents memory leaks — PostgreSQL backend processes can slowly leak memory over thousands of queries. Setting maxUses: 7500 recycles connections regularly, keeping memory stable. This is especially important for long-running server processes.

Also: match pool idle timeouts to infrastructure — if your load balancer has a 60-second idle timeout, set your pool's idleTimeoutMillis to 50 seconds (slightly lower). Mismatched timeouts cause "connection terminated unexpectedly" errors.

Configuring PgBouncer

# /etc/pgbouncer/pgbouncer.ini

[databases]
yourdb = host=127.0.0.1 port=5432 dbname=yourdb

[pgbouncer]
listen_port    = 6432
listen_addr    = 127.0.0.1       # Localhost only — never expose to internet
auth_type      = md5
auth_file      = /etc/pgbouncer/userlist.txt

; Transaction mode — one connection per transaction
pool_mode = transaction

; Max connections your app sends to PgBouncer (all pods combined)
max_client_conn = 500

; Max actual Postgres connections PgBouncer opens
; Rule: (Postgres max_connections × 0.8) - reserved_for_superuser
default_pool_size = 75

; Minimum connections kept open (warm pool for faster response)
min_pool_size = 5

; Kill server connections idle longer than this
server_idle_timeout = 600

; Kill client connections idle longer than this
client_idle_timeout = 0    ; 0 = disabled (app manages its own connections)

; Silence logs for expected events
log_connections    = 0
log_disconnections = 0
log_pooler_errors  = 1

# /etc/pgbouncer/userlist.txt
# Format: "username" "md5hash"
# Generate hash: echo -n "passwordusername" | md5sum → prefix with "md5"
"appuser" "md5abc123..."

Your pg.Pool then points at PgBouncer instead of Postgres directly:

const pool = new Pool({
  // Port 6432 = PgBouncer, not 5432 = Postgres directly
  connectionString: process.env.DATABASE_URL,  // Points to PgBouncer host:6432
  max: 20,      // Per-process limit — PgBouncer handles the Postgres side
  statement_timeout: 5000,
});

What You Lose in Transaction Mode

Transaction pooling mode is not free. These features require a persistent server connection across multiple transactions — they break or behave unexpectedly:

Session-level **SET commands** — SET search_path = myschema applies to the session. In transaction mode, the connection is returned to the pool after each transaction, so session settings are lost. Use schema-qualified names instead: SELECT * FROM myschema.users.

Advisory locks — pg_advisory_lock() is session-scoped. Does not work in transaction mode. Use row-level locks with SELECT FOR UPDATE instead.

LISTEN/NOTIFY — requires a persistent connection. Route LISTEN/NOTIFY through a dedicated connection that bypasses PgBouncer, or use a separate Redis pub/sub instead.

Prepared statements — PREPARE is session-scoped. In transaction mode, disable them: options=-c statement_cache_mode=describe in the PgBouncer database string.

# pgbouncer.ini — disable prepared statements for transaction mode
[databases]
yourdb = host=127.0.0.1 port=5432 dbname=yourdb options=-c statement_cache_mode=describe

Or in your pg.Pool config:

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  // Disable prepared statements — not supported in PgBouncer transaction mode
  // When using Prisma, set: datasources.db.url contains ?pgbouncer=true
});

Monitoring Connection Health

-- Check current connection state in Postgres
SELECT
  state,
  COUNT(*)                        AS count,
  MAX(EXTRACT(EPOCH FROM (NOW() - query_start)))::int AS max_age_secs
FROM pg_stat_activity
WHERE datname = 'yourdb'
GROUP BY state
ORDER BY count DESC;

-- Connections by application
SELECT application_name, state, COUNT(*)
FROM pg_stat_activity
WHERE datname = 'yourdb'
GROUP BY application_name, state
ORDER BY COUNT(*) DESC;

What to look for:

idle count much higher than active → over-provisioned pool or idle connections not being released
idle in transaction count growing → queries running inside open transactions that have not committed
active count at max_connections → pool exhaustion imminent

Add to Prometheus (from the earlier metrics section) and alert on pg_pool_waiting > 5 for 30 seconds.

The Decision

Single process or container?
└── pg.Pool alone, max: 10-20, statement_timeout: 5000

Multiple processes/pods but total connections < 80% of max_connections?
└── pg.Pool alone, size it correctly per-process

Multiple pods OR serverless OR total connections near max_connections?
└── Add PgBouncer in transaction mode
    └── pg.Pool → PgBouncer (500 client connections)
    └── PgBouncer → Postgres (20-75 server connections)
    └── Audit: no advisory locks, no LISTEN/NOTIFY, no session SET

PgBouncer adds one more thing to operate and debug. Do not add it before you need it. Do add it before you hit FATAL: sorry, too many clients already in production.

Originally published on ZyVOP

Docker for Developers: Stop "It Works on My Machine" Forever

ZyVOP — Thu, 28 May 2026 07:21:38 +0000

Why Docker Matters for Developers

Before Docker, setting up a project on a new machine was a ritual of pain. Clone the repo. Install the right Node version. Oh wait, you need a specific version of PostgreSQL. And Redis. And now your global npm packages conflict with another project. And somehow it works fine on your colleague's MacBook but not on yours.

Docker eliminates this entirely. A container packages everything the app needs — the runtime, system libraries, dependencies, configuration — into a single portable unit. Run it on your laptop, your teammate's Linux machine, or a cloud server, and the behavior is identical. The environment is part of the code.

For teams, the productivity gain compounds. Onboarding goes from "follow this 20-step setup guide and pray" to docker compose up. New developers are productive within minutes, not days.

Containers vs Virtual Machines

Before going further, it helps to know what a container actually is — because it's not a virtual machine.

A virtual machine emulates an entire computer, including its own operating system kernel. It's heavy: VMs take minutes to boot and consume gigabytes of RAM.

A container shares the host machine's OS kernel but isolates the application's filesystem, processes, and network. It's lightweight: containers start in seconds and use only the memory your app actually needs.

Docker is the tool that creates and manages these containers. A Docker image is a read-only snapshot of a filesystem — your app's code, dependencies, and runtime baked in. A container is a running instance of that image. One image can run as many containers as you want simultaneously.

Writing Your First Dockerfile

A Dockerfile is the recipe for building your image. It's a text file with a sequence of instructions that Docker executes layer by layer.

Here's a basic Node.js Dockerfile:

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

EXPOSE 3000
CMD ["node", "src/index.js"]

Walking through each line:

FROM node:20-alpine — Every image starts from a base image. node:20-alpine is the official Node.js 20 image built on Alpine Linux, a minimal distro that keeps the image small (~170MB vs ~1GB for the full Debian-based image).

WORKDIR /app — Sets the working directory inside the container. All subsequent commands run from here.

COPY package*.json ./ — Copies package.json and package-lock.json into the container before copying source code. This is intentional — keep reading.

RUN npm ci — Installs dependencies. npm ci (clean install) is preferred over npm install in Docker because it's faster, deterministic, and respects the lockfile exactly.

COPY . . — Copies the rest of your source code into the container.

EXPOSE 3000 — Documents that the container listens on port 3000. This doesn't publish the port — it's metadata for whoever runs the container.

CMD ["node", "src/index.js"] — The default command to run when the container starts. Use the array form (exec form) rather than a string — it avoids running your process as a child of a shell, which causes issues with signal handling.

Understanding Layer Caching — The Most Important Docker Concept

Each instruction in a Dockerfile creates a layer. Docker caches each layer and only rebuilds from the point where something changed. This makes rebuilds dramatically faster — but only if you structure your Dockerfile to take advantage of it.

Consider what happens if you copy everything first and then install:

# 🚫 Bad — cache busts on every source code change
COPY . .
RUN npm ci

Every time you change a single line of source code, Docker invalidates the cache at the COPY step — and then re-runs npm ci, downloading all your dependencies again. On a project with 500 packages, that's painful.

The fix is to copy dependency files first and install, then copy source code:

# ✅ Good — dependencies only reinstall when package.json changes
COPY package*.json ./
RUN npm ci

COPY . .

Now when you change source code, Docker uses the cached layer for npm ci and only rebuilds from the COPY . . step onward. Your build goes from 60 seconds to 3 seconds.

This pattern applies to any ecosystem. In Python, copy requirements.txt and run pip install before copying source. In Go, copy go.mod and go.sum and run go mod download first. Same principle everywhere.

Multi-Stage Builds: Keeping Production Images Small

Your development image needs build tools, compilers, dev dependencies, and test frameworks. Your production image needs none of that — just the compiled output and runtime dependencies. Multi-stage builds let you use a heavy image for building and copy only the result into a minimal final image.

Here's a TypeScript app with a multi-stage build:

# ── Stage 1: Build ────────────────────────────────────
FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY tsconfig.json ./
COPY src ./src
RUN npm run build          # Outputs compiled JS to /app/dist

# ── Stage 2: Production ───────────────────────────────
FROM node:20-alpine AS production

WORKDIR /app

# Only copy production dependencies
COPY package*.json ./
RUN npm ci --omit=dev

# Copy compiled output from the builder stage
COPY --from=builder /app/dist ./dist

EXPOSE 3000
CMD ["node", "dist/index.js"]

The final image contains only the Alpine base, production node_modules, and your compiled code. No TypeScript compiler, no source files, no dev dependencies. A typical image shrinks from 800MB to under 150MB. Smaller images mean faster pulls, smaller attack surfaces, and lower storage costs.

The .dockerignore File

Just like .gitignore, a .dockerignore file tells Docker what to exclude when copying your project into the image. Without it, you're copying node_modules (hundreds of MB), .git history, test files, and local env files into every build context — which slows down builds and risks leaking sensitive files.

# .dockerignore
node_modules
.git
.gitignore
*.md
.env
.env.*
dist
coverage
.nyc_output
.DS_Store
Dockerfile*
docker-compose*

Always create this file before your first docker build. It's one of those things that's much easier to add upfront than to chase down why your builds are slow later.

Docker Compose: Running Multi-Service Apps Locally

Real applications don't run in isolation. They have a database, a cache, maybe a message queue, maybe a background worker. Docker Compose lets you define and run all of these together in a single configuration file.

Here's a docker-compose.yml for a Node.js app with PostgreSQL and Redis:

services:

  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: development
      DATABASE_URL: postgresql://postgres:password@db:5432/myapp
      REDIS_URL: redis://cache:6379
    volumes:
      - .:/app
      - /app/node_modules
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    command: npm run dev

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: myapp
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  cache:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres_data:

A few things worth understanding here:

volumes: - .:/app — This mounts your local source code directory into the container at /app. When you edit a file on your host machine, the change is immediately reflected inside the container. Combined with a dev server that watches for file changes (like nodemon), you get hot reloading inside Docker.

- /app/node_modules — This is an anonymous volume that prevents the host's node_modules from overwriting the container's. Without this, your macOS node_modules would overwrite the Linux ones inside the container, causing native module failures.

depends_on** with **condition: service_healthy — This tells Docker to wait until the database passes its healthcheck before starting the app. Without this, your app might start before PostgreSQL is ready to accept connections, resulting in a connection error on boot.

postgres_data** named volume** — Database data is stored in a named volume managed by Docker, not in your project directory. This persists across container restarts and docker compose down commands. Running docker compose down -v removes the volumes too — useful for a clean reset.

To start everything:

docker compose up          # Start all services, watch logs
docker compose up -d       # Start in background (detached)
docker compose down        # Stop and remove containers
docker compose down -v     # Stop, remove containers AND volumes (full reset)

Useful Docker Commands You'll Actually Use

Running commands inside a container:

# Open a shell in a running container
docker compose exec app sh

# Run a one-off command (e.g. database migration)
docker compose exec app npm run migrate

# Run a command in a new container (not the running one)
docker compose run --rm app npm run seed

Inspecting what's happening:

# Follow logs for all services
docker compose logs -f

# Follow logs for a specific service
docker compose logs -f app

# See running containers and resource usage
docker stats

Cleaning up:

# Remove stopped containers, unused networks, dangling images
docker system prune

# Remove everything including unused images (be careful)
docker system prune -a

Rebuilding after Dockerfile changes:

# Force a rebuild without cache
docker compose build --no-cache
docker compose up --build

Development vs Production Compose Files

You'll often want slightly different configurations for development and production — maybe development has volume mounts and a dev server, while production uses the built image. Docker Compose supports this with file layering:

# Base config used everywhere
docker-compose.yml

# Development overrides
docker-compose.dev.yml

# Production overrides
docker-compose.prod.yml

Run with a specific override:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up

Or set COMPOSE_FILE in your .env:

COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml

This keeps the shared configuration DRY while allowing environment-specific differences.

Summary

Docker gives you reproducible environments, consistent behavior across machines, and a clean way to run complex multi-service applications locally without installing anything directly on your host. The key concepts to internalize: layer caching makes builds fast (copy dependency files before source code), multi-stage builds keep production images lean, .dockerignore prevents bloated build contexts, and Docker Compose orchestrates multi-service apps with a single command.

Once Docker becomes part of your workflow, you'll wonder how you ever managed without it. Onboarding new developers, reproducing bugs, running integration tests — all of it gets simpler when the environment is defined in code.

Originally published on ZyVOP

Node.js Performance Profiling: Finding the Bottleneck Before Your Users Do

ZyVOP — Wed, 27 May 2026 15:22:51 +0000

There is a specific kind of production bug that is worse than a crash: a performance regression. A crash is visible. It pages someone, generates an error in Sentry, and gets fixed. A performance regression sits in the background — requests take 400ms instead of 80ms, the event loop lags under load, a specific endpoint times out occasionally. Users leave. Support tickets accumulate. The team assumes it is infrastructure.

It is almost never infrastructure. It is almost always code.

This guide covers the full profiling workflow: identifying the problem from metrics, profiling the CPU and event loop, reading flame graphs, and fixing the specific patterns responsible for most Node.js performance regressions.

Know What You Are Looking For First

Before profiling, you need to know which metric is degraded. Guessing which code to optimize without measurement is how you spend a day optimizing a function that runs 10 times per day.

The signals that indicate specific problems:

High CPU, slow requests → CPU-bound work blocking the event loop. Look for synchronous operations, expensive computations, or tight loops.

Normal CPU, high latency → I/O-bound or event loop lag. Look for unoptimized database queries, N+1 patterns, missing indexes, or slow external API calls.

Memory climbing → Leak. See the memory leaks guide.

High CPU under moderate load → Garbage collector thrashing. Many short-lived allocations, or large objects being created repeatedly.

Specific endpoint slow, others fine → Query or logic problem scoped to that code path. Profile that endpoint specifically.

The Tools

clinic.js — the most useful suite for Node.js profiling. Three tools in one:

clinic doctor — identifies the category of problem (CPU, I/O, memory, event loop)
clinic flame — CPU flame graph, shows where time is spent
clinic bubbleprof — async profiling, shows where the event loop waits

0x — single-command flame graphs. Faster to use than clinic when you already know it is a CPU issue.

--prof** + **node --prof-process — V8's built-in profiler, no dependencies required, produces similar data to flame graphs.

npm install -g clinic 0x autocannon

Step 1 — clinic doctor (Diagnose First)

clinic doctor runs your app under load and produces a report that tells you which category of problem you have before you spend time on the wrong kind of profiling.

# Start your app under clinic doctor
clinic doctor -- node src/server.js

# In another terminal, apply load
autocannon -c 100 -d 30 http://localhost:3000/api/orders

After the load stops, clinic doctor opens a report in your browser showing:

Event loop delay — if high, you have synchronous blocking or very heavy async operations
CPU usage — if consistently at 100%, you have CPU-bound work
Memory — if climbing, you have a leak
Handles/requests — if handles grow without requests growing proportionally, something is not being cleaned up

The report recommends which clinic tool to use next. Follow it.

Step 2 — clinic flame (CPU Profiling)

When doctor indicates a CPU problem, clinic flame produces a flame graph — a visualization where the width of each bar represents how much CPU time that function consumed.

clinic flame -- node src/server.js

# Apply focused load on the slow endpoint
autocannon -c 50 -d 20 http://localhost:3000/api/search?q=laptop

Reading a flame graph:

The bottom of the graph is the call stack entry point
Each bar above represents a function called by the one below it
Width = time spent in that function (wider = more time)
The top of each stack is where execution was when the sample was taken
Look for wide bars near the top — these are the expensive functions

Common patterns in Node.js flame graphs:

Wide bar in JSON.parse or JSON.stringify — you are serializing large objects frequently. Consider streaming responses or reducing payload size.

Wide bar in a regex function — a regex is more expensive than expected, often because it is catastrophically backtracking. Test your regexes with rexploit or similar.

Wide bar in bcrypt or crypto — expected for hashing, but if it is in the hot path (every request, not just login), something is wrong.

Wide bar in your own business logic — investigate that function. Is it doing a computation that could be cached? Is it called more often than expected?

# Profile a specific script rather than a server
0x --open -- node src/scripts/generate-report.js

Step 3 — clinic bubbleprof (Async/I/O Profiling)

When doctor indicates I/O or event loop problems — not CPU — use bubbleprof. It shows where your code is waiting, not where it is running.

clinic bubbleprof -- node src/server.js
autocannon -c 50 -d 20 http://localhost:3000/api/orders

Bubbleprof shows a graph of async operations — database queries, HTTP calls, file I/O — and how long each one takes. Wide nodes are long waits.

What to look for:

Sequential awaits that could be parallel:

// SLOW — these run one after another
const user    = await getUser(userId);
const orders  = await getOrders(userId);
const profile = await getProfile(userId);
// Total time: getUser + getOrders + getProfile

// FAST — these run in parallel
const [user, orders, profile] = await Promise.all([
  getUser(userId),
  getOrders(userId),
  getProfile(userId),
]);
// Total time: max(getUser, getOrders, getProfile)

Missing connection pool configuration: If database operations show up as long waits, check your pool size. The default pg pool is 10 connections. Under 100 concurrent requests, requests queue waiting for a connection.

const pool = new Pool({
  connectionString: env.DATABASE_URL,
  max:             20,              // Increase pool size
  idleTimeoutMillis: 30_000,
  connectionTimeoutMillis: 5_000,  // Fail fast if no connection available
});

Step 4 — Event Loop Monitoring in Production

Flame graphs are taken in controlled environments. Production can behave differently. Add event loop lag monitoring to your metrics so you see regressions as they happen:

// src/lib/metrics.ts
import { monitorEventLoopDelay } from 'perf_hooks';

const histogram = monitorEventLoopDelay({ resolution: 20 });
histogram.enable();

// Gauge for Prometheus
const eventLoopLag = new client.Gauge({
  name: 'nodejs_event_loop_lag_p99_ms',
  help: 'Node.js event loop lag 99th percentile in milliseconds',
});

// Sample every 10 seconds
setInterval(() => {
  // histogram values are in nanoseconds
  const p99Ms = histogram.percentile(99) / 1_000_000;
  eventLoopLag.set(p99Ms);
  histogram.reset();
}, 10_000);

Event loop lag above 100ms is a warning. Above 500ms, users are noticeably affected. Above 1000ms, requests are timing out.

Step 5 — The Common Fixes

Synchronous Operations in the Hot Path

// BLOCKS the event loop — no other requests can be handled during this
const data = fs.readFileSync('/large/file.json');
const parsed = JSON.parse(data);

// Non-blocking — event loop stays free
const data = await fs.promises.readFile('/large/file.json', 'utf-8');
const parsed = JSON.parse(data);

Never use *Sync functions (readFileSync, execSync, writeFileSync) in request handlers. They block the entire Node.js event loop for their duration.

Expensive Computations

Move CPU-intensive work off the main thread:

import { Worker, isMainThread, parentPort, workerData } from 'worker_threads';

// In your route handler
function runInWorker(scriptPath: string, data: unknown): Promise {
  return new Promise((resolve, reject) => {
    const worker = new Worker(scriptPath, { workerData: data });
    worker.on('message', resolve);
    worker.on('error', reject);
    worker.on('exit', (code) => {
      if (code !== 0) reject(new Error(`Worker exited with code ${code}`));
    });
  });
}

// For truly CPU-intensive work (report generation, image processing):
router.post('/reports/generate', authenticate, async (req, res) => {
  const report = await runInWorker('./workers/reportGenerator.js', {
    tenantId: req.tenant.id,
    params:   req.body,
  });
  res.json(report);
});

Reducing Allocations in Hot Paths

Object and array allocations in tight loops create GC pressure. Reuse objects where possible:

// Creates a new object on every request — GC pressure at scale
app.use((req, res, next) => {
  req.context = {
    requestId: randomUUID(),
    startTime: Date.now(),
    user:      null,
  };
  next();
});

// Acceptable — the allocation is necessary. But avoid allocating
// inside loops or functions called thousands of times per second.
// Profile first. Optimize only what the flame graph shows is hot.

Caching Repeated Computations

// Recomputed on every request — if this is slow, cache it
async function getMenuItems(tenantId: string) {
  return db.query('SELECT * FROM menu_items WHERE tenant_id = $1', [tenantId]);
}

// Cache with LRU — computed once, served from memory
import { LRUCache } from 'lru-cache';

const menuCache = new LRUCache({
  max: 100,
  ttl: 5 * 60 * 1000,  // 5 minutes
});

async function getMenuItems(tenantId: string) {
  const cached = menuCache.get(tenantId);
  if (cached) return cached;

  const result = await db.query(
    'SELECT * FROM menu_items WHERE tenant_id = $1',
    [tenantId]
  );
  menuCache.set(tenantId, result.rows);
  return result.rows;
}

The Profiling Workflow in One Sequence

1. Detect: Grafana shows event loop lag or p99 latency spike
                ↓
2. Reproduce: Identify which endpoint or operation is slow
                ↓
3. Diagnose: clinic doctor → which category (CPU, I/O, memory, event loop)
                ↓
4. Profile:
   CPU issue  → clinic flame or 0x
   I/O issue  → clinic bubbleprof
   Memory     → heap snapshots (see memory leaks guide)
                ↓
5. Identify: Find the wide bar in the flame graph or the long wait in bubbleprof
                ↓
6. Fix: Apply the appropriate pattern (parallel awaits, caching, worker thread, remove sync op)
                ↓
7. Verify: Run autocannon before and after. Compare p99 latency.
                ↓
8. Monitor: Confirm event loop lag drops in Grafana after deploy

Profiling is not something you do once. Set up the metrics, watch them in production, and run a profiling session when they degrade. The regression that would have taken days to diagnose by reading code takes 30 minutes when you can see exactly where time is being spent.

Originally published on ZyVOP