Hyperterse — Agentic server framework.

Hyperterse supports MySQL with connection pooling, character set configuration, and parameterized query execution. All standard SQL features — joins, aggregations, subqueries, JSON functions, and window functions — work as expected in tool statements.

Hyperterse connects to your existing database. It does not create or manage databases — you provide a running MySQL instance and a connection string.

Adapter configuration

Create an adapter file in app/adapters/:

app/adapters/mysql-db.terse

connector: mysql
connection_string: '{{ env.MYSQL_URL }}'
options:
  charset: utf8mb4
  max_connections: '10'

The connection string uses the MySQL DSN format:

user:password@tcp(host:port)/database?param=value

MySQL DSN format differs from PostgreSQL URI format. The host and port are wrapped in tcp(...).

Connection options

string

Character set for the connection. Use utf8mb4 for full Unicode support including emoji.

string

Maximum number of connections in the pool.

Connection string parameters

Fine-tune behavior through query parameters on the connection string:

connection_string: 'user:pass@tcp(host:3306)/db?charset=utf8mb4&parseTime=true&loc=UTC&timeout=10s'

Parameter	Example	Purpose
`charset`	`utf8mb4`	Connection character set
`parseTime`	`true`	Parse `DATE` and `DATETIME` into time values
`loc`	`UTC`	Timezone for parsed datetimes
`timeout`	`10s`	Connection timeout
`readTimeout`	`30s`	I/O read timeout
`writeTimeout`	`30s`	I/O write timeout

Recommended permissions

Create a dedicated database user for Hyperterse and grant only the privileges your tools require:

-- Read-only
GRANT SELECT ON myapp.* TO 'hyperterse'@'%';

-- Read-write
GRANT INSERT, UPDATE, DELETE ON myapp.* TO 'hyperterse'@'%';

-- Specific tables only
GRANT SELECT ON myapp.users, myapp.products TO 'hyperterse'@'%';

Verify the connection

Start the server and confirm the adapter connects:

hyperterse start

A successful connection produces:

INFO  Connected to adapter: mysql-db

If the connection fails, the server exits immediately with a diagnostic message.

Usage

MySQL tools execute standard SQL through the adapter. Use {{ inputs.field }} placeholders for parameterized values.

app/tools/get-product/config.terse

description: 'Retrieve a product by its identifier'
use: main-db
statement: |
  SELECT id, name, price, description
  FROM products
  WHERE id = {{ inputs.product_id }}
inputs:
  product_id:
    type: int
    description: 'Product ID'
auth:
  plugin: allow_all

MySQL-specific features like JSON_EXTRACT, stored procedures, and window functions are all supported. Use standard MySQL syntax in statements.

Read replicas

Configure separate adapters for primary and replica databases:

app/adapters/primary.terse

connector: mysql
connection_string: '{{ env.PRIMARY_DB_URL }}'

app/adapters/replica.terse

connector: mysql
connection_string: '{{ env.REPLICA_DB_URL }}'

Send read-only tools to the replica adapter.

Troubleshooting

Access denied

Verify user grants:

SHOW GRANTS FOR 'hyperterse'@'%';

Ensure the user exists with the correct host permissions, then FLUSH PRIVILEGES.

Character set issues

Use utf8mb4 in the connection string to support the full Unicode range:

connection_string: "user:pass@tcp(host:3306)/db?charset=utf8mb4"

Verify the database character set:

SHOW CREATE DATABASE myapp;

Connection timeout

Increase timeout values in the connection string:

connection_string: "user:pass@tcp(host:3306)/db?timeout=30s&readTimeout=30s&writeTimeout=30s"

Timezone issues

Set the timezone explicitly for consistent datetime handling:

connection_string: "user:pass@tcp(host:3306)/db?parseTime=true&loc=UTC"

Getting started

Foundation

Agents

Tools

Resources

Prompts

Runtime

Databases

Deployment

Security

MySQL

Adapter configuration

Connection options

Connection string parameters

Recommended permissions

Verify the connection

Usage

Read replicas

Troubleshooting

Access denied

Character set issues

Connection timeout

Timezone issues

​Adapter configuration

​Connection options

​Connection string parameters

​Recommended permissions

​Verify the connection

​Usage

​Read replicas

​Troubleshooting

​Access denied

​Character set issues

​Connection timeout

​Timezone issues

Adapter configuration

Connection options

Connection string parameters

Recommended permissions

Verify the connection

Usage

Read replicas

Troubleshooting

Access denied

Character set issues

Connection timeout

Timezone issues