​
Overview

The Blnk Query Agent is currently in development and will be available to customers soon.
The Blnk Query Agent provides secure, read-only access to your database from Blnk Cloud. Get up and running in minutes with Docker.

​
Prerequisites

Before you begin, ensure you have:
  • Docker installed and running;
  • A PostgreSQL database with network access;
  • Database credentials with read permissions;
  • Your Blnk API key from the dashboard.

​
Quick Setup

​
1. Prepare Your Database User

Create a dedicated read-only user in your PostgreSQL database. This user should have SELECT permissions on the tables that Blnk needs to access.
The agent only requires read access. Never use administrative credentials.

​
2. Deploy the Agent

Run the official Docker image with your configuration: 
docker run -d \
  --name blnk-agent \
  -e DB_URL="postgres://readonly:password@host.docker.internal:5432/mydb?sslmode=require" \
  -e BLNK_API_KEY="your-api-key-here" \
  -e BLNK_CONNECTION_URL="wss://ingest.blnkfinance.com/ws" \
  blnkfinance/query-agent:latest

​
3. Verify Connection

Check that everything is working: 
# View container status
docker ps | grep blnk-agent

# Check connection logs
docker logs blnk-agent --tail 20

# Test health endpoint
curl http://localhost:9090/health

​
Configuration Reference

​
Required Environment Variables

VariableDescriptionFormat
DB_URLPostgreSQL connection stringpostgres://user:pass@host:port/db?sslmode=require
BLNK_API_KEYYour Blnk API keysk_live_... or sk_test_...
BLNK_CONNECTION_URLWebSocket endpoint for Blnk Cloudwss://ingest.blnkfinance.com/ws

​
Optional Environment Variables

VariableDefaultDescription
HTTP_PORT9090Health check server port
QUERY_TIMEOUT_MS30000Database query timeout (milliseconds)
LOG_LEVELinfoLogging level (debug, info, warn, error)
RECONNECT_INTERVAL30WebSocket reconnection interval (seconds)

​
Advanced Configuration Example

docker run -d \
  --name blnk-agent \
  --restart unless-stopped \
  -p 9090:9090 \
  -e DB_URL="postgres://blnk_readonly:secure_password@db.example.com:5432/production?sslmode=require&connect_timeout=10" \
  -e BLNK_API_KEY="sk_live_abc123def456" \
  -e BLNK_CONNECTION_URL="wss://ingest.blnkfinance.com/ws" \
  -e HTTP_PORT="9090" \
  -e QUERY_TIMEOUT_MS="60000" \
  -e LOG_LEVEL="info" \
  blnkfinance/query-agent:latest

​
Network Configuration

​
Local Database (Same Machine)

-e DB_URL="postgres://user:pass@host.docker.internal:5432/db?sslmode=require"

​
Cloud Database

Ensure your database accepts connections from your Docker host’s public IP. Most cloud providers require you to whitelist IP addresses in their firewall settings.

​
Management Commands

​
Monitor the Agent

# Real-time logs
docker logs -f blnk-agent

# Recent logs only
docker logs blnk-agent --tail 50

# Container resource usage
docker stats blnk-agent

​
Update the Agent

# Pull latest version
docker pull blnkfinance/query-agent:latest

# Restart with new image
docker stop blnk-agent && docker rm blnk-agent

# Run with same configuration
docker run -d --name blnk-agent [your-config] blnkfinance/query-agent:latest

​
Stop and Remove

# Stop the agent
docker stop blnk-agent

# Remove container
docker rm blnk-agent

# Clean up (optional)
docker image prune -f

​
Need help?

Let’s help you get started with Cloud! Whether you’re setting up your first workspace or adding Cloud to your existing tools, our team is here to help you succeed. Contact our Support team to get answers and expert guidance on making the most of Cloud.