Skip to main content
PostgreSQL is the most common connector for Hyperterse deployments. It supports all standard SQL features — joins, aggregations, window functions, JSON operations, full-text search, and advanced data types — with connection pooling, SSL/TLS, and parameterized query execution built in.
Hyperterse connects to your existing database. It does not create or manage databases — you provide a running PostgreSQL instance and a connection string.

​
Adapter configuration

Create an adapter file in app/adapters/:
app/adapters/primary-db.terse
The connection string follows the standard PostgreSQL URI format:
Always use {{ env.VAR }} placeholders for connection strings. Never commit credentials to source control.

​
Connection options

Pass driver-level settings through the options map. All values must be strings.
​
sslmode
string
SSL negotiation mode. Use require or stricter in production.Values: disable, allow, prefer, require, verify-ca, verify-full
​
connect_timeout
string
Connection timeout in seconds. Connections that exceed this threshold are terminated.
​
application_name
string
Application name reported to the PostgreSQL server. Useful for identifying connections in pg_stat_activity.
​
max_connections
string
Maximum number of connections in the pool.
Never use sslmode: disable with cloud-hosted databases or production environments. Connection traffic is unencrypted.
Create a dedicated database user for Hyperterse and grant only the privileges your tools require:
For tools that write data, add the necessary privileges:

​
Verify the connection

Start the server and confirm the adapter connects:
A successful connection produces:
If the connection fails, the server exits immediately with a diagnostic message.

​
Usage

PostgreSQL tools execute standard SQL through the adapter. Use {{ inputs.field }} placeholders for parameterized values — they are never interpolated as raw SQL.
app/tools/get-user/config.terse
PostgreSQL-specific features like jsonb operators, tsvector search, array operations, CTEs, and window functions are all supported. Use standard PostgreSQL syntax in statements.

​
Read replicas

For read-heavy workloads, configure separate adapters for primary and replica databases:
app/adapters/primary.terse
app/adapters/replica.terse
Send read-only tools to the replica adapter and write tools to the primary.

​
Troubleshooting

​
Connection refused

Verify that PostgreSQL is running and the host is reachable:
Check firewall rules and security groups if connecting to a remote or cloud-hosted instance.

​
SSL certificate errors

For self-signed certificates, set sslmode to require (encrypts traffic without certificate verification). For full verification, use verify-ca or verify-full and ensure the CA certificate is installed on the machine running Hyperterse.

​
Permission denied

Inspect the current grants for your user:
Grant the missing permissions, then restart Hyperterse to re-establish the connection pool.