Skip to main content
POST
/
api
/
test-connection
curl -X POST http://localhost:3000/api/test-connection \
  -H "Content-Type: application/json" \
  -d '{
    "host": "localhost",
    "port": 5432,
    "user": "postgres",
    "password": "mypassword",
    "database": "mydb",
    "sslMode": "disable"
  }'

{
  "success": true,
  "message": "Connection successful!"
}

​
Overview

Tests database connectivity with provided credentials. This endpoint validates that Poge can establish a connection to the PostgreSQL server and execute queries.

​
Request

​
host
string
required
PostgreSQL server hostname or IP addressExample: localhost, db.example.com, 192.168.1.100
​
port
number
required
PostgreSQL server port numberDefault: 5432
​
user
string
required
PostgreSQL username for authentication
​
password
string
PostgreSQL user passwordOptional for users without password authentication
​
database
string
Target database nameDefaults to postgres if not specified
​
sslMode
string
SSL connection modeOptions: disable, require, preferDefault: disable

​
Response

​
Success Response

​
success
boolean
Connection status (true for successful connections)
​
message
string
Human-readable success message

​
Error Response

​
success
boolean
Always false for errors
​
error
string
Error message describing the failure
​
details
string
Additional context about the error and resolution steps
​
code
string
PostgreSQL or system error code

​
Examples

​
Successful Connection

curl -X POST http://localhost:3000/api/test-connection \
  -H "Content-Type: application/json" \
  -d '{
    "host": "localhost",
    "port": 5432,
    "user": "postgres",
    "password": "mypassword",
    "database": "mydb",
    "sslMode": "disable"
  }'

{
  "success": true,
  "message": "Connection successful!"
}

​
Connection Refused

curl -X POST http://localhost:3000/api/test-connection \
  -H "Content-Type: application/json" \
  -d '{
    "host": "localhost",
    "port": 5433,
    "user": "postgres",
    "password": "mypassword"
  }'

{
  "success": false,
  "error": "Connection refused",
  "details": "Unable to connect to the database server. Please check if the server is running and the host/port are correct.",
  "code": "ECONNREFUSED"
}

​
Authentication Failed

{
  "success": false,
  "error": "Authentication failed",
  "details": "Invalid username or password.",
  "code": "28P01"
}

​
Database Not Found

{
  "success": false,
  "error": "Database does not exist",
  "details": "The specified database does not exist on the server. Try connecting without specifying a database or use a different database name.",
  "code": "3D000"
}

​
Missing Required Fields

{
  "success": false,
  "error": "Missing required fields: host, port, and user are required"
}

​
Error Codes

The endpoint returns specific error codes from PostgreSQL and the system:
CodeErrorDescription
ECONNREFUSEDConnection refusedServer is not running or port is incorrect
ENOTFOUNDHost not foundInvalid hostname or DNS resolution failed
ECONNRESETConnection resetSSL configuration mismatch
28P01Authentication failedInvalid username or password
3D000Database does not existSpecified database not found
28000Invalid authorizationUser lacks database access permissions

​
Implementation Details

From /app/api/test-connection/route.ts:15-30: 
const client = new Client({
  host,
  port,
  user,
  password,
  database: database || 'postgres', // Use postgres as default
  ssl: sslMode === "require" ? { rejectUnauthorized: false } : false,
  connectionTimeoutMillis: 5000, // 5 second timeout
})

await client.connect()
await client.query('SELECT 1') // Validate connection
await client.end()
The endpoint creates a new client connection (not pooled) to test credentials without affecting the connection pool.

​
Use Cases

  • Server Setup Form: Validate credentials before saving connection
  • Health Checks: Verify database availability
  • Connection Debugging: Identify connection issues with detailed errors