hs-sql-agent
2.0.2
문서 2.0.2
문서 버전
2.0.2
2.0.2 지원 중 2.0.3 최신
문서 SQL 컴파일러

SQL 지원 레퍼런스

hs-sql-agent 2.0.2의 SQL grammar와 provider capability를 사람이 읽기 쉽게 정리합니다.

hs-sql-agent 2.0.2은 데이터베이스 provider의 전체 SQL grammar를 자동으로 신뢰하는 입력으로 취급하지 않습니다. F# parser가 statement를 표현할 수 있고, source semantics가 검증되며, 필요한 capability가 증명되고, provider runtime이 결과 immutable command를 compile할 수 있을 때만 SQL을 허용합니다.

이 페이지는 2.0.2 계약을 요약합니다. 최종 기준은 compiler이며, 미지원 또는 version-gated construct는 조용히 근사 변환되지 않고 fail-closed로 거부됩니다.

Query baseline

execute_query_sql은 하나의 SELECT statement를 받습니다. 공개 tool contract에는 다음과 같은 일반 Query 형태가 명시적으로 포함됩니다.

  • JOIN
  • WHERE
  • GROUP BY
  • HAVING
  • ORDER BY
  • LIMIT / OFFSET
  • DISTINCT
  • common table expression(CTE)
  • subquery
  • UNION, INTERSECT, EXCEPT

중첩 expression, function, window expression, cast, operator, temporal value, JSON operation 등 고급 문법은 계속 capability check를 받습니다. 위 baseline 목록만 보고 임의 vendor extension이 지원된다고 추정하면 안 됩니다.

DML baseline

execute_dml_sql은 하나의 지원 mutation을 받고 Safe DML approval을 거칩니다.

Statement2.0.2 MCP DML 상태승인 모델
UPDATEparsed/provider capability가 유효하면 지원영향 row preview, 정확한 primary-key row set에 승인 바인딩, commit transaction에서 revalidation
DELETEparsed/provider capability가 유효하면 지원영향 row preview, 정확한 primary-key row set에 승인 바인딩, commit transaction에서 revalidation
INSERT ... VALUESparsed/provider capability가 유효하면 지원immutable literal payload와 compiled command에 승인 바인딩, commit 시 승인 payload row count 검증
INSERT ... SELECT거부source-rowset approval semantics가 2.0.2에 정의되어 있지 않아 fail-closed

전체 approval protocol은 Safe DML을 참고하십시오.

여섯 provider 모델

SQL Core에는 PostgreSQL, MySQL, SQL Server, Oracle, SQLite, Firebird에 대한 provider capability contract가 있습니다. Capability 상태는 다음과 같이 구분됩니다.

  • supported — target에 필요한 native semantics가 존재
  • translated — Core에 semantics-preserving provider lowering이 선언되어 있음
  • rejected — 요청한 provider/profile에 대해 증명된 계약이 없음

일부 capability는 target server version 또는 SQL Server compatibility level에 따라 달라집니다. Runtime version이 필요하지만 안전한 baseline이 정의되지 않은 capability는 profile이 없으면 비활성 상태로 유지됩니다.

주요 provider 차이

아래 표는 중요한 2.0.2 차이를 요약한 것으로 CapabilityMatrix.fs의 모든 capability ID를 나열하는 표는 아닙니다.

CapabilityPostgreSQLMySQLSQL ServerOracleSQLiteFirebird
RIGHT JOINtranslatedtranslatedtranslatedtranslated3.39+ target profiletranslated
FULL JOINtranslatedrejectedtranslatedtranslated3.39+ target profiletranslated
aggregate FILTERnative; PostgreSQL 9.4+rejectedrejectedOracle 26ai+ profile, 추가 predicate 제한명시적 3.30+ profile명시적 4.0+ profile
aggregate-local orderingnativenativeSQL Server 14.0+ 및 compatibility level 110+Oracle 11.2+명시적 3.44+ profilerejected
DML RETURNINGtranslatedrejectedrejectedrejected명시적 3.35+ profile명시적 5.0+ profile
upsert contracttranslatedrejectedrejectedrejected명시적 3.24+ profilerejected
offset-preserving timestamptranslatedrejectedtranslatedtranslatedtranslated명시적 4.0+ profile
standalone TIMEtranslatedtranslatedtranslatedrejectedtranslatedtranslated

SQL Core의 RETURNING 및 upsert 지원이 MCP Safe DML 규칙을 바꾸지는 않습니다. Mutation은 여전히 DML runtime의 supported-statement 및 approval contract를 통과해야 합니다.

JSON capability

2.0.2 capability matrix는 PostgreSQL, MySQL, SQLite에 portable JSON extraction lowering을 선언합니다. Canonical JSON-set contract에 따른 JSON mutation은 PostgreSQL, MySQL, SQLite, SQL Server에 선언되어 있습니다.

PostgreSQL native -> / ->> operator는 JSON 결과와 text 결과 semantics가 provider-specific이므로 별도로 모델링됩니다. Cross-provider lowering에서는 fail-closed 상태이며 선언된 version contract를 만족하는 PostgreSQL target이 필요합니다.

Aggregate FILTER

Aggregate FILTER는 의도적으로 version-sensitive합니다.

  • PostgreSQL은 9.4부터 native contract를 지원하며 명시적으로 더 오래된 target은 거부됩니다.
  • SQLite는 명시적인 3.30+ server profile이 필요합니다.
  • Firebird는 명시적인 4.0+ server profile이 필요합니다.
  • Oracle은 26ai/26.0+ profile이 필요하고, Core는 Oracle lowering 전에 subquery, window function, outer reference가 들어 있는 filter predicate를 추가로 거부합니다.
  • MySQL과 SQL Server에는 이 capability에 대한 2.0.2 portable target contract가 선언되어 있지 않습니다.

따라서 “vendor가 이 SQL을 실행할 수 있다”는 사실만으로 hs-sql-agent가 이를 허용하지는 않습니다.

Join version gate

SQLite RIGHT JOIN과 FULL JOIN은 target capability profile에서 SQLite 3.39 이상을 요구합니다. FULL JOIN은 2.0.2 capability matrix에서 MySQL target에 계속 rejected입니다.

필요한 target contract를 증명할 수 없으면 해당 capability에 의존하는 Query는 거부됩니다.

DML returning과 upsert

2.0.2 target contract에는 다음이 포함됩니다.

  • PostgreSQL RETURNING 및 upsert lowering
  • 명시적 SQLite 3.35+ profile의 RETURNING
  • 명시적 Firebird 5.0+ profile의 RETURNING
  • PostgreSQL 및 SQLite 3.24+ upsert contract

다른 provider target은 이 canonical capability에 대해 2.0.2 matrix에서 rejected 상태입니다.

Fail-closed 진단

Capability failure는 일반적인 database execution error가 아닙니다. SQL Core는 source validation/source capability, target capability 같은 단계를 구분합니다. 요청한 provider/profile에서 semantics를 안전하게 표현할 수 없으면 실행 전에 statement를 거부할 수 있습니다.

운영 관점에서는 이런 오류를 compiler 우회 사유가 아니라 SQL 형태를 바꾸거나 현재 데이터베이스에서 지원되는 capability를 사용하라는 신호로 해석하십시오.

이 레퍼런스가 보장하지 않는 것

이 페이지는 모든 function name, operator spelling, cast target, JSON path form, window frame, vendor extension을 보장하지 않습니다. 2.0.2 capability matrix는 단일 문서 표보다 훨씬 상세하며 runtime-version gate도 포함합니다.

MCP client는 MCP 도구 레퍼런스에서 공개 tool contract를 확인하고, 실제 compiler acceptance를 최종적인 제한된 SQL contract로 취급하십시오.