agens 클라이언트

agens는 대화형 터미널 클라이언트입니다. PostgreSQL의 psql을 AgensGraph 이름으로 부르는 것이며, 여기에 그래프를 설명하는 메타 명령 다섯 개가 더해져 있습니다.

psql이므로 모든 옵션과 모든 변수와 그 밖의 모든 메타 명령은 PostgreSQL의 psql 레퍼런스가 문서화합니다. 그것을 여기서 되풀이하지 않습니다. 이 페이지가 다루는 것은 둘입니다. 다른 어디에도 없는 그래프 메타 명령, 그리고 AgensGraph의 것인 환경 세부 두 가지입니다.

이름 둘을 가진 같은 프로그램

빌드는 같은 소스에서 바이너리 두 개를 만들어 둘 다 설치합니다. 차이는 브랜딩뿐입니다. 각자가 출력하는 이름, 그리고 도움말의 버그 신고 줄과 홈페이지 줄입니다.

agens --version
psql --version

agens (AgensGraph) 2.18.6.0
psql (PostgreSQL) 18.6

두 도움말을 diff 하면 차이 전부가 드러납니다:

diff <(agens --help) <(psql --help)

62,63c62,63
< Report bugs to <agens@bitnine.net>.
< AgensGraph home page: <https://bitnine.net/>
---
> Report bugs to <pgsql-bugs@lists.postgresql.org>.
> PostgreSQL home page: <https://www.postgresql.org/>

여기서 결론 둘이 따라오고, 둘 다 일을 덜어 줍니다.

psql에 대해 아는 것이 그대로 적용됩니다. 같은 옵션, 같은 ~/.psqlrc, 같은 PG* 환경 변수, 같은 \copy, \watch, \gexec, \timing, \x, \pset, 같은 탭 완성과 변수 치환입니다.

agens -d docs -c "SHOW agversion;"

 agversion
------------
 2.18.6.0

그래프 메타 명령은 두 바이너리에 다 있습니다. 둘은 같은 오브젝트로 빌드되므로, 이 설치본의 psql도 agens와 똑같이 그래프를 나열합니다. 이미 psql이 경로에 있다면 그래프를 설명하려고 클라이언트를 바꿀 필요가 없습니다.

서버 도구도 같은 방식을 따르며, 이름이 바뀐 쌍이 하나 있습니다:

AgensGraph 이름	PostgreSQL 이름	차이
agens	psql	브랜딩뿐입니다. 둘 다 설치됩니다.
ag_ctl	pg_ctl	브랜딩뿐입니다. 둘 다 설치됩니다.

그 밖의 모든 도구는 PostgreSQL 이름을 그대로 지니며 그 이름뿐입니다. initdb, postgres, pg_dump, pg_dumpall, pg_restore, pg_basebackup, pg_upgrade, pg_controldata, pg_checksums, pg_rewind, pg_waldump, createdb, dropdb, createuser, dropuser, vacuumdb, reindexdb, clusterdb, pgbench, ecpg와 나머지가 그렇습니다. ag_dump도 ag_basebackup도 없습니다. 이 도구들이 그래프를 어떻게 다루는지는 서버 측 도구가 다룹니다.

그래프 메타 명령

메타 명령 다섯 개가 그래프를 설명합니다. +는 각각에 컬럼을 더하고, 패턴은 나열 대상을 좁힙니다.

명령	나열하는 것
\dG[+] [PATTERN]	그래프입니다.
\dGl[+] [PATTERN]	레이블 두 종류 모두입니다.
\dGv[+] [PATTERN]	정점 레이블, 그리고 각각의 설명입니다.
\dGe[+] [PATTERN]	간선 레이블, 그리고 각각의 설명입니다.
\dGi[+] [PATTERN]	속성 인덱스입니다.

대소문자가 중요합니다. \dG는 그래프를 나열합니다. \dg는 PostgreSQL 자신의 명령이며 롤을 나열합니다.

이 다섯이 전부이고, 그중 어느 것도 \?에 나오지 않습니다. 다른 \d 명령이 받는 x와 S 수식자는 \dG 바로 뒤에서는 받아들여지지 않습니다:

\dGx moviekb

invalid command \dGx

x는 하위 명령 네 개에서는 동작하므로, \dGvx는 목록을 확장 모드로 출력합니다.

아래 예제는 모두 예제 데이터셋을 상대로 실행합니다.

데이터베이스의 그래프 나열하기

\dG moviekb

 List of graphs
  Name   | Owner
---------+-------
 moviekb | agens

+는 그래프의 접근 권한과 주석을 더합니다. 그래프는 스키마이므로 그 권한은 스키마 권한입니다. 무엇인가 부여하기 전에는 비어 있으므로, 컬럼이 채워진 것을 보려면 하나를 부여하십시오:

GRANT USAGE ON SCHEMA moviekb TO PUBLIC;

\dG+ moviekb

                  List of graphs
  Name   | Owner | Access privileges | Description
---------+-------+-------------------+-------------
 moviekb | agens | agens=UC/agens   +|
         |       | =U/agens          |

예제 데이터셋을 원래대로 두기 위해 다시 회수합니다:

REVOKE USAGE ON SCHEMA moviekb FROM PUBLIC;

패턴을 주지 않으면 \dG는 데이터베이스의 모든 그래프를 나열합니다.

그래프의 레이블 나열하기

\dGl은 두 종류를 함께 나열하며, 그래프·종류·이름 순으로 정렬합니다:

\dGl moviekb.*

            List of labels
  Graph  |    Name    |  Type  | Owner
---------+------------+--------+-------
 moviekb | acted_in   | edge   | agens
 moviekb | ag_edge    | edge   | agens
 moviekb | directed   | edge   | agens
 moviekb | related_to | edge   | agens
 moviekb | ag_vertex  | vertex | agens
 moviekb | movie      | vertex | agens
 moviekb | person     | vertex | agens

모든 그래프가 ag_vertex와 ag_edge를 가지므로 그 둘이 함께 나옵니다. 레이블 상속을 참고하십시오.

+는 레이블의 디스크 크기와 주석을 더합니다. 크기는 레이블 테이블의 pg_table_size이므로, 적재한 만큼을 반영합니다:

\dGl+ moviekb.*

                                     List of labels
  Graph  |    Name    |  Type  | Owner |    Size    |            Description
---------+------------+--------+-------+------------+------------------------------------
 moviekb | acted_in   | edge   | agens | 16 kB      |
 moviekb | ag_edge    | edge   | agens | 8192 bytes | base edge label of graph moviekb
 moviekb | directed   | edge   | agens | 16 kB      |
 moviekb | related_to | edge   | agens | 16 kB      |
 moviekb | ag_vertex  | vertex | agens | 8192 bytes | base vertex label of graph moviekb
 moviekb | movie      | vertex | agens | 16 kB      |
 moviekb | person     | vertex | agens | 16 kB      |

정점 레이블 설명 보기

\dGv는 목록을 정점 레이블로 좁힌 다음, \d가 테이블의 꼬리말을 출력하듯 각각에 대한 블록을 출력합니다. 블록에는 그 레이블의 속성 인덱스와 제약, 그 레이블이 상속하는 레이블과 그 레이블을 상속하는 레이블이 담깁니다:

\dGv moviekb.*

            List of labels
  Graph  |   Name    |  Type  | Owner
---------+-----------+--------+-------
 moviekb | ag_vertex | vertex | agens
 moviekb | movie     | vertex | agens
 moviekb | person    | vertex | agens

Vertex label "moviekb.ag_vertex"
--
Child labels: moviekb.movie,
              moviekb.person

Vertex label "moviekb.movie"
--
Inherits: moviekb.ag_vertex

Vertex label "moviekb.person"
--
Inherits: moviekb.ag_vertex

인덱스와 제약이 있는 레이블은 둘 다 보여 줍니다:

CREATE GRAPH demo;
SET graph_path = demo;
CREATE VLABEL book;
CREATE PROPERTY INDEX ON book (title);
CREATE CONSTRAINT book_isbn_uq ON book ASSERT isbn IS UNIQUE;

\dGv demo.book

        List of labels
 Graph | Name |  Type  | Owner
-------+------+--------+-------
 demo  | book | vertex | agens

Vertex label "demo.book"
--
Property Indexes:
    "book_title_idx" btree (title)
Constraints:
    "book_isbn_uq" ASSERT (isbn) IS UNIQUE
Inherits: demo.ag_vertex

블록이 보여 주지 않는 것에 유의하십시오. 레이블의 컬럼입니다. id와 properties, 그리고 승격된 컬럼을 보려면 레이블이 테이블이므로 그 테이블에 \d를 쓰십시오:

\d moviekb.movie

                                                          Table "moviekb.movie"
   Column   |  Type   | Collation | Nullable |                                          Default
------------+---------+-----------+----------+-------------------------------------------------------------------------------------------
 id         | graphid |           | not null | graphid(graph_labid('moviekb.movie'::cstring), nextval('moviekb.movie_id_seq'::regclass))
 properties | jsonb   |           | not null | jsonb_build_object()
Indexes:
    "movie_pkey" PRIMARY KEY, btree (id)
Inherits: moviekb.ag_vertex

간선 레이블 설명 보기

\dGe는 간선에 대한 \dGv이며, 블록의 모양도 같습니다:

\dGe moviekb.acted_in

          List of labels
  Graph  |   Name   | Type | Owner
---------+----------+------+-------
 moviekb | acted_in | edge | agens

Edge label "moviekb.acted_in"
--
Inherits: moviekb.ag_edge

이 블록을 출력하지 않는 것이 \dGl입니다. 그것은 두 종류의 요약일 뿐, 그 이상이 아닙니다.

속성 인덱스 나열하기

\dGi는 ag_property_indexes를 읽어 각 인덱스의 Cypher 정의, 즉 다시 만들 때 입력할 그 문장을 보여 줍니다. 속성 인덱스가 없는 그래프는 아무것도 나열하지 않습니다:

\dGi moviekb.*

No matching property indexes found.

\dGi demo.*

                                                List of property indexes
 Graph | LabelName |   IndexName    | Unique | Owner |                             Indexdef
-------+-----------+----------------+--------+-------+------------------------------------------------------------------
 demo  | book      | book_title_idx | f      | agens | CREATE PROPERTY INDEX book_title_idx ON book USING btree (title)

+는 인덱스의 크기와 주석을 더합니다:

\dGi+ demo.*

                                                             List of property indexes
 Graph | LabelName |   IndexName    | Unique | Owner |                             Indexdef                             |    Size    | Description
-------+-----------+----------------+--------+-------+------------------------------------------------------------------+------------+-------------
 demo  | book      | book_title_idx | f      | agens | CREATE PROPERTY INDEX book_title_idx ON book USING btree (title) | 8192 bytes |

고유성 제약은 속성 인덱스가 아니므로 여기에 나오지 않습니다. 그것은 자기 레이블의 \dGv나 \dGe 블록에, 그리고 \d에서는 제외 제약으로 나타납니다.

DROP GRAPH demo CASCADE;

NOTICE:  drop cascades to 4 other objects
DETAIL:  drop cascades to sequence demo.ag_label_seq
drop cascades to vlabel ag_vertex
drop cascades to elabel ag_edge
drop cascades to vlabel book
DROP GRAPH

패턴으로 목록 좁히기

패턴은 PostgreSQL의 \d 패턴 언어이며, 점으로 구분한 이름 두 부분에 적용됩니다. 그 언어에는 *와 ? 와일드카드, 문자 클래스, 그리고 대소문자 접기를 막는 큰따옴표가 있습니다.

그 두 부분이 무엇인지는 명령마다 다르고, 그 차이에서 자주 헷갈립니다:

명령	첫째.둘째의 뜻
\dG	그래프 이름입니다. 둘째 부분은 없습니다.
\dGl, \dGv, \dGe	그래프, 그다음 레이블 이름입니다.
\dGi	그래프, 그다음 인덱스 이름입니다.

그래서 \dGi moviekb.movie는 아무것도 찾지 못합니다. movie가 인덱스 이름과 대조되기 때문입니다:

\dGi moviekb.movie

No matching property indexes found.

대신 인덱스 이름을 대거나, moviekb.*를 쓰고 LabelName 컬럼을 읽으십시오. 아무것도 일치하지 않는 패턴은 그렇다고 말하며, 오류가 아닙니다:

\dGv nosuchgraph.*

No matching labels found.

AGDATA

AGDATA는 PGDATA가 그러하듯 데이터 디렉터리를 가리킵니다. 이것을 읽는 프로그램은 정확히 셋입니다. initdb와 pg_ctl과 ag_ctl입니다. 다른 도구는 읽지 않습니다. agens도, psql도, pg_dump도, pg_basebackup도 읽지 않습니다. 그러므로 모든 것이 존중하는 변수를 설정하고 싶다면 여전히 PGDATA를 설정해야 합니다.

한 번 export 해 두면 그 셋은 -D가 필요 없어집니다:

export AGDATA=/tmp/agensdata
ag_ctl status

ag_ctl: no server running

둘 다 읽는 두 프로그램 사이에서 우선순위가 다르므로, 둘 다 설정하기 전에 확인하십시오:

프로그램	순서
initdb	-D, 그다음 AGDATA, 그다음 PGDATA입니다.
pg_ctl과 ag_ctl	-D, 그다음 PGDATA, 그다음 AGDATA입니다.

initdb는 결정을 내린 뒤 자기 환경에도 AGDATA를 설정하며, 마지막 힌트는 ag_ctl을 가리킵니다:

env -u PGDATA AGDATA=/tmp/agensdata initdb -U agens --no-sync

Success. You can now start the database server using:

    ag_ctl -D /tmp/agensdata -l logfile start

두 변수 모두 설정하지 않고 -D도 주지 않으면 메시지는 PGDATA만 가리킵니다. AGDATA도 똑같이 동작했을 것입니다:

ag_ctl status

ag_ctl: no database directory specified and environment variable PGDATA unset
Try "ag_ctl --help" for more information.

데이터 디렉터리를 어디에 두고 init 시스템에서 서버를 어떻게 기동하는지는 배포가 다룹니다.

관련 항목

• 서버 측 도구 — ag_ctl·pg_dump·pg_upgrade와 그래프

• 예제 데이터셋 — 위의 모든 목록이 설명하는 그래프

• 시스템 카탈로그 — 이 명령들이 조회하는 ag_graph·ag_label· ag_property_indexes

• 서버 설정 — 세션이 Cypher를 실행하기 전에 필요한 graph_path

• PostgreSQL: psql — 모든 옵션과 그 밖의 모든 메타 명령

• PostgreSQL: pg_ctl — ag_ctl이 무엇인가