pglens 1.0.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "pglens",
+  "version": "1.0.0",
+  "description": "A simple PostgreSQL database viewer tool",
+  "main": "src/server.js",
+  "bin": {
+    "pglens": "./bin/pglens"
+  },
+  "scripts": {
+    "start": "node bin/pglens"
+  },
+  "keywords": [
+    "postgresql",
+    "database",
+    "viewer",
+    "cli"
+  ],
+  "author": "Tekeshwar Singh (https://github.com/tsvillain)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tsvillain/pglens.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tsvillain/pglens/issues"
+  },
+  "homepage": "https://github.com/tsvillain/pglens#readme",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^11.1.0",
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "postgres": "^3.4.3"
+  }
+}

package/src/db/connection.js

@@ -0,0 +1,200 @@
+/**
+ * Database Connection Pool Manager
+ * 
+ * Manages PostgreSQL connection pool using postgres library.
+ * Provides connection pooling for efficient database access.
+ */
+
+const postgres = require('postgres');
+
+let sql = null;
+
+/**
+ * Create a wrapper that provides pg-compatible query interface.
+ * The postgres package uses a different API, so we wrap it to maintain compatibility.
+ * @param {object} sqlClient - The postgres client instance
+ * @returns {object} Wrapped client with .query() method
+ */
+function createPoolWrapper(sqlClient) {
+  return {
+    query: async (queryText, params) => {
+      const result = await sqlClient.unsafe(queryText, params || []);
+      return { rows: result };
+    },
+    end: () => sqlClient.end(),
+  };
+}
+
+/**
+ * Create a new connection pool.
+ * Closes existing pool if one exists.
+ * @param {string} connectionString - PostgreSQL connection string
+ * @param {string} sslMode - SSL mode: disable, require, prefer, verify-ca, verify-full
+ * @returns {Promise} The created connection wrapper
+ */
+function createPool(connectionString, sslMode = 'prefer') {
+  if (sql) {
+    sql.end();
+  }
+
+  const sslConfig = getSslConfig(sslMode);
+  const poolConfig = {
+    max: 10,
+    idle_timeout: 30,
+    connect_timeout: 10,
+  };
+
+  if (sslConfig !== null) {
+    poolConfig.ssl = sslConfig;
+  }
+
+  sql = postgres(connectionString, poolConfig);
+
+  // Test the connection
+  return sql`SELECT NOW()`
+    .then(() => {
+      console.log('✓ Connected to PostgreSQL database');
+      return createPoolWrapper(sql);
+    })
+    .catch((err) => {
+      console.error('✗ Failed to connect to PostgreSQL database:', err.message);
+      const recommendation = getSslModeRecommendation(err, sslMode);
+      if (recommendation) {
+        console.error(`\n💡 SSL Mode Recommendation: Try using --sslmode ${recommendation}`);
+        console.error(`   Current SSL mode: ${sslMode}`);
+        console.error(`   Suggested command: Add --sslmode ${recommendation} to your command\n`);
+      }
+      throw err;
+    });
+}
+
+/**
+ * Analyze connection error and recommend appropriate SSL mode.
+ * @param {Error} error - Connection error object
+ * @param {string} currentSslMode - Current SSL mode that failed
+ * @returns {string|null} Recommended SSL mode or null if not SSL-related
+ */
+function getSslModeRecommendation(error, currentSslMode) {
+  const errorMessage = error.message?.toLowerCase() || '';
+  const errorCode = error.code;
+  const errorStack = error.stack?.toLowerCase() || '';
+
+  // Certificate verification errors
+  if (
+    errorMessage.includes('certificate') ||
+    errorMessage.includes('self signed') ||
+    errorMessage.includes('unable to verify') ||
+    errorCode === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE' ||
+    errorCode === 'SELF_SIGNED_CERT_IN_CHAIN'
+  ) {
+    if (currentSslMode === 'verify-full' || currentSslMode === 'verify-ca') {
+      return 'require';
+    }
+    if (currentSslMode === 'prefer') {
+      return 'require';
+    }
+  }
+
+  // Hostname mismatch errors
+  if (
+    errorMessage.includes('hostname') ||
+    errorMessage.includes('host name') ||
+    errorCode === 'ERR_TLS_CERT_ALTNAME_INVALID'
+  ) {
+    if (currentSslMode === 'verify-full') {
+      return 'verify-ca';
+    }
+    return 'require';
+  }
+
+  // SSL/TLS protocol errors (but not connection refused, which is handled separately)
+  if (
+    (errorMessage.includes('ssl') ||
+      errorMessage.includes('tls') ||
+      errorMessage.includes('protocol') ||
+      errorStack.includes('ssl')) &&
+    errorCode !== 'ECONNREFUSED'
+  ) {
+    // If SSL is enabled and failing, try disabling
+    if (currentSslMode !== 'disable' && currentSslMode !== 'prefer') {
+      // First try prefer (allows fallback to non-SSL)
+      if (currentSslMode === 'require' || currentSslMode === 'verify-ca' || currentSslMode === 'verify-full') {
+        return 'prefer';
+      }
+    }
+    // If prefer failed, try disable
+    if (currentSslMode === 'prefer') {
+      return 'disable';
+    }
+  }
+
+  // Connection refused might indicate SSL requirement
+  if (errorCode === 'ECONNREFUSED' || errorMessage.includes('connection refused')) {
+    // If SSL is disabled, server might require SSL
+    if (currentSslMode === 'disable') {
+      return 'prefer';
+    }
+  }
+
+  // Connection timeout with SSL might need different mode
+  if (
+    (errorCode === 'ETIMEDOUT' || errorMessage.includes('timeout')) &&
+    currentSslMode !== 'disable'
+  ) {
+    return 'prefer';
+  }
+
+  return null;
+}
+
+/**
+ * Get SSL configuration based on SSL mode.
+ * @param {string} sslMode - SSL mode string
+ * @returns {object|null} SSL configuration object or null to disable SSL
+ */
+function getSslConfig(sslMode) {
+  switch (sslMode?.toLowerCase()) {
+    case 'disable':
+      return null;
+    case 'require':
+      return { rejectUnauthorized: false };
+    case 'prefer':
+      return { rejectUnauthorized: false };
+    case 'verify-ca':
+      return { rejectUnauthorized: true };
+    case 'verify-full':
+      return { rejectUnauthorized: true };
+    default:
+      return { rejectUnauthorized: false };
+  }
+}
+
+/**
+ * Get the current connection pool.
+ * @returns {object} The connection pool wrapper
+ * @throws {Error} If pool is not initialized
+ */
+function getPool() {
+  if (!sql) {
+    throw new Error('Database pool not initialized. Call createPool first.');
+  }
+  return createPoolWrapper(sql);
+}
+
+/**
+ * Close the connection pool gracefully.
+ * @returns {Promise} Promise that resolves when pool is closed
+ */
+function closePool() {
+  if (sql) {
+    return sql.end();
+  }
+  return Promise.resolve();
+}
+
+module.exports = {
+  createPool,
+  getPool,
+  closePool,
+};
+

package/src/routes/api.js

@@ -0,0 +1,200 @@
+/**
+ * API Routes
+ * 
+ * RESTful API endpoints for database operations.
+ * 
+ * Endpoints:
+ * - GET /api/tables - List all tables in the database
+ * - GET /api/tables/:tableName - Get paginated table data
+ * 
+ * Features:
+ * - SQL injection prevention via table name sanitization
+ * - Cursor-based pagination for efficient large table navigation
+ * - Automatic primary key detection for optimized pagination
+ */
+
+const express = require('express');
+const { getPool } = require('../db/connection');
+
+const router = express.Router();
+
+/**
+ * Sanitize table name to prevent SQL injection.
+ * Only allows alphanumeric characters, underscores, and dots.
+ * @param {string} tableName - Table name to sanitize
+ * @returns {string} Sanitized table name
+ * @throws {Error} If table name contains invalid characters
+ */
+function sanitizeTableName(tableName) {
+  if (!/^[a-zA-Z0-9_.]+$/.test(tableName)) {
+    throw new Error('Invalid table name');
+  }
+  return tableName;
+}
+
+/**
+ * GET /api/tables
+ * 
+ * Returns a list of all tables in the public schema.
+ * Only returns BASE TABLE types (excludes views, sequences, etc.).
+ * 
+ * Response: { tables: string[] }
+ */
+router.get('/tables', async (req, res) => {
+  try {
+    const pool = getPool();
+    const result = await pool.query(`
+      SELECT table_name 
+      FROM information_schema.tables 
+      WHERE table_schema = 'public' 
+      AND table_type = 'BASE TABLE'
+      ORDER BY table_name;
+    `);
+
+    const tables = result.rows.map(row => row.table_name);
+    res.json({ tables });
+  } catch (error) {
+    console.error('Error fetching tables:', error);
+    res.status(500).json({ error: error.message });
+  }
+});
+
+/**
+ * Get the primary key column name for a table.
+ * Used to enable cursor-based pagination for better performance.
+ * @param {Pool} pool - Database connection pool
+ * @param {string} tableName - Name of the table
+ * @returns {Promise<string|null>} Primary key column name or null if no primary key exists
+ */
+async function getPrimaryKeyColumn(pool, tableName) {
+  try {
+    const pkQuery = `
+    SELECT kcu.column_name
+    FROM information_schema.table_constraints tc
+    JOIN information_schema.key_column_usage kcu
+      ON tc.constraint_name = kcu.constraint_name
+      AND tc.table_schema = kcu.table_schema
+    WHERE tc.constraint_type = 'PRIMARY KEY'
+      AND tc.table_name = $1
+      AND tc.table_schema = 'public'
+    LIMIT 1;
+    `;
+    const result = await pool.query(pkQuery, [tableName]);
+    const pkColumn = result.rows.length > 0 ? result.rows[0].column_name : null;
+    return pkColumn;
+  } catch (error) {
+    console.error('Error getting primary key:', error);
+    return null;
+  }
+}
+
+/**
+ * GET /api/tables/:tableName
+ * 
+ * Returns paginated table data with support for cursor-based pagination.
+ * 
+ * Query parameters:
+ * - page: Page number (default: 1)
+ * - limit: Rows per page (default: 100)
+ * - cursor: Cursor value for cursor-based pagination (optional)
+ * 
+ * Pagination strategy:
+ * - If table has primary key and cursor is provided: Use cursor-based pagination (WHERE id > cursor)
+ * - If table has primary key and page=1: Start from beginning, return cursor for next page
+ * - Otherwise: Use OFFSET-based pagination (for backward nav, page jumps, or tables without PK)
+ * 
+ * Response: {
+ *   rows: Object[],
+ *   totalCount: number,
+ *   page: number,
+ *   limit: number,
+ *   isApproximate: boolean,
+ *   nextCursor: string|null,
+ *   hasPrimaryKey: boolean
+ * }
+ */
+router.get('/tables/:tableName', async (req, res) => {
+  try {
+    const tableName = sanitizeTableName(req.params.tableName);
+    const page = parseInt(req.query.page || '1', 10);
+    const limit = parseInt(req.query.limit || '100', 10);
+    const cursor = req.query.cursor;
+
+    if (page < 1 || limit < 1) {
+      return res.status(400).json({ error: 'Page and limit must be positive integers' });
+    }
+
+    const pool = getPool();
+    const primaryKeyColumn = await getPrimaryKeyColumn(pool, tableName);
+
+    const countQuery = `SELECT COUNT(*) as total FROM "${tableName}"`;
+    const countResult = await pool.query(countQuery);
+    const totalCount = parseInt(countResult.rows[0].total, 10);
+    const isApproximate = false;
+
+    let dataResult;
+    let nextCursor = null;
+
+    if (primaryKeyColumn && cursor) {
+      // Cursor-based pagination: WHERE id > cursor (most efficient for forward navigation)
+      const cursorQuery = `SELECT * FROM "${tableName}" WHERE "${primaryKeyColumn}" > $1 ORDER BY "${primaryKeyColumn}" ASC LIMIT $2`;
+      const cursorParams = [cursor, limit];
+      dataResult = await pool.query(cursorQuery, cursorParams);
+
+      if (dataResult.rows.length > 0) {
+        const lastRow = dataResult.rows[dataResult.rows.length - 1];
+        nextCursor = lastRow[primaryKeyColumn];
+      }
+    } else if (primaryKeyColumn && page === 1) {
+      // First page with primary key: start from beginning, return cursor
+      const firstPageQuery = `SELECT * FROM "${tableName}" ORDER BY "${primaryKeyColumn}" ASC LIMIT $1`;
+      const firstPageParams = [limit];
+      dataResult = await pool.query(firstPageQuery, firstPageParams);
+
+      if (dataResult.rows.length > 0) {
+        const lastRow = dataResult.rows[dataResult.rows.length - 1];
+        nextCursor = lastRow[primaryKeyColumn];
+      }
+    } else {
+      // Fallback to OFFSET-based pagination
+      // Used for: backward navigation, page jumps, or tables without primary key
+      const offset = (page - 1) * limit;
+      let query;
+      const queryParams = [];
+
+      if (primaryKeyColumn) {
+        // Order by primary key for consistent results
+        query = `SELECT * FROM "${tableName}" ORDER BY "${primaryKeyColumn}" ASC LIMIT $1 OFFSET $2`;
+        queryParams.push(limit, offset);
+      } else {
+        // No primary key: no ordering guarantee
+        query = `SELECT * FROM "${tableName}" LIMIT $1 OFFSET $2`;
+        queryParams.push(limit, offset);
+      }
+      dataResult = await pool.query(query, queryParams);
+
+      // Calculate cursor for next page if primary key exists
+      if (primaryKeyColumn && dataResult.rows.length > 0) {
+        const lastRow = dataResult.rows[dataResult.rows.length - 1];
+        nextCursor = lastRow[primaryKeyColumn];
+      }
+    }
+
+    const responseData = {
+      rows: dataResult.rows,
+      totalCount,
+      page,
+      limit,
+      isApproximate,
+      nextCursor,
+      hasPrimaryKey: !!primaryKeyColumn,
+    };
+    res.json(responseData);
+  } catch (error) {
+    console.error('Error fetching table data:', error);
+    res.status(500).json({ error: error.message });
+  }
+});
+
+module.exports = router;
+

package/src/server.js

@@ -0,0 +1,62 @@
+/**
+ * pglens Server
+ * 
+ * Express server that serves the web UI and provides API endpoints
+ * for querying PostgreSQL database tables.
+ * 
+ * Features:
+ * - RESTful API for table listing and data retrieval
+ * - Static file serving for the client application
+ * - CORS enabled for development
+ * - Graceful shutdown handling
+ */
+
+const express = require('express');
+const cors = require('cors');
+const path = require('path');
+const { createPool, closePool } = require('./db/connection');
+const apiRoutes = require('./routes/api');
+
+/**
+ * Start the Express server.
+ * @param {string} connectionString - PostgreSQL connection string
+ * @param {number} port - Port number to listen on
+ * @param {string} sslMode - SSL mode for database connection
+ */
+function startServer(connectionString, port, sslMode) {
+  const app = express();
+
+  app.use(cors());
+  app.use(express.json());
+
+  createPool(connectionString, sslMode)
+    .then(() => {
+      app.use('/api', apiRoutes);
+
+      const clientPath = path.join(__dirname, '../client');
+      app.use(express.static(clientPath));
+
+      app.get('*', (_, res) => {
+        res.sendFile(path.join(clientPath, 'index.html'));
+      });
+
+      app.listen(port, () => {
+        console.log(`✓ Server running on http://localhost:${port}`);
+        console.log(`  Open your browser to view your database`);
+      });
+
+      process.on('SIGINT', () => {
+        console.log('\nShutting down...');
+        closePool().then(() => {
+          process.exit(0);
+        });
+      });
+    })
+    .catch((error) => {
+      console.error('Failed to start server:', error.message);
+      process.exit(1);
+    });
+}
+
+module.exports = { startServer };
+