Summary

Fixes #28896

This PR fixes issue #28896 where $connect() succeeds even when PostgreSQL is stopped when using @prisma/adapter-pg. The root cause was that pg.Pool uses lazy connection initialization, so creating a pool doesn't actually establish a database connection until the first query is executed.

Problem

Before this fix:

const adapter = new PrismaPgAdapterFactory(config)
await prisma.$connect()  // ✅ Succeeds even when PostgreSQL is offline
await prisma.user.findMany()  // ❌ Fails here with connection error

Expected behavior:

const adapter = new PrismaPgAdapterFactory(config)
await prisma.$connect()  // ❌ Should fail immediately if database is unreachable

Root Cause

The PrismaPgAdapterFactory.connect() method only instantiated new pg.Pool(config) without validating the connection. Since pg.Pool uses lazy connection initialization, no actual connection attempt occurred until the first query execution, causing $connect() to succeed even when the database was offline.

Solution

Added a validateConnection() private method that executes SELECT 1 during the connect() phase to validate the database is reachable:

private async validateConnection(pool: pg.Pool): Promise<void> {
  const tag = '[js::validateConnection]'

  try {
    // SELECT 1 is the lightest query (best for connection validation)
    await pool.query('SELECT 1')
    debug(`${tag} Connection validated successfully`)
  } catch (e) {
    debug(`${tag} Connection failed: %O`, e)
    throw e
  }
}

This method is called in connect() before returning the adapter, ensuring that any connection errors are surfaced immediately during $connect() rather than being deferred to the first query.

Changes Made

packages/adapter-pg/src/pg.ts:

• Added validateConnection() private method (lines 318-329)
• Call validateConnection() in connect() before returning adapter (line 284)

packages/adapter-pg/src/__tests__/pg.test.ts:

• Added getTestConfig() helper to parse PostgreSQL connection URI from environment
• Refactored existing tests to use real PostgreSQL from Docker instead of mocks
• Added two regression tests for issue $connect() always succeeds in Prisma v7 using @prisma/adapter-pg even when DB is unreachable #28896:
  1. Test with unreachable database using reserved IP (192.0.2.1)
  2. Test with external pool that fails connection validation

Testing

Regression Tests:

it('should throw an error when database is unreachable during connect', async () => {
  const config: pg.PoolConfig = {
    user: 'test',
    password: 'test',
    database: 'test',
    host: '192.0.2.1', // TEST-NET-1 - reserved for documentation, guaranteed to be unreachable
    port: 54321,
    connectionTimeoutMillis: 100,
  }
  const factory = new PrismaPgAdapterFactory(config)

  await expect(factory.connect()).rejects.toThrow()
})

it('should throw an error when database connection fails with external pool', async () => {
  const mockPool = new pg.Pool({...})
  mockPool.query = vi.fn().mockRejectedValue(new Error('Connection refused'))

  const factory = new PrismaPgAdapterFactory(mockPool)
  await expect(factory.connect()).rejects.toThrow('Connection refused')

  await mockPool.end()
})

Test Requirements:

• Tests require Docker PostgreSQL to be running (postgres://prisma:prisma@localhost:5432/tests)
• Matches Prisma's CI/CD testing pattern
• Uses real database connections instead of mocks for integration testing

Behavior Changes

After this fix:

const adapter = new PrismaPgAdapterFactory(config)
await prisma.$connect()  // ❌ Now fails immediately if PostgreSQL is unreachable

This is the correct behavior and matches user expectations for connection validation.

Related Work

• Similar validation pattern exists in @prisma/adapter-mariadb which uses SELECT VERSION() for capability detection
• @prisma/adapter-neon has similar connection error handling tests

Breaking Changes

None. This is a bug fix that makes the behavior match documented expectations.

Additional Notes

The ECONNREFUSED error when Docker PostgreSQL is not running is expected and acceptable behavior - it confirms that the connection validation is working correctly and surfacing errors immediately during $connect() as intended.

Summary by CodeRabbit

• New Features

  • Added stronger connection validation and error handling to fail fast when the database or connection pool is unreachable.

• Tests

  • Consolidated test configuration and added cases verifying failures for unreachable databases and simulated pool connection errors.

_{✏️ Tip: You can customize this high-level summary in your review settings.}