@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

$3

`bash
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

$3

`bash
npx @truthmaker/db-connect connect
`

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

$3

`bash
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

`sql
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