Connect your database to Truth Maker securely via an outbound-only tunnel
npm install @truthmaker/db-connectSecurely connect your database to Truth Maker from inside your network.
```
┌─────────────────────────────────────────────────────────────────┐
│ 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
`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
`bash`
npx @truthmaker/db-connect connect
This starts the tunnel. Keep it running while you want Truth Maker to access your database.
`bash`
npx @truthmaker/db-connect status
The setup command automatically scans for databases in:
| Source | What it checks |
| ------------ | ------------------------------------------------------------------- |
| Environment | DATABASE_URL, POSTGRES_URL, PGHOST, etc. |.env
| Config files | , .env.local, config/database.yml, prisma/schema.prisma |~/.pgpass
| Credentials | |
| Processes | PostgreSQL listening on port 5432 |
| Docker | Running PostgreSQL containers |
- 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
`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 is stored locally at:
- macOS: ~/Library/Preferences/truthmaker-db-connect-nodejs/config.json~/.config/truthmaker-db-connect-nodejs/config.json
- Linux: %APPDATA%\truthmaker-db-connect-nodejs\Config\config.json
- Windows:
| Variable | Description |
| ----------------------- | ----------------------------------------------------------------------------- |
| TRUTHMAKER_TUNNEL_URL | Override tunnel server URL (default: wss://api.truthmaker.io/api/tunnel/ws`) |
Currently supported:
- PostgreSQL 12+
Coming soon:
- MySQL 8+
- SQL Server
- Snowflake
- BigQuery