DBInsight Agent

Local database connector agent for DBInsight. Securely connects your local PostgreSQL database to DBInsight cloud for schema introspection and documentation.

Features

• 🔒 Secure - Read-only access, no write operations
• 🚀 Fast - Real-time communication with DBInsight
• 🛡️ Safe - Enforced limits on sample data
• 📦 Simple - Two commands: link and start
• 🔌 Local - Your database never leaves your machine
• ⚡ No Installation - Run directly with npx

Requirements

• Node.js 18+ - Download here
• PostgreSQL - Local database to connect

Quick Start (Recommended)

No installation required! Use npx to run the agent directly.

1. Link the Agent

First, generate a pairing code in the DBInsight web app:

1. Go to your project
2. Click "Connect Database"
3. Click "Generate Pairing Code"

Then run:

npx dbinsight-agent@latest link --code ABC-123 --apiBase https://www.dbinsight.app

Example:

npx dbinsight-agent@latest link --code XYZ-789 --apiBase https://www.dbinsight.app

This will:

• Validate the pairing code
• Register the connector with DBInsight
• Save configuration to ~/.dbinsight/config.json
• Generate a secure connector token

2. Start the Agent

Replace the connection string with your local database credentials:

npx dbinsight-agent@latest start --db "postgres://user:password@localhost:5432/mydb"

Example:

npx dbinsight-agent@latest start --db "postgres://admin:secret@localhost:5432/ecommerce"

The agent will:

• Connect to your local database
• Connect to DBInsight via WebSocket
• Wait for introspection jobs
• Execute jobs and return results

Commands

link

Link the agent to a DBInsight project using a pairing code.

npx dbinsight-agent@latest link --code <code> --apiBase <url> [--name <name>]

Options:

• --code <code> - Pairing code from DBInsight (e.g., ABC-123) [required]
• --apiBase <url> - DBInsight API base URL (e.g., https://www.dbinsight.app) [required]
• --name <name> - Connector name (default: "Local Connector")

Example:

npx dbinsight-agent@latest link \
  --code ABC-123 \
  --apiBase https://www.dbinsight.app \
  --name "Development Machine"

start

Start the connector agent.

npx dbinsight-agent@latest start --db <url> [--apiBase <url>] [--token <token>]

Options:

• --db <url> - PostgreSQL connection string [required]
• --apiBase <url> - DBInsight API base URL (defaults to saved config)
• --token <token> - Connector token (defaults to saved config)

Example:

npx dbinsight-agent@latest start --db "postgres://user:pass@localhost:5432/mydb"

Connection String Format:

postgres://username:password@host:port/database

Supported Job Types

The agent executes the following read-only operations:

1. HEALTHCHECK

Test database connection and get version info.

Returns:

{
  "connected": true,
  "database": "mydb",
  "version": "PostgreSQL 15.3"
}

2. LIST_TABLES

List all tables in the database.

Returns:

{
  "tables": [
    {
      "name": "users",
      "schema": "public",
      "rowCount": 1000
    }
  ]
}

3. DESCRIBE_TABLE

Get table schema (columns, types, constraints).

Payload:

{
  "tableName": "users",
  "schema": "public"
}

Returns:

{
  "table": "users",
  "schema": "public",
  "columns": [
    {
      "name": "id",
      "type": "integer",
      "nullable": false,
      "primaryKey": true,
      "unique": false
    }
  ],
  "foreignKeys": [
    {
      "column": "org_id",
      "referencesSchema": "public",
      "referencesTable": "organizations",
      "referencesColumn": "id"
    }
  ]
}

4. SAMPLE_ROWS

Get sample rows from a table.

Payload:

{
  "tableName": "users",
  "schema": "public",
  "limit": 10
}

Returns:

{
  "table": "users",
  "schema": "public",
  "rows": [
    { "id": 1, "email": "[email protected]" }
  ],
  "count": 1,
  "limit": 10
}

Safety Limit: Maximum 100 rows (enforced by agent)

Security

Read-Only Access

The agent only executes read operations:

• ✅ SELECT queries
• ✅ Schema introspection
• ❌ INSERT, UPDATE, DELETE
• ❌ DROP, CREATE, ALTER
• ❌ Any write operations

Safety Limits

• Sample rows: Maximum 100 rows per query
• Query timeout: 30 seconds
• SQL injection protection: Identifier validation

Unknown Job Types

The agent will reject any unknown job types and return an error.

Token Security

• Connector tokens are 256-bit secure random values
• Tokens are stored locally in config.json
• Tokens never expire (but can be revoked by deleting the connector)

Configuration

Configuration is automatically saved in a secure location:

Windows:

%APPDATA%\dbinsight-agent\config.json

Mac/Linux:

~/.config/dbinsight-agent/config.json

Config file contents:

{
  "connectorToken": "dbc_abc123...",
  "connectorId": "dbc_abc123...",
  "projectId": "clxxx",
  "apiBase": "https://www.dbinsight.app",
  "connectorName": "My Laptop"
}

⚠️ Keep this file secure! It contains your connector token.

Troubleshooting

"Not linked"

Run the link command first to pair the agent with DBInsight:

npx dbinsight-agent@latest link --code <CODE> --apiBase https://www.dbinsight.app

The config file will be saved to:

• Windows: %APPDATA%\dbinsight-agent\config.json
• Mac/Linux: ~/.config/dbinsight-agent/config.json

"Failed to connect to database"

Check your PostgreSQL connection string:

• Correct host and port?
• Valid credentials?
• Database exists?
• PostgreSQL is running?

Heartbeat issues

The agent sends a heartbeat every 15 seconds to stay online. If heartbeats fail:

• Check DBInsight API is accessible
• Verify correct apiBase URL in config
• Check network connectivity
• Ensure firewall allows outbound HTTPS

"Authentication failed"

• Pairing code may have expired (10 minutes)
• Generate a new pairing code and run link again

Alternative: Global Installation

If you prefer to install the agent globally instead of using npx:

npm install -g dbinsight-agent

Then you can run commands without npx:

dbinsight-agent link --code ABC-123 --apiBase https://www.dbinsight.app
dbinsight-agent start --db "postgres://user:pass@localhost:5432/mydb"

Development

Build

npm run build

Watch Mode

npm run dev

Link Locally

npm link

Architecture

┌─────────────────┐
│  DBInsight Web  │
│   (Cloud)       │
└────────┬────────┘
         │
         │ HTTPS
         │ (Heartbeat every 15s)
         │
┌────────▼────────┐
│  DBInsight      │
│  Agent (CLI)    │
│  (Your Machine) │
└────────┬────────┘
         │
         │ pg (postgres)
         │
┌────────▼────────┐
│  PostgreSQL     │
│  (localhost)    │
└─────────────────┘

Communication:

• Agent sends heartbeat every 15 seconds via HTTPS
• Heartbeat keeps connector status "online" in DBInsight
• Simple HTTP polling (no WebSocket required)

Communication Flow

1. Pairing:

   • User generates pairing code in web app
   • Agent calls /api/connectors/link with code
   • Server validates and returns connector token
   • Agent saves token to config.json

2. Connection:

   • Agent connects to WebSocket with token
   • Server authenticates and marks connector online
   • Heartbeat every 30 seconds

3. Job Execution:

   • Server sends job via WebSocket
   • Agent acknowledges job
   • Agent executes job against local database
   • Agent sends result back to server

License

MIT

Support

For issues or questions, please contact DBInsight support or open an issue on GitHub.