PEP 248 – Python 데이터베이스 API 명세 v1.0

Author:: Greg Stein <gstein at lyra.org>, Marc-André Lemburg <mal at lemburg.com>
Discussions-To:: Db-SIG list
Status:: Final
Type:: Informational
Created:: 08-May-1996
Post-History:
Superseded-By:: 249

Table of Contents

소개
모듈 인터페이스
연결 객체
커서 객체
DBI 헬퍼 객체
감사의 글
Copyright

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

소개

이 API는 데이터베이스에 접근하는 데 사용되는 Python 모듈 사이의 유사성을 높이기 위해 정의되었습니다. 이를 통해 더 이해하기 쉬운 모듈, 일반적으로 여러 데이터베이스 사이에서 이식성이 더 높은 코드, 그리고 Python에서 더 폭넓은 데이터베이스 연결을 가능하게 하는 일관성을 얻기를 기대합니다.

이 인터페이스 명세는 다음 몇 가지 항목으로 구성됩니다:

모듈 인터페이스
연결 객체
커서 객체
DBI 헬퍼 객체

이 명세에 대한 의견과 질문은 파이썬 표 형식 데이터베이스 SIG(http://www.python.org/sigs/db-sig)로 보내 주십시오.

이 명세 문서는 1996년 4월 9일에 마지막으로 갱신되었습니다. 이 문서는 이 명세의 버전 1.0으로 불리게 됩니다.

모듈 인터페이스

데이터베이스 인터페이스 모듈의 이름은 일반적으로 db로 끝나야 합니다. 기존 예로는 oracledb, informixdb, pg95db가 있습니다. 이러한 모듈은 다음 몇 가지 이름을 내보내야 합니다:

modulename(connection_string): 데이터베이스에 대한 연결을 만드는 생성자입니다. 연결 객체를 반환합니다.
error: 데이터베이스 모듈에서 발생한 오류에 대해 발생하는 예외입니다.

연결 객체

연결 객체는 다음 메서드에 응답해야 합니다:

close(): (__del__이 호출될 때가 아니라) 지금 즉시 연결을 닫습니다. 이 시점부터 연결은 사용할 수 없게 되며, 이 연결로 어떤 작업이든 시도하면 예외가 발생합니다.
commit(): 보류 중인 트랜잭션을 데이터베이스에 커밋합니다.
rollback(): 데이터베이스를 보류 중인 트랜잭션의 시작 시점으로 롤백합니다.
cursor(): 새 Cursor 객체를 반환합니다. 데이터베이스가 커서 개념을 지원하지 않으면 예외가 발생할 수 있습니다.
callproc([params]): (참고: 이 메서드는 아직 명확하게 정의되지 않았습니다.) 주어진 (선택적) 매개변수로 데이터베이스 저장 프로시저를 호출합니다. 저장 프로시저의 결과를 반환합니다.
(모든 Cursor 객체 속성과 메서드): 커서가 없는 데이터베이스나 커서의 복잡성이 필요하지 않은 단순한 애플리케이션을 위해, 연결 객체(Connection Object)는 커서 객체(Cursor Object)의 모든 속성과 메서드에 응답해야 합니다. 커서가 있는 데이터베이스는 암묵적인 내부 커서를 사용하여 이를 구현할 수 있습니다.

커서 객체

이 객체는 데이터베이스 커서를 나타내며, 데이터베이스 커서는 fetch 연산의 컨텍스트를 관리하는 데 사용됩니다.

Cursor 객체는 다음 메서드와 속성에 응답해야 합니다:

arraysize

이 읽기/쓰기 속성은 fetchmany()로 한 번에 가져올 행의 수를 지정합니다. 이 값은 여러 행을 한 번에 삽입할 때(튜플/리스트의 튜플/리스트를 execute()에 params 값으로 전달할 때)에도 사용됩니다. 이 속성의 기본값은 한 행입니다.

arraysize는 선택 사항이며 단지 더 높은 성능의 데이터베이스 상호 작용을 위해 제공된다는 점에 유의하십시오. 구현은 fetchmany() 메서드에 대해 이 값을 따라야 하지만, 데이터베이스와 한 번에 한 행씩 상호 작용해도 됩니다.

description

이 읽기 전용 속성은 7-튜플의 튜플입니다. 각 7-튜플에는 각 결과 열을 설명하는 정보가 담겨 있습니다: (name, type_code, display_size, internal_size, precision, scale, null_ok). 행을 반환하지 않는 연산이거나 커서에서 아직 execute() 메서드로 연산을 호출하지 않은 경우 이 속성은 None입니다.

‘type_code’는 아래 절에 명시된 ‘dbi’ 값 중 하나입니다.

참고: 이 부분은 아직 다소 유동적입니다. 일반적으로 7-튜플의 처음 두 항목은 항상 존재하며, 나머지는 데이터베이스마다 다를 수 있습니다.

close()

(__del__이 호출될 때가 아니라) 지금 즉시 커서를 닫습니다. 이 시점부터 커서는 사용할 수 없게 되며, 커서로 어떤 연산이든 시도하면 예외가 발생합니다.

execute(operation [,params])

데이터베이스 연산(쿼리 또는 명령)을 실행(준비)합니다. 매개변수는 (시퀀스(예: 튜플/리스트)로) 제공될 수 있으며 연산 안의 변수에 바인딩됩니다. 변수는 매개변수 튜플의 인덱스에 기반한(이름 기반이 아닌 위치 기반의) 데이터베이스별 표기법으로 지정합니다.

매개변수를 시퀀스의 시퀀스(예: 튜플의 리스트)로 지정하여 단일 연산으로 여러 행을 삽입할 수도 있습니다.

커서는 해당 연산에 대한 참조를 유지합니다. 같은 연산 객체가 다시 전달되면 커서는 동작을 최적화할 수 있습니다. 이는 같은 연산을 사용하되 (여러 번) 서로 다른 매개변수를 바인딩하는 알고리즘에서 가장 효과적입니다.

연산을 재사용할 때 효율을 극대화하려면 setinputsizes() 메서드를 사용하여 매개변수의 타입과 크기를 미리 지정하는 것이 가장 좋습니다. 매개변수가 미리 정의된 정보와 일치하지 않아도 허용됩니다. 구현은 이를 보완해야 하며, 이 경우 효율이 떨어질 수 있습니다.

SQL 용어로 표현하면 execute() 메서드가 반환할 수 있는 결과 값은 다음과 같습니다:

문이 DDL(예: CREATE TABLE)이면 1이 반환됩니다.
문이 DML(예: UPDATE 또는 INSERT)이면 영향을 받은 행의 수(0 또는 양의 정수)가 반환됩니다.
문이 DQL(예: SELECT)이면 None이 반환되며, 이는 ‘fetch’ 메서드 중 하나를 사용하기 전까지는 문이 실제로 완료되지 않았음을 나타냅니다.

fetchone()

쿼리 결과의 다음 행을 가져와 단일 튜플로 반환합니다.

fetchmany([size])

쿼리 결과의 다음 행 집합을 가져와 튜플의 리스트로 반환합니다. 더 이상 가져올 행이 없으면 빈 리스트가 반환됩니다. 가져올 행의 수는 매개변수로 지정합니다. 매개변수가 None이면 커서의 arraysize가 가져올 행의 수를 결정합니다.

size 매개변수와 관련하여 성능상 고려할 사항이 있다는 점에 유의하십시오. 최적의 성능을 얻으려면 보통 arraysize 속성을 사용하는 것이 가장 좋습니다. size 매개변수를 사용한다면 fetchmany() 호출마다 같은 값을 유지하는 것이 가장 좋습니다.

fetchall()

쿼리 결과의 모든 행을 가져와 튜플의 리스트로 반환합니다. 커서의 arraysize 속성이 이 연산의 성능에 영향을 줄 수 있다는 점에 유의하십시오.

setinputsizes(sizes)

(참고: 이 메서드는 아직 명확하게 정의되지 않았습니다.) 이 메서드는 execute() 호출 전에 사용하여 연산의 매개변수를 위한 메모리 영역을 미리 정의할 수 있습니다. sizes는 튜플로 지정하며, 입력 매개변수마다 항목이 하나씩 있습니다. 각 항목은 사용될 입력에 대응하는 Type 객체이거나, 문자열 매개변수의 최대 길이를 지정하는 정수여야 합니다. 항목이 None이면 해당 열에는 미리 정의된 메모리 영역이 예약되지 않습니다(이는 큰 입력에 대해 미리 정의된 영역을 피하는 데 유용합니다).

이 메서드는 execute() 메서드가 호출되기 전에 사용합니다.

이 메서드는 선택 사항이며 단지 더 높은 성능의 데이터베이스 상호작용을 위해 제공된다는 점에 유의하십시오. 구현은 아무 동작도 하지 않아도 되며, 사용자는 이 메서드를 사용하지 않아도 됩니다.

setoutputsize(size [,col])

(참고: 이 메서드는 아직 명확하게 정의되지 않았습니다.)

큰 열(예: LONG)을 가져올 때 사용할 열 버퍼 크기를 설정합니다. 열은 결과 튜플의 인덱스로 지정합니다. 열로 None을 사용하면 커서에 있는 모든 큰 열의 기본 크기가 설정됩니다.

이 메서드는 execute() 메서드를 호출하기 전에 사용합니다.

이 메서드는 선택 사항이며, 더 높은 성능의 데이터베이스 상호 작용을 위해 제공될 뿐이라는 점에 유의하십시오. 구현은 아무 동작도 하지 않아도 되며, 사용자는 이 메서드를 사용하지 않아도 됩니다.

DBI 헬퍼 객체

많은 데이터베이스는 연산의 입력 매개변수에 바인딩하려면 입력이 특정 형식으로 되어 있어야 합니다. 예를 들어, 입력이 DATE 열에 들어갈 것이라면 특정 문자열 형식으로 데이터베이스에 바인딩되어야 합니다. “Row ID” 열이나 큰 바이너리 항목(예: blob 또는 RAW 열)에도 비슷한 문제가 있습니다. execute() 메서드의 매개변수에는 타입이 없으므로 이는 Python에 문제가 됩니다. 데이터베이스 모듈은 Python 문자열 객체를 받았을 때 이를 단순한 CHAR 열로 바인딩해야 하는지, 원시 바이너리 항목으로 바인딩해야 하는지, 아니면 DATE로 바인딩해야 하는지 알 수 없습니다.

이 문제를 해결하기 위해 ‘dbi’ 모듈이 만들어졌습니다. 이 모듈은 데이터베이스 작업에 사용할 몇 가지 기본 데이터베이스 인터페이스 타입을 정의합니다. 클래스는 ‘dbiDate’와 ‘dbiRaw’ 두 가지입니다. 이들은 값을 감싸는 단순한 컨테이너 클래스입니다. 이 클래스의 인스턴스를 데이터베이스 모듈에 전달하면, 모듈은 해당 입력 매개변수가 DATE나 RAW로 의도된 것임을 알아낼 수 있습니다. 대칭성을 위해 데이터베이스 모듈은 DATE 열과 RAW 열을 이 클래스들의 인스턴스로 반환합니다.

커서 객체의 ‘description’ 속성은 쿼리의 각 결과 열에 대한 정보를 반환합니다. ‘type_code’는 이 모듈이 내보내는 다섯 가지 타입인 STRING, RAW, NUMBER, DATE, ROWID 중 하나로 정의됩니다.

이 모듈은 다음 이름들을 내보냅니다:

dbiDate(value): 이 함수는 날짜 값을 담는 ‘dbiDate’ 인스턴스를 생성합니다. 값은 “에포크” 이후 경과한 초 수를 나타내는 정수로 지정해야 합니다(예: time.time()).
dbiRaw(value): 이 함수는 원시(바이너리) 값을 담는 ‘dbiRaw’ 인스턴스를 생성합니다. 값은 Python 문자열로 지정해야 합니다.
STRING: 이 객체는 데이터베이스에서 문자열 기반인 열(예: CHAR)을 설명하는 데 사용됩니다.
RAW: 이 객체는 데이터베이스의 (큰) 바이너리 열(예: LONG RAW, blob)을 설명하는 데 사용됩니다.
NUMBER: 이 객체는 데이터베이스의 숫자 열을 설명하는 데 사용됩니다.
DATE: 이 객체는 데이터베이스의 날짜 열을 설명하는 데 사용됩니다.
ROWID: 이 객체는 데이터베이스의 “Row ID” 열을 설명하는 데 사용됩니다.

감사의 글

2001년에 Python 데이터베이스 API 명세 1.0을 원래의 HTML 형식에서 PEP 형식으로 변환해 준 Andrew Kuchling에게 깊은 감사를 드립니다.

Greg Stein은 Python 데이터베이스 API 명세 1.0의 최초 작성자입니다. 이후 Marc-André가 편집자로서 이 API의 유지 관리를 이어 갔습니다.

Copyright

This document has been placed in the Public Domain.