For AI agents: the complete documentation index is available at /hclapi/llms.txt, the full documentation bundle is available at /hclapi/llms-full.txt, and this page is available as Markdown at /hclapi/docs/manifest/connections.md.
hclapi
    Install

    connection

    Declares access parameters, connection pool sizing, and lifecycle policies for a database, cache, or storage backend.

    Declaration

    A connection block takes two labels: the canonical driver identifier and a unique connection name.

    connection "<driver>" "<name>" {
  url = env("DATABASE_URL")

  pool {
    max_open_conns    = 25
    max_idle_conns    = 5
    conn_max_lifetime = "30m"
    idle_timeout      = "5m"
  }
}

    Reference the connection as connection.<driver>.<name>.

    Attributes

    AttributeTypeRequiredDescription
    Driver labelstringyesCanonical driver identifier
    Name labelstringyesUnique name within the driver namespace
    urlstringyesDSN or URI; supports env(...) resolution
    poolblocknoConnection-pool tuning parameters

    Pool settings

    AttributeTypeDefaultDescription
    max_open_connsint25Maximum number of open SQL connections
    max_idle_connsint5Maximum idle SQL connections retained
    conn_max_lifetimeDuration"30m"Maximum reuse duration
    idle_timeoutDuration"5m"Maximum idle duration before eviction
    sizeint20Pool capacity for cache/key-value drivers

    Supported drivers

    DriverCategoryTypical targets
    postgresRelational SQLPostgreSQL, Supabase, TimescaleDB, Aurora PostgreSQL
    sqliteEmbedded SQLSQLite, Turso, LibSQL
    mysqlRelational SQLMySQL, MariaDB, PlanetScale, TiDB, Aurora MySQL
    sqlserverRelational SQLSQL Server, Azure SQL
    oracleRelational SQLOracle Database 11g–23ai
    cockroachdbDistributed SQLCockroachDB
    clickhouseColumnar SQLClickHouse Cloud / self-hosted
    duckdbEmbedded analyticsDuckDB
    redisKey-value/cacheRedis, Valkey, ElastiCache
    s3Blob storageS3, R2, MinIO, GCS-compatible endpoints

    Example: primary and replica pools

    connection "postgres" "primary" {
  url = env("DATABASE_PRIMARY_URL")

  pool {
    max_open_conns    = 50
    max_idle_conns    = 10
    conn_max_lifetime = "1h"
    idle_timeout      = "10m"
  }
}

connection "postgres" "replica" {
  url = env("DATABASE_REPLICA_URL")

  pool {
    max_open_conns = 100
    max_idle_conns = 20
  }
}

    Reference in a pipeline

    endpoint "GET /api/v1/users/{id}" {
  pipeline {
    sql "find_user" {
      connection = connection.postgres.replica
      query      = "SELECT id, name, email FROM users WHERE id = @id"
      args       = { id = ctx.request.path.id }
    }

    redis "cache_user" {
      connection = connection.redis.cache
      command    = "SET"
      key        = "user:${ctx.request.path.id}"
      value      = json_encode(steps.find_user.row)
      ttl        = "15m"
    }

    respond {
      status = 200
      body   = steps.find_user.row
    }
  }
}