Your first configuration

This guide walks through building a complete Hyperterse configuration for a typical application, in this case a user management system with authentication and analytics.

Configuration formats

Hyperterse configuration is defined in a single YAML-like Terse file with the .terse extension. Read the configuration reference for more details.

Building a user management API

Let’s look at a complete configuration for a user management system.

1. Define your adapters

   Adapters are database connections. You can define multiple adapters for different databases:

   config.terse

   name: user-management-api
   
   adapters:
     # Primary PostgreSQL database
     main_db:
       connector: postgres
       connection_string: 'postgresql://app_user:secret@localhost:5432/myapp'
       options:
         max_connections: '10'
         ssl_mode: 'prefer'
   
     # Redis for caching
     cache:
       connector: redis
       connection_string: 'redis://localhost:6379/0'

   Security: Never hardcode connection strings in configuration files. Use environment variables in production:

   connection_string: '{{ env.DATABASE_URL }}'

2. Create user queries

   Add queries for common user operations:

   config.terse

   queries:
     # List users with pagination
     list-users:
       use: main_db
       description: 'List all users with pagination'
       statement: |
         SELECT id, name, email, role, created_at
         FROM users
         ORDER BY created_at DESC
         LIMIT {{ inputs.limit }}
         OFFSET {{ inputs.offset }}
       inputs:
         limit:
           type: int
           description: 'Maximum number of results'
           optional: true
           default: '20'
         offset:
           type: int
           description: 'Number of results to skip'
           optional: true
           default: '0'
   
     # Get single user by ID
     get-user-by-id:
       use: main_db
       description: 'Retrieve a user by their unique ID'
       statement: |
         SELECT id, name, email, role, created_at, updated_at
         FROM users
         WHERE id = {{ inputs.userId }}
       inputs:
         userId:
           type: int
           description: 'Unique user identifier'
   
     # Search users by email
     find-user-by-email:
       use: main_db
       description: 'Find a user by email address'
       statement: |
         SELECT id, name, email, role
         FROM users
         WHERE email = {{ inputs.email }}
       inputs:
         email:
           type: string
           description: 'Email address to search for'

3. Add analytics queries

   config.terse

   queries:
     # User signup statistics
     user-signups-by-date:
       use: main_db
       description: 'Get user signup counts grouped by date'
       statement: |
         SELECT
           DATE(created_at) as date,
           COUNT(*) as signups
         FROM users
         WHERE created_at >= {{ inputs.startDate }}
           AND created_at <= {{ inputs.endDate }}
         GROUP BY DATE(created_at)
         ORDER BY date DESC
       inputs:
         startDate:
           type: datetime
           description: 'Start of date range (ISO 8601)'
         endDate:
           type: datetime
           description: 'End of date range (ISO 8601)'
   
     # Active users count
     active-users-count:
       use: main_db
       description: 'Count users who logged in within a timeframe'
       statement: |
         SELECT COUNT(DISTINCT user_id) as active_users
         FROM sessions
         WHERE last_activity > {{ inputs.since }}
       inputs:
         since:
           type: datetime
           description: 'Count users active since this time'

4. Server configuration (optional)

   Configure server settings:

   config.terse

   server:
     port: '8080'
     log_level: 3 # 1=ERROR, 2=WARN, 3=INFO, 4=DEBUG

Complete example

Here’s the full configuration file:

config.terse

name: user-management-api

server:
  port: '8080'
  log_level: 3

adapters:
  main_db:
    connector: postgres
    connection_string: 'postgresql://app_user:secret@localhost:5432/myapp'
    options:
      max_connections: '10'

queries:
  list-users:
    use: main_db
    description: 'List all users with pagination'
    statement: |
      SELECT id, name, email, role, created_at
      FROM users
      ORDER BY created_at DESC
      LIMIT {{ inputs.limit }}
      OFFSET {{ inputs.offset }}
    inputs:
      limit:
        type: int
        optional: true
        default: '20'
      offset:
        type: int
        optional: true
        default: '0'

  get-user-by-id:
    use: main_db
    description: 'Retrieve a user by their unique ID'
    statement: |
      SELECT id, name, email, role, created_at, updated_at
      FROM users
      WHERE id = {{ inputs.userId }}
    inputs:
      userId:
        type: int
        description: 'Unique user identifier'

  find-user-by-email:
    use: main_db
    description: 'Find a user by email address'
    statement: |
      SELECT id, name, email, role
      FROM users
      WHERE email = {{ inputs.email }}
    inputs:
      email:
        type: string
        description: 'Email address'

  user-signups-by-date:
    use: main_db
    description: 'Get user signup counts grouped by date'
    statement: |
      SELECT
        DATE(created_at) as date,
        COUNT(*) as signups
      FROM users
      WHERE created_at >= {{ inputs.startDate }}
        AND created_at <= {{ inputs.endDate }}
      GROUP BY DATE(created_at)
      ORDER BY date DESC
    inputs:
      startDate:
        type: datetime
        description: 'Start of date range'
      endDate:
        type: datetime
        description: 'End of date range'

Run and test

Hyperterse can be run in development mode with hot reload:

hyperterse dev -f config.terse

Or in production mode:

hyperterse run -f config.terse

To test your queries, you can either test via the HTTP API using cURL or connect it to an agent and ask it to call the tool via MCP.

# List users
curl -X POST http://localhost:8080/query/list-users \
  -H "Content-Type: application/json" \
  -d '{"limit": 10, "offset": 0}'

# Get specific user
curl -X POST http://localhost:8080/query/get-user-by-id \
  -H "Content-Type: application/json" \
  -d '{"userId": 1}'

# View auto-generated documentation
curl http://localhost:8080/docs