Postgres Drivers & BI Tools

HatiData exposes a PostgreSQL wire-protocol interface on port 5439. Any BI tool, SQL client, language driver, or application that supports PostgreSQL connections can connect to HatiData without modification. Legacy SQL dialect syntax is automatically transpiled to native SQL by the proxy — so existing queries continue to work as-is.

Universal Connection Parameters

Parameter	Value
Host	Your HatiData proxy endpoint (e.g., data.yourcompany.com)
Port	5439
Database	hatidata (or your configured catalog name)
Username	Your HatiData user or service account ID
Password	Your HatiData API key (hd_live_* or hd_test_*)
SSL	Required in production; optional in local dev mode
Protocol	PostgreSQL v3 wire protocol
Driver	Any PostgreSQL driver (JDBC, ODBC, native)

HatiData presents itself as PostgreSQL 15.0 to connected clients. All catalog queries (information_schema, pg_catalog) are handled by HatiData's compatibility layer without touching the underlying query engine.

Connection String Format

postgres://USERNAME:API_KEY@HOST:5439/hatidata?sslmode=require

Examples:

# Production (cloud)
postgres://admin:hd_live_your_api_key@data.yourcompany.com:5439/hatidata?sslmode=require

# Local development
postgres://admin@localhost:5439/hatidata?sslmode=disable

---

Command-Line Clients

psql

# Basic connection
psql -h data.yourcompany.com -p 5439 -U admin -d hatidata

# With SSL (production)
psql "host=data.yourcompany.com port=5439 dbname=hatidata user=admin sslmode=require"

# Local dev (no SSL)
psql -h localhost -p 5439 -U admin -d hatidata

# Single query
psql -h localhost -p 5439 -U admin -c "SELECT 1"

Using environment variables:

export PGHOST=data.yourcompany.com
export PGPORT=5439
export PGDATABASE=hatidata
export PGUSER=admin
export PGPASSWORD=hd_live_your_api_key
export PGSSLMODE=require

psql  # uses the env vars above

---

Language Drivers

Python — psycopg2

import psycopg2

conn = psycopg2.connect(
    host="data.yourcompany.com",
    port=5439,
    dbname="hatidata",
    user="admin",
    password="hd_live_your_api_key",
    sslmode="require",
)

cursor = conn.cursor()
cursor.execute("SELECT customer_id, SUM(total) FROM orders GROUP BY 1 LIMIT 5")
rows = cursor.fetchall()
for row in rows:
    print(row)

cursor.close()
conn.close()

Python — SQLAlchemy

from sqlalchemy import create_engine, text

engine = create_engine(
    "postgresql+psycopg2://admin:hd_live_your_api_key@data.yourcompany.com:5439/hatidata",
    connect_args={"sslmode": "require"},
)

with engine.connect() as conn:
    result = conn.execute(text("SELECT table_name FROM information_schema.tables"))
    for row in result:
        print(row.table_name)

Node.js — pg

const { Pool } = require('pg');

const pool = new Pool({
  host: 'data.yourcompany.com',
  port: 5439,
  database: 'hatidata',
  user: 'admin',
  password: 'hd_live_your_api_key',
  ssl: { rejectUnauthorized: true },
});

async function query(sql) {
  const client = await pool.connect();
  try {
    const result = await client.query(sql);
    return result.rows;
  } finally {
    client.release();
  }
}

// Example usage
query('SELECT COUNT(*) as total FROM orders').then(console.log);

JDBC

Use the standard PostgreSQL JDBC driver (version 42.x or later):

<!-- Maven -->
<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <version>42.7.3</version>
</dependency>

String url = "jdbc:postgresql://data.yourcompany.com:5439/hatidata?sslmode=require";
Properties props = new Properties();
props.setProperty("user", "admin");
props.setProperty("password", "hd_live_your_api_key");

Connection conn = DriverManager.getConnection(url, props);
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT * FROM orders LIMIT 10");

---

BI Tools

DBeaver

1. Click New Database Connection and select PostgreSQL.
2. Enter:
   • Host: data.yourcompany.com
   • Port: 5439
   • Database: hatidata
   • Username / Password: your HatiData credentials
3. On the SSL tab: set SSL mode to require (production) or disable for local dev.
4. Click Test Connection, then Finish.

DBeaver's schema browser, ERD, SQL editor (F3), and data export all work as expected. Use EXPLAIN COST <sql> to preview query cost before executing.

DataGrip (JetBrains)

1. Go to File > New > Data Source > PostgreSQL.
2. Enter host, port, database, and credentials.
3. On the Advanced tab, set ssl = true and sslmode = require.
4. Click Test Connection, then OK.

DataGrip's introspection queries against pg_catalog are fully supported. SQL console, query execution plans, and data export work as expected.

Metabase

1. Go to Admin > Databases > Add Database and select PostgreSQL.
2. Fill in:
   • Display name: HatiData Production
   • Host: data.yourcompany.com
   • Port: 5439
   • Database name: hatidata
   • Username / Password: your credentials
3. Under Additional connection string options: ssl=true&sslmode=require
4. Click Save.

Set sync schedule to daily to reduce unnecessary catalog queries. Metabase's visual query builder generates standard SQL; custom SQL supports legacy dialect syntax too.

Grafana

1. In Grafana, go to Configuration > Data Sources > Add data source and select PostgreSQL.
2. Configure:
   • Host: data.yourcompany.com:5439
   • Database: hatidata
   • User / Password: your credentials
   • SSL Mode: require
3. Set PostgreSQL Version to 15.
4. Click Save & Test.

Grafana's time series panels and table panels work natively. Use $__timeFilter(column) macros with timestamp columns in your data layer.

Tableau Desktop

1. Under Connect, select PostgreSQL.
2. Enter:
   • Server: data.yourcompany.com
   • Port: 5439
   • Database: hatidata
   • Authentication: Username and Password
3. Check Require SSL for production endpoints.
4. Click Sign In.

Tableau issues many pg_type and pg_attribute catalog queries on connect — HatiData handles all of these transparently. If schema discovery is slow, set Initial SQL to SET search_path = 'public'.

Power BI

Power BI connects via the PostgreSQL ODBC driver (psqlODBC).

1. Install psqlODBC from https://www.postgresql.org/ftp/odbc/versions/msi/
2. In Power BI Desktop, click Get Data > PostgreSQL.
3. Enter server as data.yourcompany.com:5439 and database as hatidata.
4. Select Database authentication and enter credentials.

Alternatively, configure an ODBC DSN (~/.odbc.ini on macOS/Linux):

[HatiData]
Driver = PostgreSQL Unicode
Server = data.yourcompany.com
Port = 5439
Database = hatidata
UserName = admin
Password = hd_live_your_api_key
SSLMode = require

---

Migration from Legacy SQL Drivers

If you are migrating from a legacy cloud data infrastructure, swap the connection string — no code changes required.

Legacy JDBC Property	PostgreSQL JDBC Equivalent
jdbc:legacy://account.vendor.com	jdbc:postgresql://host:5439/database
account	(not needed)
warehouse	(not needed — HatiData auto-manages compute)
db	Database name in URL path
schema	Set via SET search_path = schema_name after connect
role	Mapped to HatiData RBAC role
authenticator	Use password auth with HatiData API key

---

Troubleshooting

Symptom	Fix
Connection refused	Verify proxy is running on port 5439; check firewall rules
SSL errors in dev	Set sslmode=disable or sslmode=prefer for local connections
Authentication failed	Check API key is valid (hd_live_* for prod, hd_test_* for dev)
Table not found	Run SELECT * FROM information_schema.tables to verify access
Slow schema discovery	Run SET search_path = 'public' to speed up catalog queries
Query timeout	Increase with SET statement_timeout = 600000 (milliseconds)
Syntax errors	Check SQL Functions; try standard SQL syntax

---

Related Concepts

• SQL Functions — Supported dialects and auto-transpilation
• dbt Adapter — Run dbt models against your HatiData data layer
• Python SDK — Agent-aware queries with automatic audit attribution