pglens 1.1.0 → 2.0.1

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-01-01
+
+### Added
+
+- **Server-Side Sorting**: Table sorting is now performed on the database server, ensuring correct ordering across all data pages.
+- **Connection Parameters Mode**: New tabbed interface in connection dialog allowing separate input for Host, Port, User, Password, and Database.
+- **Global Loading Overlay**: Blocks user interaction during data fetching to prevent race conditions.
+- **Dynamic Port Selection**: Server automatically finds an available port if 54321 is busy.
+- **`pglens url` Command**: CLI command to display the currently running server URL.
+- **Database Query Timeout**: Enforced 30-second timeout on all database operations.
+
+### Changed
+
+- Connection dialog now defaults to "Parameters" input mode for better usability.
+- Switched to offset-based pagination when a custom sort order is active.
+- Improved connection error handling and validation.
+
 ## [1.1.0] - 2025-11-21
 
 ### Added

package/README.md

@@ -4,18 +4,23 @@ A simple PostgreSQL database viewer tool. Perfect to quickly view and explore yo
 
 ## Features
 
+- 🔌 **Connection Manager**: Manage multiple database connections from a single UI
+- 🚀 **Background Service**: Runs as a daemon process for persistent access
 - 🗂️ **Table Browser**: View all tables in your database in a clean, searchable sidebar
 - 📊 **Data Viewer**: Browse table rows with a modern, easy-to-read interface
+- 📝 **Cell Content Viewer**: Double-click any cell to view full content in a popup
+- 🎨 **JSON/JSONB Formatting**: Auto-formats JSON data with syntax highlighting
+- 🕒 **Timezone Support**: View timestamps in local, UTC, or other timezones
+- 📋 **Clipboard Support**: One-click copy for cell contents
 - 🪟 **Multiple Tabs**: Open multiple tables simultaneously in separate tabs
-- 🔄 **Sorting**: Click column headers to sort data (client-side sorting on current view)
-- 📄 **Pagination**: Navigate through large tables with Previous/Next buttons (100 rows per page)
+- 🔄 **Server-Side Sorting**: Click column headers to sort data directly on the database server
+- 📄 **Pagination**: Navigate through large tables with Previous/Next buttons
 - 🔍 **Table Search**: Quickly find tables by name using the search bar
 - 👁️ **Column Visibility**: Show or hide columns to focus on what matters
 - 📏 **Column Resizing**: Resize columns by dragging the column borders
 - 🎨 **Theme Support**: Choose between light, dark, or system theme
-- 🔄 **Refresh Data**: Reload table data with a single click
 - ⚡ **Optimized Performance**: Uses cursor-based pagination for efficient large table navigation
-- 🔒 **SSL Support**: Configurable SSL modes with automatic recommendations on connection errors
+- 🔒 **SSL Support**: Configurable SSL modes (Disable, Require, Prefer, Verify CA/Full)
 - 🚀 **Easy Setup**: Install globally and run with a single command
 
 ## Installation
@@ -32,173 +37,63 @@ npm install pglens
 
 ## Usage
 
-Run pglens with your PostgreSQL connection string and optional port:
+### Start the Server
 
-```bash
-pglens --url postgresql://user:password@localhost:5432/dbname --port 54321
-```
-
-### Arguments
-
-- `--url` (required): PostgreSQL connection string
-  - Format: `postgresql://user:password@host:port/database`
-  - Example: `postgresql://postgres:mypassword@localhost:5432/mydb`
-- `--port` (optional): Port to run the web server on (default: 54321)
-- `--sslmode` (optional): SSL mode for database connection (default: `prefer`)
-  - `disable`: Disable SSL encryption
-  - `require`: Require SSL, but don't verify certificate
-  - `prefer`: Prefer SSL, but allow non-SSL fallback (default)
-  - `verify-ca`: Require SSL and verify certificate authority
-  - `verify-full`: Require SSL and verify certificate and hostname
-
-### SSL Mode Examples
-
-```bash
-# Use default SSL mode (prefer)
-pglens --url postgresql://postgres:secret@localhost:5432/myapp
-
-# Require SSL without certificate verification (for self-signed certs)
-pglens --url postgresql://postgres:secret@localhost:5432/myapp --sslmode require
-
-# Disable SSL (for local development)
-pglens --url postgresql://postgres:secret@localhost:5432/myapp --sslmode disable
-
-# Full certificate verification (for production)
-pglens --url postgresql://postgres:secret@localhost:5432/myapp --sslmode verify-full
-```
-
-### Connection Troubleshooting
-
-If you encounter connection errors, pglens will automatically analyze the error and suggest an appropriate SSL mode:
-
-```
-✗ Failed to connect to PostgreSQL database: self signed certificate
-
-💡 SSL Mode Recommendation: Try using --sslmode require
-   Current SSL mode: verify-full
-   Suggested command: Add --sslmode require to your command
-```
-
-### Basic Example
-
-```bash
-pglens --url postgresql://postgres:secret@localhost:5432/myapp --port 54321
-```
-
-Then open your browser to `http://localhost:54321` to view your database.
-
-## Running with PM2 (Server Deployment)
-
-For production use on a server, you can run pglens as a persistent process using [PM2](https://pm2.keymetrics.io/), a process manager for Node.js applications.
-
-### Install PM2
+Start pglens as a background service:
 
 ```bash
-npm install -g pm2
+pglens start
 ```
 
-### Start pglens with PM2
+This will start the server on `http://localhost:54321` (or the next available port if 54321 is busy).
+The URL will be printed to the console. You can also check the running URL at any time with:
 
 ```bash
-pm2 start pglens -- --url postgresql://user:password@localhost:5432/dbname --port 54321
+pglens url
 ```
 
-Or with SSL mode:
+### Connect to a Database
 
-```bash
-pm2 start pglens -- --url postgresql://user:password@localhost:5432/dbname --port 54321 --sslmode require
-```
+1. Open `http://localhost:54321`
+2. Click the **+** icon in the sidebar
+3. Enter your connection details using one of the tabs:
+   - **Parameters** (Default): Enter Host, Port, Database, User, and Password separately.
+   - **Connection URL**: Paste a standard PostgreSQL connection string (e.g., `postgresql://user:pass@localhost:5432/db`).
+4. Select the **SSL Mode** appropriate for your server.
+5. Click **Connect**.
 
-Or use PM2's ecosystem file for better configuration:
-
-**ecosystem.config.js:**
-
-```javascript
-module.exports = {
-  apps: [
-    {
-      name: "pglens",
-      script: "pglens",
-      args: "--url postgresql://user:password@localhost:5432/dbname --port 54321 --sslmode require",
-      instances: 1,
-      autorestart: true,
-      watch: false,
-      max_memory_restart: "300M",
-      env: {
-        NODE_ENV: "production",
-      },
-    },
-  ],
-};
-```
+### Stop the Server
 
-Then start with:
+To stop the background service:
 
 ```bash
-pm2 start ecosystem.config.js
+pglens stop
 ```
 
-### Useful PM2 Commands
-
-```bash
-# View running processes
-pm2 list
-
-# View logs
-pm2 logs pglens
-
-# Stop pglens
-pm2 stop pglens
-
-# Restart pglens
-pm2 restart pglens
-
-# Delete pglens from PM2
-pm2 delete pglens
-
-# Save PM2 process list (for auto-restart on reboot)
-pm2 save
-
-# Setup PM2 to start on system boot
-pm2 startup
-```
-
-### Important Security Reminder
-
-⚠️ **Warning**: When running pglens on a server, ensure you:
-
-- Use a reverse proxy (nginx, Apache) with authentication
-- Restrict access via firewall rules
-- Use HTTPS/TLS encryption
-- Consider adding authentication middleware
-- Never expose it directly to the internet without proper security measures
-
 ## How It Works
 
-1. **Start the server**: Run the `pglens` command with your database URL
-2. **View tables**: The left sidebar shows all tables in your database
-3. **Search tables**: Use the search bar to quickly filter tables by name
-4. **Select a table**: Click on any table to view its data in a new tab
-5. **Multiple tabs**: Open multiple tables at once - each opens in its own tab
-6. **Sort data**: Click on column headers to sort the current view
-7. **Customize columns**: Use the "Columns" button to show/hide columns or resize them by dragging borders
-8. **Navigate pages**: Use Previous/Next buttons to load more rows (100 rows per page)
-9. **Refresh data**: Click the refresh button (↻) to reload the current table
-10. **Change theme**: Click the theme button (🌓) to switch between light, dark, or system theme
+1. **Start**: Run `pglens start` to launch the background service
+2. **Connect**: Add one or more database connections via the Web UI
+3. **Explore**: 
+   - Use the sidebar to browse tables across different connections
+   - Double-click cells to view detailed content
+   - Use the "Columns" menu to toggle visibility
+   - Switch themes for comfortable viewing
 
 ## Development
 
 To develop or modify pglens:
 
 ```bash
-# Clone or navigate to the project directory
+# Clone the repository
+git clone https://github.com/tsvillain/pglens.git
 cd pglens
 
 # Install dependencies
 npm install
 
-# Run locally
-node bin/pglens --url your-connection-string --port 54321
+# Run locally (starts server in foreground for logs)
+node bin/pglens serve
 ```
 
 ## Contributing
@@ -210,11 +105,9 @@ Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTIN
 - Pull request process
 - Issue reporting
 
-We appreciate all contributions, whether it's bug fixes, new features, documentation improvements, or feedback.
-
 ## Security Note
 
-This tool is designed for local development use only. It has no authentication and should **never** be exposed to the internet or untrusted networks. Always use it on localhost or within a trusted network environment.
+This tool is designed for local development use. While it supports SSL for database connections, the web interface itself runs on HTTP (localhost) and has no user authentication. **Do not expose the pglens port (54321) directly to the internet.**
 
 ## License
 

package/bin/pglens

@@ -2,17 +2,153 @@
 
 const { program } = require('commander');
 const { startServer } = require('../src/server');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+const PID_FILE = path.join(os.homedir(), '.pglens.pid');
+const PORT_FILE = path.join(os.homedir(), '.pglens.port');
 
 program
   .name('pglens')
   .description('A simple PostgreSQL database viewer tool')
-  .version('1.0.0')
-  .requiredOption('--url <url>', 'PostgreSQL connection string (e.g., postgresql://user:pass@localhost:5432/dbname)')
-  .option('--port <port>', 'Port to run the web server on', '54321')
-  .option('--sslmode <mode>', 'SSL mode: disable, require, prefer, verify-ca, verify-full', 'prefer')
-  .parse(process.argv);
+  .version('2.0.1');
+
+function getRunningPort() {
+  if (fs.existsSync(PORT_FILE)) {
+    try {
+      return parseInt(fs.readFileSync(PORT_FILE, 'utf8'));
+    } catch (e) {
+      return null;
+    }
+  }
+  return null;
+}
+
+program
+  .command('start')
+  .description('Start the pglens server in background')
+  .action(async () => {
+    // Check if already running
+    if (fs.existsSync(PID_FILE)) {
+      try {
+        const pid = parseInt(fs.readFileSync(PID_FILE, 'utf8'));
+        process.kill(pid, 0); // Check if process exists
+        console.log(`pglens is already running (PID: ${pid})`);
+
+        const port = getRunningPort();
+        if (port) {
+          console.log(`✓ Server running on http://localhost:${port}`);
+        } else {
+          console.log('  Server URL unknown (check logs)');
+        }
+        return;
+      } catch (e) {
+        // Stale PID file, remove it
+        fs.unlinkSync(PID_FILE);
+        if (fs.existsSync(PORT_FILE)) fs.unlinkSync(PORT_FILE);
+      }
+    }
+
+    // Spawn detached child process
+    const child = spawn(process.execPath, [__filename, 'serve'], {
+      detached: true,
+      stdio: 'ignore'
+    });
+
+    // Save PID
+    fs.writeFileSync(PID_FILE, child.pid.toString());
+
+    // Unref to allow parent to exit
+    child.unref();
+
+    console.log(`  Background process started (PID: ${child.pid})`);
+
+    // Wait for server to start and acquire port
+    let attempts = 0;
+    const maxAttempts = 20;
+    const checkInterval = 100;
+
+    process.stdout.write('  Waiting for server...');
+
+    const interval = setInterval(() => {
+      const port = getRunningPort();
+      if (port) {
+        clearInterval(interval);
+        process.stdout.write('\r\x1b[K'); // Clear line
+        console.log(`✓ Server running on http://localhost:${port}`);
+        process.exit(0);
+      }
+
+      attempts++;
+      if (attempts >= maxAttempts) {
+        clearInterval(interval);
+        process.stdout.write('\r\x1b[K'); // Clear line
+        console.log('✓ Server started (could not determine port, check logs)');
+        process.exit(0);
+      }
+    }, checkInterval);
+  });
+
+// Hidden command that actually runs the server
+program
+  .command('serve', { hidden: true })
+  .action(() => {
+    startServer();
+  });
+
+program
+  .command('stop')
+  .description('Stop the pglens server')
+  .action(() => {
+    if (!fs.existsSync(PID_FILE)) {
+      console.log('pglens is not running');
+      return;
+    }
+
+    try {
+      const pid = parseInt(fs.readFileSync(PID_FILE, 'utf8'));
+      process.kill(pid, 'SIGTERM');
+      fs.unlinkSync(PID_FILE);
+      if (fs.existsSync(PORT_FILE)) fs.unlinkSync(PORT_FILE);
+      console.log('pglens stopped');
+    } catch (e) {
+      console.error(`Error stopping pglens: ${e.message}`);
+      // Clean up if process not found
+      if (e.code === 'ESRCH') {
+        fs.unlinkSync(PID_FILE);
+        if (fs.existsSync(PORT_FILE)) fs.unlinkSync(PORT_FILE);
+      }
+    }
+  });
+
+program
+  .command('url')
+  .description('Show the URL where pglens is running')
+  .action(() => {
+    if (!fs.existsSync(PID_FILE)) {
+      console.log('pglens is not running');
+      return;
+    }
 
-const options = program.opts();
+    // Verify process is actually running
+    try {
+      const pid = parseInt(fs.readFileSync(PID_FILE, 'utf8'));
+      process.kill(pid, 0);
+    } catch (e) {
+      console.log('pglens is not running (stale PID file)');
+      fs.unlinkSync(PID_FILE);
+      if (fs.existsSync(PORT_FILE)) fs.unlinkSync(PORT_FILE);
+      return;
+    }
 
-startServer(options.url, parseInt(options.port, 10), options.sslmode);
+    const port = getRunningPort();
+    if (port) {
+      console.log(`http://localhost:${port}`);
+    } else {
+      console.log('Could not determine server URL.');
+    }
+  });
 
+program.parse(process.argv);