@truthmaker/db-connect

Securely connect your database to Truth Maker from inside your network.

How It Works

┌─────────────────────────────────────────────────────────────────┐
│ Your Network (VPC/On-prem)                                      │
│                                                                 │
│  ┌──────────┐      ┌─────────────────────────────────────────┐  │
│  │ Database │◄────►│ truthmaker-db-connect                   │  │
│  └──────────┘      │                                         │  │
│                    │ • Introspects schema (tables, columns)  │  │
│                    │ • Opens outbound WebSocket tunnel       │  │
│                    │ • Executes validated queries            │  │
│                    │ • Returns sanitized results             │  │
│                    └───────────────┬─────────────────────────┘  │
│                                    │ Outbound only (port 443)   │
└────────────────────────────────────┼────────────────────────────┘
                                     ▼
                          Truth Maker Cloud

Quick Start

1. Setup

npx @truthmaker/db-connect setup

This will:

• Scan for databases (environment variables, config files, Docker)
• Let you select or enter a connection string
• Test the connection
• Introspect the schema
• Save configuration locally

2. Connect

npx @truthmaker/db-connect connect

This starts the tunnel. Keep it running while you want Truth Maker to access your database.

3. Check Status

npx @truthmaker/db-connect status

Database Discovery

The setup command automatically scans for databases in:

| Source | What it checks | | ------------ | ------------------------------------------------------------------- | | Environment | DATABASE_URL, POSTGRES_URL, PGHOST, etc. | | Config files | .env, .env.local, config/database.yml, prisma/schema.prisma | | Credentials | ~/.pgpass | | Processes | PostgreSQL listening on port 5432 | | Docker | Running PostgreSQL containers |

Security

• Outbound only: No inbound firewall rules needed
• Read-only: Only SELECT queries are allowed (enforced server-side)
• Schema-aware: Queries are validated against your discovered schema
• No credentials stored on our servers: Connection happens from your network

Recommended: Create a Read-Only User

CREATE USER truthmaker_readonly WITH PASSWORD 'your-secure-password';
GRANT CONNECT ON DATABASE your_database TO truthmaker_readonly;
GRANT USAGE ON SCHEMA public TO truthmaker_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO truthmaker_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO truthmaker_readonly;

Configuration

Configuration is stored locally at:

• macOS: ~/Library/Preferences/truthmaker-db-connect-nodejs/config.json
• Linux: ~/.config/truthmaker-db-connect-nodejs/config.json
• Windows: %APPDATA%\truthmaker-db-connect-nodejs\Config\config.json

Environment Variables

| Variable | Description | | ----------------------- | ----------------------------------------------------------------------------- | | TRUTHMAKER_TUNNEL_URL | Override tunnel server URL (default: wss://api.truthmaker.io/api/tunnel/ws) |

Supported Databases

Currently supported:

• PostgreSQL 12+

Coming soon:

• MySQL 8+
• SQL Server
• Snowflake
• BigQuery