Server Connection Types

Overview

Poge uses two primary interfaces for managing PostgreSQL server connections: ServerConnection for stored connections with metadata, and ServerFormData for connection form input.

ServerConnection

Represents a saved PostgreSQL server connection with full metadata.

Interface Definition

From /types/server.ts:1-14:

export interface ServerConnection {
  id: string
  name: string
  host: string
  port: number
  database: string
  username: string
  password: string
  sslMode?: "disable" | "require" | "prefer"
  connected: boolean
  favorite?: boolean
  createdAt: Date
  lastConnected?: Date
}

Fields

string

required

Unique identifier for the connection (UUID)Example: "550e8400-e29b-41d4-a716-446655440000"

name

string

required

Human-readable connection nameExample: "Production Database", "Local Dev"

host

string

required

PostgreSQL server hostname or IP addressExample: "localhost", "db.example.com"

port

number

required

PostgreSQL server port numberDefault: 5432

database

string

required

Target database nameExample: "myapp_production"

username

string

required

PostgreSQL username for authenticationExample: "postgres", "app_user"

password

string

required

PostgreSQL user password

Stored in plain text. Use secure storage mechanisms in production.

sslMode

string

SSL connection modeOptions:

"disable" - No SSL
"require" - Require SSL (allows self-signed certificates)
"prefer" - Try SSL first, fallback to non-SSL

Default: "disable"

connected

boolean

required

Current connection status

true - Connection is active/established
false - Connection is inactive

favorite

boolean

Whether connection is marked as favoriteUsed for sorting/filtering in UI

createdAt

Date

required

Timestamp when connection was createdExample: new Date("2024-01-15T10:30:00Z")

lastConnected

Date

Timestamp of last successful connectionundefined if never connected

Example

const connection: ServerConnection = {
  id: "550e8400-e29b-41d4-a716-446655440000",
  name: "Production Database",
  host: "db.example.com",
  port: 5432,
  database: "myapp_production",
  username: "postgres",
  password: "secure_password",
  sslMode: "require",
  connected: true,
  favorite: true,
  createdAt: new Date("2024-01-15T10:30:00Z"),
  lastConnected: new Date("2024-03-20T14:25:00Z")
}

Use Cases

Connection List: Display saved connections in sidebar
Connection Switching: Switch between multiple databases
Recent Connections: Sort by lastConnected for quick access
Favorites: Filter favorite connections for quick access

ServerFormData

Represents form input data for creating or editing server connections.

Interface Definition

From /types/server.ts:16-25:

export interface ServerFormData {
  name: string
  host: string
  port: number
  database: string
  username: string
  password: string
  sslMode?: "disable" | "require" | "prefer"
  connectionString?: string
}

Fields

name

string

required

Human-readable connection name

host

string

required

PostgreSQL server hostname or IP address

port

number

required

PostgreSQL server port number

database

string

required

Target database name

username

string

required

PostgreSQL username for authentication

password

string

required

PostgreSQL user password

sslMode

string

SSL connection mode ("disable", "require", "prefer")

connectionString

string

PostgreSQL connection string (alternative to individual fields)Format: postgresql://username:password@host:port/database?sslmode=requireWhen provided, parsed into individual fields

Example

const formData: ServerFormData = {
  name: "Local Development",
  host: "localhost",
  port: 5432,
  database: "myapp_dev",
  username: "postgres",
  password: "devpassword",
  sslMode: "disable"
}

Connection String Example

const formDataWithConnectionString: ServerFormData = {
  name: "Production via Connection String",
  connectionString: "postgresql://postgres:securepass@db.example.com:5432/myapp_production?sslmode=require",
  host: "", // Parsed from connectionString
  port: 0,  // Parsed from connectionString
  database: "",
  username: "",
  password: ""
}

Use Cases

Connection Form: Capture user input for new connections
Connection Editing: Update existing connection properties
Connection String Import: Parse PostgreSQL connection strings
Form Validation: Validate required fields before saving

Type Conversion

Convert ServerFormData to ServerConnection:

import { v4 as uuidv4 } from 'uuid';

function formDataToConnection(formData: ServerFormData): ServerConnection {
  return {
    id: uuidv4(),
    name: formData.name,
    host: formData.host,
    port: formData.port,
    database: formData.database,
    username: formData.username,
    password: formData.password,
    sslMode: formData.sslMode || "disable",
    connected: false,
    favorite: false,
    createdAt: new Date(),
    lastConnected: undefined
  };
}

Validation Example

function validateServerFormData(data: ServerFormData): string[] {
  const errors: string[] = [];
  
  if (!data.name?.trim()) errors.push("Name is required");
  if (!data.host?.trim()) errors.push("Host is required");
  if (!data.port || data.port < 1 || data.port > 65535) {
    errors.push("Port must be between 1 and 65535");
  }
  if (!data.database?.trim()) errors.push("Database is required");
  if (!data.username?.trim()) errors.push("Username is required");
  
  return errors;
}

Security Considerations

Password Storage: Both interfaces store passwords in plain text. For production use:

Encrypt passwords before storage
Use environment variables or secure vaults
Consider OAuth or certificate-based authentication
Never commit passwords to version control

Overview

Endpoints

Types

​Overview