blnkfinance/query-agent repository overview

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 Instance Connection key from the Cloud⁠

⁠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.

⁠2. Deploy the Agent

Run the official Docker image with your configuration:

docker run -d \
  --name blnk-agent \
  -e DB_URL="postgres://readonly:[email protected]:5432/mydb?sslmode=require" \
  -e CONNECTION_KEY="your-api-key-here" \
  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

✅ Success Response:

{"status": "healthy", "database": "connected", "websocket": "connected"}

⁠Configuration Reference

⁠Required Environment Variables

⁠Network Configuration

⁠Local Database (Same Machine)

macOS & Windows:

-e DB_URL="postgres://user:[email protected]:5432/db?sslmode=require"

Linux:

--network host \
-e DB_URL="postgres://user:pass@localhost: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

⁠Update the Agent

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

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

⁠Stop and Remove

# Stop the agent
docker stop blnk-agent

# Remove container
docker rm blnk-agent

# Clean up (optional)
docker image prune -f