| PostgreSQL 8.3.3문서 | ||||
|---|---|---|---|---|
| Prev | Fast Backward | Chapter 29. libpq - C 라이브러리 | Fast Forward | Next |
PostgreSQL의 백엔드 서버와의 접속을 생성하려면 , 이하의 함수를 사용합니다.
응용 프로그램은 백엔드와의 접속을 한 번에 여러개 열 수 있습니다. (한 가지 이유로 여러 데이터베이스로의 액세스를 들 수 있습니다. )
개개의 접속은 PQconnectdb 또는 PQsetdbLogin함수를 호출하여 얻을 수 있는 PGconn오브젝트로 나타납니다.
이러한 함수는 항상 NULL이 아닌 오브젝트 포인터를 반환합니다. PGconn 오브젝트를 할당할 수 없는 경우가 아닌 이상
NULL이 아닌 브젝트의 포인터를 반환합니다.
또한, 이 접속 오브젝트를 통해 쿼리를 보내기 전에, PQstatus함수를 호출해, 데이터베이스와의 접속에 성공했는지 여부를 체크해야 합니다.
PQconnectdb
새롭게 데이터베이스 서버로의 접속을 생성합니다.
PGconn *PQconnectdb(const char *conninfo);
이 함수는 conninfo 문자열로부터 취득한 파라미터를 사용하고, 데이터베이스와의 접속을 확립합니다.
이하의 PQsetdbLogin과는 달리, 함수의 prototype를 변경하지 않고 파라미터를 확장할 수 있기 때문에, 응용 프로그램을 생성하려면,
이 함수(혹은 nonblocking analogue PQconnectStart와 PQconnectPoll)을 사용하는 것을 추천합니다.
빈 문자열을 건네주는 것으로, 모든 파라미터는 디폴트로 사용할 수 있습니다. 또한, 공백 문자로 분리하여 1개 이상의 파라미터를 설정할 수 있습니다. 각각의 파라미터는 keyword = value라고 하는 형태로 설정합니다. 등호 전후의 공백 문자는 임의로 붙일 수 있습니다. 비어있는 값이나 공백 문자를 포함한 값을 쓰는 경우는 단일 인용부호로 둘러쌉니다. 예를 들면, keyword = 'a value'입니다. 단일 인용부호와 backslash는 \'나 \\와 같이, backslash로 이스케이프 해야 합니다.
현시점에서 유효한 파라미터의 키워드는 이하에 나타내는 대로입니다.
접속하는 호스트명을 지정합니다. 이 인자 리스트를 slash로 시작했을 경우, TCP/IP에 의한 통신이 아닌 Unix 도메인의 통신을 지정하게 됩니다. 그 경우, 이 값은 소켓 파일을 저장하는 디렉토리의 이름이 됩니다. host가 지정되지 않은 경우, 디폴트는 /tmp에 있는 Unix 도메인의 소켓에 접속하도록 합니다. (또는 PostgreSQL의 구축시에 지정한 다른 디렉토리에 있는 소켓입니다. ) Unix 도메인 소켓이 없는 머신에서 디폴트는 localhost에 접속하는 것입니다.
접속하는 호스트의 IP주소를 지정합니다. 이는 172.28. 40.9라고 하는 표준적인 IPv4 주소 서식이 아니면 안됩니다. 사용하는 머신으로 IPv6를 서포트하는 경우는 그 주소를 사용할 수도 있습니다. 이 파라미터에 비어있지 않은 문자열이 지정되면, TCP/IP통신이 항상 사용됩니다.
host대신에hostaddr를 사용하여, 어플리케이션이 호스트명의 검색을 하지 않고 끝납니다. 특히, 시간 제약이 있는 어플리케이션에서는 중요할 것입니다. 그러나 Kerberos 및 GSSAPI 인증을 실시하는 어플리케이션에서는 호스트명이 필요하게 됩니다. 결국, 이하와 같이 됩니다. hostaddr를 사용하지 않고host를 지정했을 경우는 호스트명의 검색이 발생합니다. host를 사용하지 않고, hostaddr를 지정했을 경우, hostaddr는 리모트 머신의 주소가 됩니다. 이 때, Kerberos를 사용하고 있는 경우, 반대되는 이름의 쿼리는 Kerberos의 호스트명을 획득하기 위해 발생합니다. host와 hostaddr의 양쪽 모두를 지정했을 경우, hostaddr가 리모트 머신의 주소가 됩니다. 이 때, Kerberos가 사용하면서도 host의 값이 무시되어 사용되고 있는 경우는 Kerberos 인증에host의 값이 사용됩니다. (libpq에게 건네진 호스트명이, hostaddr에 대응하는 머신의 이름과 일치하지 않는 경우는 인증에 실패할 가능성이 있으므로, 주의하십시요. ) 또한, hostaddr는 아니고host가~/. pgpass(Section 29.13를 참조)에서의 접속의 식별로 사용됩니다.
호스트명이나 호스트의 주소도 이용하지 않는 경우, libpq는 로컬 Unix 도메인의 소켓을 사용해 접속합니다. 다만, Unix 도메인 소켓을 가지지 않는 머신에서는 localhost의 접속을 시도합니다.
서버 호스트에서의 접속용의 포트 번호, 또는 Unix 도메인 접속의 경우는 소켓 파일의 확장자(extension)를 지정합니다.
데이터베이스명을 지정합니다. 디폴트는 유저명과 같습니다.
데이터베이스에 접속하는 PostgreSQL유저명을 지정합니다. 디폴트는 그 어플리케이션을 실행하고 있는 유저의 operating system상의 이름과 같습니다.
서버가 패스워드에 의한 인증을 요구하는 경우에 패스워드를 사용합니다.
접속을 위해 최대 대기 시간을 초단위로 지정합니다. (10 진수 정수로 나타낸 문자열로서 기술해 주십시요. ) 0 또는 설정하지 않는 것은 무한 시간의 대기를 의미합니다. 2초 미만의 대기 시간을 사용하는 것은 권하지 않습니다.
서버에 전송하는 커맨드 라인 옵션을 지정합니다.
무시됩니다. (이전에는 이것은 서버 디버그 출력을 전송하는 장소를 지정하는 것이었습니다. )
이 옵션은 어느SSL접속에서 우선적으로 서버와 조정할까를 결정합니다. 4개의 모드가 있습니다. disable는 암호화하지 않는 SSL접속만을 시도합니다. allow는 우선 nonSSL접속을 시도해 실패하면SSL로 시도합니다. prefer(디폴트입니다)는 우선SSL접속을 시도해 실패하면 보통의 비SSL접속으로 시도합니다. require는 SSL접속에서만 시도됩니다.
SSL 서포트없이PostgreSQL가 컴파일 되었을 경우, require를 사용하면 에러가 됩니다. 한편, allow와 prefer는 사용할 수 있지만, 실제로libpq는 SSL접속을 받아들이지 않습니다.
이 옵션은 sslmode설정에 의해 쓸모없게 된 것이 되었습니다.
1으로 설정하면, 서버에 SSL접속이 요구됩니다. (이것은sslmode의require와 같습니다. ) 서버가SSL접속을 받아들이지 않는 경우, Libpq는 접속을 거절합니다. 0(디폴트)으로 설정하면, 서버와 조정을 실시합니다. (sslmode의prefer와 같습니다.) SSL 서포트 첨부로PostgreSQL를 컴파일 했을 경우에만, 이 옵션을 이용할 수 있습니다.
Kerberos5 또는 GSSAPI의 인증시에 사용되는 Kerberos 서비스명입니다. 이것은 서버의 Kerberos 인증 설정의 서비스명과 일치해야만 합니다. (Section 20.2.3도 참조해 주십시요.)
다른 파라미터용으로 사용되는 서비스명입니다. pg_service.conf내의 추가적인 접속 파라미터를 보관하는 서비스명을 지정합니다. 이것에 의해 어플리케이션은 서비스명만을 지정할 수 있어 접속 파라미터를 집중적으로 보수할 수 있게 됩니다. 자세한 사항은 Section 29.14 을 참조해 주십시요.
파라미터가 지정되지 않은 경우는 상응하는 환경 변수가 체크됩니다(Section 29.12를 참조해 주십시요). 환경 변수도 설정되어 있지 않은 경우는 내장 디폴트 값이 지정됩니다.
PQsetdbLogin
새롭운 데이터베이스 서버 접속을 생성합니다.
PGconn *PQsetdbLogin(const char *pghost,
const char *pgport,
const char *pgoptions,
const char *pgtty,
const char *dbName,
const char *login,
const char *pwd);
이것은 파라미터 세트를 고정하는 PQconnectdb프로시저입니다.
설정할 수 없는 파라미터가 항상 디폴트 값이 되는 점을 제외하고, 동일한 기능을 가집니다.
고정된 파라미터에 대해서 NULL나 공문자열을 입력하면, 그것은 디폴트가 됩니다.
PQsetdb
새롭게 데이터베이스 서버의 접속을 생성합니다.
PGconn *PQsetdb(char *pghost,
char *pgport,
char *pgoptions,
char *pgtty,
char *dbName);
이는 login와 pwd에 null 포인터를 설정하는 PQsetdbLogin를 호출하는 매크로입니다.
매우 오래된 프로그램의 백엔드 호환성을 위해서 제공되고 있습니다.
PQconnectStart
PQconnectPoll
차단하지 않는 방법으로, 데이터베이스 서버의 접속을 생성합니다.
PGconn *PQconnectStart(const char *conninfo);
PostgresPollingStatusType PQconnectPoll(PGconn *conn);
이 2개의 함수를 사용하고, 리모트 I/O의 실행시에 어플리케이션 thread의 실행이 차단되지 않도록 데이터베이스 서버로의 접속을 생성합니다.
이러한 접근 포인트는 I/O 의 종료 대기는 PQconnectdb내부 보다는 응용 프로그램의 메인 루프에서 발생 할 수 있습니다.
이것에 의해, 어플리케이션은 다른 처리와 병행해서 관리할 수 있습니다.
PQconnectStart에 건네진conninfo문자열에서 파라미터를 가져와 데이터베이스 접속이 확립되게 됩니다.
이 문자열은 위의PQconnectdb의 경우와 같은 형식으로 기술되고 있습니다.
PQconnectStart와 PQconnectPoll는 이하의 제약에서는 차단되지 않습니다.
The hostaddr and host parameters are used appropriately to ensure that
name and reverse name queries are not made. See the documentation of
these parameters under PQconnectdb above for details.
-->
hostaddr와 host파라미터는 호스트명으로부터의 IP주소 검색이나 호스트명의 반대 쿼리가 일어나지 않도록 적절히 사용되어야 합니다.
이러한 파라미터에 대한 자세한 사항은, 위의 PQconnectdb를 참조해 주십시요.
PQtrace를 호출하는 경우는 trace에 사용하는 stream 오브젝트가 차단되지 않는다는 것이 확실해야 합니다.
PQconnectPoll를 호출하기 전에 소켓이 적절한 상태에 있다는 것을 보증해야 합니다.
nonblock 접속을 시작하려면 우선, conn=PQconnectStart("
connection_info_string
")를 호출합니다.
conn가 null일 경우, libpq가 새로운 PGconn구조를 할당할 수 없는 것을 나타냅니다.
그렇지 않은 경우는 적절한 PGconn 포인터가 반환됩니다
(다만, 데이터베이스에 올바르게 접속되는지를 나타내지는 않습니다).
PQconnectStart로부터 값이 되돌아 온 단계에서, status=PQstatus(conn)를 호출합니다.
만약, status가CONNECTION_BAD와 동일한 경우, PQconnectStart가 실패하게 됩니다.
PQconnectStart가 성공하면, 다음은 접속 순서를 진행시키기 위해서, libpq를 폴링 합니다.
데이터베이스 접속의 배후에 있는 소켓의 기술자를 꺼내려면 , PQsocket(conn)를 사용합니다.
이하의 반복입니다.
직전의PQconnectPoll(conn)이PGRES_POLLING_READING의 경우, 소켓의 read 준비가 갖춰질 때까지 대기합니다.
(select()나 poll()등의 시스템 함수로 나타납니다. )
그리고 재차PQconnectPoll(conn)를 호출합니다.
반대로 마지막 PQconnectPoll(conn)이 PGRES_POLLING_WRITING의 경우, 소켓의 기입 준비가 갖춰질 때까지 대기해,
그 후, PQconnectPoll(conn)를 재차 호출합니다.
아직PQconnectPoll를 호출하지 않은 경우, 즉, PQconnectStart의 호출 직후로는 직전이PGRES_POLLING_WRITING였을 경우와 같은 처리를 행합니다.
이 반복을PQconnectPoll(conn)이, 접속 수속의 실패를 나타내는 PGRES_POLLING_FAILED,
혹은 접속 확립에 성공한 것을 나타내는 PGRES_POLLING_OK를 반환할 때까지 계속합니다.
접속하고 있는 동안은 언제든지 PQstatus를 호출하여, 접속 상태를 체크할 수 있습니다.
이 함수가CONNECTION_BAD를 반환할 경우, 접속 절차가 실패한 것이며, CONNECTION_OK를 돌려주는 경우, 접속이 확립된 것입니다.
위에서 설명한 바와 같이, 이러한 상태들은 모두 PQconnectPoll의 반환 값으로 검출할 수 있습니다.
다른 상태는 비동기의 접속 절차 동안 나타잡니다.
이것은 접속 프로시저의 현재의 단계를 나타내는 것으로, 예를 들면 유저에게로의 피드백을 제공하는 것에 사용할 수 있습니다.
이하 상태가 있습니다.
접속의 확립 대기 상태입니다.
접속은 OK입니다. 전송 대기 상태입니다.
서버로부터의 응답 대기 상태입니다.
인증이 끝난 상태입니다. 백엔드 시작 대기 상태입니다.
SSL 암호화의 조정 상태입니다.
환경이 제공하는 파라미터 설정의 조정 상태입니다.
이러한 정수가 (호환성 유지를 위해) 남는 다면, 어플리케이션은 특정한 순서로 이들이 발생되거나 전혀 그렇지 않거나, 문서화된 값의 상태로 항상 머무는 것에 결코 의존해서는 않됩니다. 어플리케이션은 이하에 나타내도록 해야 합니다.
switch(PQstatus(conn))
{
case CONNECTION_STARTED:
feedback = "Connecting...";
break;
case CONNECTION_MADE:
feedback = "Connected to server...";
break;
.
.
.
default:
feedback = "Connecting...";
}
PQconnectPoll를 사용하는 경우, connect_timeout접속 파라미터는 무시됩니다.
경과시간이 너무 길지 어떨지의 판정은 어플리케이션의 책임으로 결정됩니다.
그렇지 않으면, PQconnectStart의 뒤의PQconnectPoll의 루프는 PQconnectdb와 같게 됩니다.
PQconnectStart가 NULL이 아닌 포인터를 돌려주었을 경우, 처리를 종료하려면, 구조나 관련되는 메모리 블록을 처리하기 위해 PQfinish를 호출해야 합니다.
이 처리는 접속 시도가 실패했거나 중단되는 경우에, 반드시 실행되어야 합니다.
PQconndefaults
디폴트의 접속 옵션을 반환합니다.
PQconninfoOption *PQconndefaults(void);
typedef struct
{
char *keyword; /* 이 옵션의 키워드 */
char *envvar; /* 대체 되는 환경 변수의 이름 */
char *compiled; /* 대체 되는 컴파일시에 디폴트치 */
char *val; /* 옵션의 현재 값, 혹은 NULL */
char *label; /* 접속 다이얼로그 내의 해당 필드의 라벨 */
char *dispchar; /* 접속 다이얼로그 내의 해당 필드에서 표시하는 문자
값:
"" 입력된 값을 그대로 표시
"*" 값을 숨기는 패스워드 필드용
"D" 디버그 옵션. 디폴트로 아무것도 표시하지 않습니다 */
int dispsize; /* 다이얼로그용의 필드의 크기(문자 수 단위) */
} PQconninfoOption;
접속 옵션의 배열을 반환합니다.
이는 사용 가능한PQconnectdb 옵션 모두나, 그 시점에서의 디폴트치를 결정하기 위해서 사용할 수 있습니다.
반환 값은 PQconninfoOption구조의 배열 포인터로, keyword포인터가 NULL이 되는 항목이 배열의 마지막에 옵니다.
메모리를 확보될 수 없었던 경우는 null 포인터를 반환합니다.
현재의 디폴트치(val 필드)는 환경 변수나 다른 문맥에 의존합니다.
호출측에서는 접속 옵션의 정보는 read 전용으로만 다뤄야 합니다.
옵션 배열을 처리한 후에는 PQconninfoFree를 사용해 해제합니다.
이 처리를 하지 않으면PQconndefaults가 호출될 때마다 조금씩 메모리 리크가 발생합니다.
PQfinish
서버와의 접속을 닫습니다. 또한, PGconn오브젝트가 차지하는 메모리도 해제합니다.
void PQfinish(PGconn *conn);
비록 서버의 접속 시도가 실패해도(PQstatus에 의해 지시된), 어플리케이션은PQfinish를 호출해
PGconn오브젝트가 차지하는 메모리를 해제해야 합니다.
그리고PQfinish가 호출된 후에는 PGconn 포인터를 다시 사용해서는 안됩니다.
PQreset
서버로의 통신 채널을 재설정 합니다.
void PQreset(PGconn *conn);
이 함수는 서버로의 접속을 닫고, 이전에 사용한 파라미터를 모두 사용하고, 동일한 서버에 새로운 접속을 확립합니다. 이는 작업 중에 접속이 사라졌을 경우, 에러 복구에 도움이 될 것입니다.
PQresetStart
PQresetPoll
비블로킹 방식에서, 서버로의 접속 채널을 재설정 합니다
int PQresetStart(PGconn *conn);
PostgresPollingStatusType PQresetPoll(PGconn *conn);
이러한 함수는 서버로의 접속을 닫고 그리고 재차, 이전 사용한 파라미터를 모두 사용하고, 같은 서버와 새로운 접속을 확립하려고 합니다.
이것들은 작업 중 접속이 없어졌을 경우의 에러 복구에 도움이 될 것입니다.
PQreset(위의)와의 차이는 이 2개의 함수가 nonblock 방식에서 동작하는 것입니다.
또한, 이러한 함수는 PQconnectStart나 PQconnectPoll와 같은 제약을 받습니다.
접속 재설정을 시작하려면 , PQresetStart를 호출합니다.
이 함수가 0을 돌려주는 경우, 재설정에 실패한 것입니다.
반환 값이 1이라면, PQconnectPoll를 사용해 접속을 확립했던 것과 같이, PQresetPoll를 사용해 재설정 폴링을 실시합니다.