드라이버와 클라이언트 라이브러리#

AgensGraph는 PostgreSQL 통신 프로토콜을 쓰므로, 어떤 PostgreSQL 드라이버로도 접속해 Cypher를 실행할 수 있습니다. 프로토콜이 보기에 Cypher 문장은 그저 문장 하나입니다. AgensGraph를 쓰는 데 그래프 전용 클라이언트가 필요하지 않습니다.

드라이버가 도움 없이 하지 못하는 것은 그래프 타입을 해석하는 일입니다. m.title 을 반환하는 쿼리는 모든 드라이버가 아는 jsonb 를 돌려주지만, m 을 반환하는 쿼리는 vertex 를, 경로 패턴의 p 는 graphpath 를 돌려줍니다. 보통의 드라이버는 그것들을 텍스트로 봅니다. AgensGraph를 위해 쓰인 드라이버는 타입 처리를 더하므로, 정점이 자기 레이블과 id와 속성을 지닌 객체로 도착합니다.

그래서 방법은 두 가지입니다:

이미 쓰고 있는 PostgreSQL 드라이버를 쓰십시오. 요소 전체가 아니라 속성을 반환하고, jsonb 대신 평범한 스칼라를 원하는 곳에서는 Cypher를 SQL로 감싸십시오. SQL과 Cypher 섞기를 참고하십시오. 코드도 의존성도 가장 적고, Python이 아닌 언어에서는 이 길이 맞습니다.

정점과 간선과 경로를 네이티브 객체로 받고 싶을 때, 또는 AI 연동을 기반으로 만들 때는 Python 드라이버를 쓰십시오.

Python 드라이버#

기반으로 삼을 드라이버는 AgensGraph for Python입니다. psycopg 3 위에 그래프 타입 처리를 더하며, 모든 AI 연동이 이 드라이버 위에서 동작합니다. 설치와 사용법은 그 매뉴얼에 있습니다.

LangChain·LlamaIndex·LightRAG·cognee와 MCP 서버가 모두 이 드라이버를 기반으로 합니다. AI·LLM 연동을 참고하십시오.

다른 언어#

Java·Node.js·Go에서는 보통의 PostgreSQL 드라이버 — pgjdbc, node-postgres, pgx — 를 쓰고, 위에서 말한 대로 요소 전체가 아니라 속성을 읽으십시오. 지금 기반으로 삼기에 알맞은 조합은 이것입니다.

그 세 언어를 위한 드라이버도 있기는 하며, 새로 시작하는 자리가 아니라 이미 쓰고 있는 프로젝트를 위해 여기에 남겨 둡니다:

  • Java / JDBC legacy — pgjdbc의 포크이며 2023년 1월에 net.bitnine:agensgraph-jdbc:1.4.3 으로 배포됐습니다.

  • Node.js legacy — node-postgres를 감싸며 pg >= 6.1.2 를 대상으로 합니다. 2025년 9월에 @skaiworldwide/ag-driver 1.1.0으로 배포됐습니다.

  • Go legacy — lib/pq 위에 만들어졌고 태그 v0.1.1 의 Go 모듈로 배포됩니다.

접속과 매개변수#

접속에 graph_path 를 설정하십시오. 세션별이므로, 풀에서 꺼내 주는 접속은 꺼낼 때마다 설정해야 합니다. 아니면 롤이나 데이터베이스에 한 번 설정하십시오:

ALTER ROLE appuser SET graph_path = moviekb;

Python 드라이버의 ConnectionPool 은 graph= 로 받은 그래프를 접속을 열 때 한 번만 설정하고 꺼내 줄 때마다 다시 설정하지는 않으므로, 접속을 빌려 간 쪽이 graph_path 를 바꾸고 커밋하면 그 값이 다음에 빌려 가는 쪽으로 넘어갑니다.

Cypher 매개변수에는 타입을 주십시오. 드라이버가 타입을 정해 주지 않은 매개변수는 JSON으로 파싱되므로, 평범한 문자열은 실패합니다:

ERROR:  invalid input syntax for type json
DETAIL:  Token "The" is invalid.
CONTEXT:  JSON data, line 1: The...

드라이버의 API로 매개변수의 타입을 선언하거나, 문장 안에서 형 변환하십시오:

MATCH (m:movie {title: $1::text}) RETURN m.year;

형 변환이 이식성 있는 형태이고 비용도 들지 않습니다. 값이 어느 쪽으로도 읽힐 수 있는 곳에서 가장 중요합니다. 타입이 없으면 '123' 이 숫자 123으로 도착해, 문자열 "123" 을 담은 속성과 일치하지 않게 됩니다.

Python 드라이버는 타입을 대신 선언해 줍니다. 2.0부터는 Python str 을 text 로 보내므로 문자열 매개변수는 따로 형 변환할 필요가 없습니다. 다만 문자열을 다른 타입으로 받아야 하는 자리에서는 여전히 %s::date 처럼 형 변환해야 합니다.