PostgreSQL Integration Tests in 3s (No Docker Needed)

We test our entire tRPC backend 18 tables, foreign keys, JSONB columns, array types without Docker, without a real PostgreSQL server, and without any external infrastructure.

The database runs inside the test process. It's PostgreSQL compiled to WebAssembly. And it works.

Repo: https://github.com/rogasper/labas-bahasa﻿

Key Takeaways

•PGlite (@electric-sql/pglite) runs PostgreSQL in-memory via WebAssembly no Docker, no Testcointainers, no external databases needed. Combined with Bun's mock.module for dependency injection, it enables full integration tests that run in under 3 seconds.

•The pattern: create 18 tables via raw SQL in a test setup file, mock @labas/db to return the PGlite-based Drizzle instance, then use tRPC's createCaller to test routers end-to-end with real SQL queries.

•Real integration tests verify business logic timing a 5-second minimum timer validation test uses Bun.sleep(4500) to satisfy the constraint, proving the test runner can handle async timing-sensitive code.

The Problem: Integration Tests Need a Real Database

Unit tests are easy. Mock the database, test the logic, done. But integration test the ones that verify your tRPC routers actually execute correct SQL against real tables need a real database.

The traditional approaches:

1.Docker Compose: spin up a PostgreSQL container, run migrations, seed data, test, tear down. Slow, requires Docker, flaky in CI.

2.Testcontainers: programmatically start a Docker container per test suite, Better, but still requires Docker.

3.SQLite: swap PostgreSQL for SQLite in tests. Fast, but SQLite doesn't support JSONB, array types, or gen_random_uuid() so your tests don't match production.

4.Shared test database: one PostgreSQL instance for all tests. Fast, but tests interfere with each other, and you need cleanup logic.

We chose a fifth option: PGlite PostgreSQL compiled to WebAssembly, running in-process.

What Is PGlite?

PGlite is an open-source project by Electric SQL that compiles PostgreSQL to WebAssembly. It runs entirely in memory no network, no external process, no Docker. You import it like any npm package:

That's it. You now have a PostgreSQL database running inside your Javascript process. It supports JSONB, array types, foreign keys, gen_random_uuid(), and most PostgreSQL features. It just doesn't persist to disk which is perfect for tests.

Our finding: PGlite test setup takes ~200ms for 18 tables. Docker-based setup takes ~5-10 seconds (container pull + start + migrate). For a test suite with 12 test cases, that's a 25x speedup in setup time alone.

The Setup: 14 Tables in 90 lines

Our test setup file (packages/api/src/__tests__/test-setup.ts) creates all 14 application tables via raw SQL:

Why raw SQL instead of Drizzle's migration system? Because drizzle-kit push requires a separate CLI process. In tests, we want everything in-process. Raw SQL is verbose but fast and the schema is stable enough that we don't change it often.

We also have a second setup file (test-db.ts) that uses a slightly different approach enabling the pgcrypto extension explicity for gen_random_uuid():

This inconsistency shows the project evolving its test strategy. The first setup file works because PGlite includes pgcrypto by default. The second is more explicit. Both work.

The Magic: Bun's mock.module

Here's where it gets clever. Our application code imports the database from @labas/db:

In tests, we intercept that import and replace it with our PGlite-based instance:

When the tRPC router imports @labas/db, it gets our test database instead of the real one. No code changes needed in the router. No dependency injection framework. Just module mocking.

We also mock environment variables:

This prevents the env validation from failing during tests it expects real values, but we're running in-memory.

The Test: tRPC Router Integration

With the database and end mocked, we can test tRPC routers end-to-end:

The createCaller pattern is tRPC's built-in test utility. It creates a caller object that invokes router procedures directly no HTTP layer, no network. Combined with PGlite, the entire test runs in-process.

Anti-Cheat Testing: The 5-Second Timer

One of our business rules: you can't finish an exam in under 5 seconds. The test verifies this with Bun.sleep():

The test sleeps for 4.5 seconds to satisfy the 5-second minimum. The { timeout: 3000 } option gives Bun 30 seconds for the entire test case enough time for the sleep plus the database operations.

This is a genuine integration test. It verifies that the router's timing logic works correctly with real timestamps, real database inserts, and real score computation.

Rate Limiting Testing

Another test verifies rate limiting you can't start two exam attempts within 3 seconds:

The rate limiter uses an in-memory Map (not Redis, not a database table). The test works because the Map persist across test cases within the same process which is why each test uses a unique user label ("dup", "start", "strip") to avoid cross-test interference.

Comparison: PGlite vs Alternatives

Approach
Setup time
Docker needed
JSONB support
Array types
gen_random_uuid()
PGlite
~200ms
No
Yes
Yes
Yes
Docker Compose
~5-10s
Yes
Yes
Yes
Yes
Testcontainers
~10-15s
Yes
Yes
Yes
Yes
SQLite
~50ms
No
No
No
No
Shared PG
~0ms
Yes
Yes
Yes
Yes

PGlite wins on setup speed and zero infrastructure. The tradeoff: it's not a real PostgreSQL server, so edge cases (complex queries, performance characteristics) might differ. But for integration tests that verify business logic, it's more than sufficient.

What we learned: When we switched from Docker-based tests to PGlite, our CI test time dropped from ~45 seconds to ~12 seconds. The biggest win wasn't speed it was reliability. Docker containers occasionally fail to start in CI. PGlite never fails because it's just a Javascript import.

The Limitations

PGlite isn't perfect. Here's what we've encountered:

1.No extensions beyond pgcrypto. PGlite includes pgcrypto for gen_random_uuid(), but doesn't support PostGIS, full-text search extensions, or custom exntensions.

2.Memory limits. Since it runs in-process, large datasets can consume significant memory. For our test suite (~50 rows of seed data), it's fine. For load testing, you'd want a real database.

3.Two setup files. We have both test-setup.ts and test-db.ts a sign of evovling test strategy. They should eventually be consolidated.

4.Raw SQL schema. We maintain 14 CREATE TABLE statements manually instead of using Drizzle's migration system. When the schema changes, we update both Drizzle schema and the test SQL a potential drift point.

Frequently Asked Questions

Does PGlite work other test runners besides Bun?
Yes. PGlite is Javascript library it works with Jest, Vitest, Node's built-in test runner, or any environment that supports WebAssembly. We use bun because it's our runtime, but the PGlite pattern is test-runner-agnostic.
Can PGlite replace PostgreSQL in production?
No. PGlite is designed for testing and embedded use cases. It doesn't persist to disk, doesn't support concurrent connections, and lacks production features like connection pooling, replication, and backup. Use it for tests, not for your production database.
How do you handle schema migrations in test?
We don't yet. Currently, the test setup file has raw SQL that mirrors the Drizzle schema. When the schema changes, we update both, This is a known maintenance burden. A better approach would be to use drizzle-kit generate to produce SQL migrations, then apply them in the test setup. We're working on this.
What about testing the AI generation pipeline?
The AI pipeline (packages/ai/) is tested separately with mocked LLM responses. PGlite handles the database layer (tRPC routers), while the AI tests mock the OpenAICompatibleClient to return predefined JSON. The two test strategies complement each other.

Approach	Setup time	Docker needed	JSONB support	Array types	gen_random_uuid()
PGlite	~200ms	No	Yes	Yes	Yes
Docker Compose	~5-10s	Yes	Yes	Yes	Yes
Testcontainers	~10-15s	Yes	Yes	Yes	Yes
SQLite	~50ms	No	No	No	No
Shared PG	~0ms	Yes	Yes	Yes	Yes

How We Run Full PostgreSQL Integration Tests in 3 Seconds (Without Docker)

Key Takeaways

The Problem: Integration Tests Need a Real Database

What Is PGlite?

The Setup: 14 Tables in 90 lines

The Magic: Bun's mock.module

The Test: tRPC Router Integration

Anti-Cheat Testing: The 5-Second Timer

Rate Limiting Testing

Comparison: PGlite vs Alternatives

The Limitations

Frequently Asked Questions