Python DB-API の使用法
InterSystems Python DB-API ドライバは、PEP 249 バージョン 2.0Opens in a new tab Python Database API の仕様に完全に準拠した実装です。以下のセクションでは、必要なすべての実装機能をリストして、それぞれのサポート・レベルを示し、インターシステムズ固有の機能すべてについて詳細に説明します。
-
InterSystems IRIS への接続方法、および Cursor オブジェクトの取得方法について説明します。
-
以下に、PEP 249 のすべての要件と実装の詳細を示します。
-
"グローバル" では、必要なグローバル定数 apilevel、threadsafety、および paramstyle の値を示します。
-
"Connection オブジェクト" では、Connection メソッド connect()、close()、commit()、rollback()、および cursor() について説明します。
-
"Cursor オブジェクト" では、次の Cursor メンバについて説明します。
-
属性 arraysize、description、および rowcount。
-
標準メソッド callproc()、close()、execute()、executemany()、fetchone()、fetchmany()、fetchall()、nextset()、scroll()、setinputsizes()、および setoutputsize()。
-
インターシステムズの拡張メソッド isClosed() および stored_results()。
-
-
-
有効な SQLType 列挙定数。
DB-API は、InterSystems IRIS をインストールすると使用できるようになります。InterSystems DB-API ドライバがない場合 (InterSystems IRIS がインストールされていないホストから接続されている場合など)、InterSystems IRIS ドライバのページOpens in a new tabからこれをダウンロードし、以下を使用してインストールできます。
pip install intersystems_irispython-3.2.0-py3-none-any.whl
使用法
次の例では、InterSystems IRIS データベースに接続し、その接続に関連付けられたカーソルを作成して、DB-API 呼び出しを設定し、シャットダウンします。
使用可能なすべての DBAPI メソッドに関する詳細なドキュメントは、次のセクションの “Connection オブジェクト” および “Cursor オブジェクト” を参照してください。
import iris
def main():
connection_string = "localhost:1972/USER"
username = "_system"
password = "SYS"
connection = iris.connect(connection_string, username, password)
cursor = connection.cursor()
try:
pass # do something with DB-API calls
except Exception as ex:
print(ex)
finally:
if cursor:
cursor.close()
if connection:
connection.close()
if __name__ == "__main__":
main()
この例で呼び出されるメソッドの詳細は、"iris.connect()"、"Connection.close()"、"Connection.cursor()"、および "Cursor.close()" を参照してください。
"Connecting Your Application to InterSystems IRISOpens in a new tab" にも、サンプル・コードを含め、DB-API を使用して Python アプリケーションから InterSystems IRIS サーバに接続する手順が示されています。
PEP 249 実装リファレンス
このセクションでは、PEP 249 バージョン 2.0Opens in a new tab Python Database API の仕様で説明されているすべての必須実装機能をリストして、それぞれのサポート・レベルを示し、インターシステムズ固有の機能すべてについて詳細に説明します。
グローバル
これらは、必須の実装固有定数です。インターシステムズの実装では、これらのグローバルは次の値に設定されます。
"2.0" — PEP 249 バージョン 2.0 に準拠することを指定します。
0 — スレッドはモジュールを共有できません。
"qmark" — クエリ・パラメータは疑問符のスタイルを使用します (例: WHERE name=?)。
Connection オブジェクト
このセクションでは、iris.connect() を使用して Connection オブジェクトを作成する方法を説明し、必須 Connection メソッド close()、commit()、rollback()、および cursor() の実装の詳細を示します。
Connection オブジェクトの生成
DB-API Connection オブジェクトは、InterSystems iris.connect() メソッドを呼び出すことにより作成されます。
iris.connect() は、新しい Connection オブジェクトを返し、InterSystems IRIS のインスタンスへの新規接続の作成を試みます。接続が成功するとオブジェクトは開かれ、それ以外の場合は閉じられます (Cursor.isClosed() を参照)。
iris.connect(hostname,port,namespace,username,password,timeout,sharedmemory,logfile)
iris.connect(connectionstr,username,password,timeout,sharedmemory,logfile)
最後に成功した接続試行の hostname、port、namespace、timeout、および logfile が Connection オブジェクトのプロパティとして保存されます。
パラメータ:
パラメータは位置またはキーワードによって渡すことができます。
-
hostname — サーバ URL を指定する str
-
port — スーパーサーバ・ポート番号を指定する int
-
namespace — ネームスペース・サーバを指定する str
-
以下のパラメータを、hostname、port、および namespace の引数の代わりに使用できます。
-
connectionstr — hostname:port/namespace の形式の str
-
-
username — ユーザ名を指定する str
-
password — パスワードを指定する str
-
timeout (オプション) — 接続試行時に待機する最大秒数を指定する int既定値は 10 です。
-
sharedmemory (オプション) — bool を True に指定すると、ホスト名が localhost または 127.0.0.1 の場合に共有メモリ接続を試行します。False に指定すると、TCP/IP 経由の接続を強制します。既定値は True です。
-
logfile (オプション) — クライアント側のログ・ファイル・パスを指定する strパスの最大長は、255 文字の ASCII 文字です。
Connection オブジェクト・メソッド
Connection オブジェクトは、1 つ以上の Cursor オブジェクトの作成に使用できます。1 つのカーソルにより行われたデータベースの変更は、同じ接続から作成されたその他すべてのカーソルに即座に表示されます。ロールバックとコミットは、この接続を使用するカーソルによって行われたすべての変更に影響を与えます。
Connection.close() は、即座に接続を閉じます。接続とその接続に関連付けられたすべてのカーソルは使用できなくなります。関連付けられたカーソルによるコミットされていないすべての変更に対して、暗黙的なロールバックが実行されます。
Connection.close()
閉じられた接続で、または関連するカーソルで何らかの操作が試みられると、ProgrammingError 例外が発生します。
Connection.commit() は、前回のコミット以降にこの接続で実行されたすべての SQL 文をコミットします。ロールバックは、この接続を使用する任意のカーソルによって行われたすべての変更に影響を与えます。このメソッドへの明示的な呼び出しは必要ありません。
Connection.commit()
Connection.rollback() は、(前回のコミットまたはロールバック以降に) このカーソルを作成した接続で実行されたすべての SQL 文をロールバックします。ロールバックは、この接続を使用する任意のカーソルによって行われたすべての変更に影響を与えます。
Connection.rollback()
Connection.cursor() は、この接続を使用する、新しい Cursor オブジェクトを返します。
Connection.cursor()
1 つのカーソルにより行われたデータベースへの任意の変更は、同じ接続から作成されたその他すべてのカーソルに即座に表示されます。ロールバックとコミットは、この接続を使用する任意のカーソルによって行われたすべての変更に影響を与えます。
Cursor オブジェクト
このセクションでは、Cursor オブジェクトの作成方法について説明し、以下の必須 Cursor メソッドおよび属性の実装の詳細を示します。
-
属性 arraysize、description、および rowcount。
-
標準メソッド callproc()、close()、execute()、executemany()、fetchone()、fetchmany()、fetchall()、nextset()、scroll()、setinputsizes()、および setoutputsize()。
-
インターシステムズの拡張メソッド isClosed() および stored_results()。
Cursor オブジェクトの作成
Cursor オブジェクトは、接続を確立した後に Connection.cursor() を呼び出すことにより作成されます。例:
connection = iris.connect(connection_string, username, password)
cursor = connection.cursor()
1 つのカーソルにより行われたデータベースへの任意の変更は、同じ接続から作成されたその他すべてのカーソルに即座に表示されます。
完全な例は、“DB-API ドライバへの接続とカーソルの取得” を参照してください。接続の作成の詳細は、“Connection オブジェクトの生成” を参照してください。
Cursor の属性
Cursor.arraysize は、fetchmany() により一度にフェッチする行数を指定する読み取り/書き込み属性です。既定値は 1 (一度に 1 行をフェッチする) です。
Cursor.description は、前回の SQL select 文で返された各結果の列の情報を含むタプルのリストを返します。実行メソッドが呼び出されなかった場合、または前回の操作で行が返されなかった場合、値は None になります。
リスト内の各タプル (列の説明) には、以下の項目が含まれます。
-
name — 列名 (既定値は None)
-
type_code — 整数の SQLType 識別子 (既定値は 0)。有効な値は、“SQLType 列挙値” を参照してください。
-
display_size — 未使用 - 値は None に設定されます。
-
internal_size — 未使用 - 値は None に設定されます。
-
precision — 整数 (既定値は 0)
-
scale — 整数 (既定値は None)
-
nullable — 整数 (既定値は 0)
Cursor.rowcount は、前回の SQL 文で変更された行数を指定します。SQL が実行されていない、または行数が不明である場合、値は -1 となります。例えば、CREATE、DROP、DELETE、SELECT 文などの DDL は (パフォーマンス上の理由で) -1 を返します。
バッチ更新でも影響を受ける行数が返されます。
Cursor メソッド
Cursor.callproc() は、指定された procname のストアド・データベース・プロシージャを呼び出します。
Cursor.callproc(procname)
Cursor.callproc(procname, parameters)
パラメータ:
-
procname – パラメータ化された引数を使用したストアド・プロシージャ呼び出しを含む文字列。
-
parameters – ストアド・プロシージャに渡すパラメータ値の list
例:
このコードは、list にパラメータ値 "A" を指定して、ストアド・プロシージャ Sample.SP_Sample_By_Name を呼び出します。
cursor.callproc("CALL Sample.SP_Sample_By_Name (?)", ["A"])
row = cursor.fetchone()
while row:
print(row.ID, row.Name, row.DOB, row.SSN)
row = cursor.fetchone()
出力は以下のようになります。
167 Adams,Patricia J. 1964-10-12 216-28-1384
28 Ahmed,Dave H. 1954-01-12 711-67-4091
20 Alton,Samantha E. 2015-03-28 877-53-4204
118 Anderson,Elvis V. 1994-05-29 916-13-245
Cursor.close() は、カーソルをクローズします。
Cursor.close()
閉じられたカーソルで何らかの操作が試みられると、ProgrammingError 例外が発生します。カーソルは削除される (一般的には範囲外になる) と自動的に閉じられるため、これを呼び出すことは通常必要ありません。
Cursor.execute() は、operation パラメータで指定されたクエリを実行します。Cursor オブジェクトを更新し、rowcount 属性を、クエリの場合は -1 に、更新の場合は 1 に設定します。
Cursor.execute(operation)
Cursor.execute(operation, parameters)
パラメータ:
-
operation – 実行する SQL 文を含む string
-
parameters – オプションの値の list。これは Python list である必要があります (タプルまたはセットは受け入れられません)。
例:
パラメータ値は、SQL 文にリテラルや定数ではなく ? (疑問符) が含まれている位置で使用されます。文に疑問符が含まれていない場合、parameters 引数は必要ありません。指定された場合は例外が発生します。
-
sql = "...(1,2)..."; execute(sql)
-
sql = "...(?,?)..."; params = [1,2]; execute(sql, params)
-
sql = "...(1,?)..."; params = [2]; execute(sql, params)
Cursor.executemany() は、バッチの挿入または更新に使用されます。これは、データベース操作 (クエリまたはコマンド) を準備し、すべてのパラメータ・シーケンス、またはシーケンス seq_of_parameters 内にあるマッピングに対してこれを実行します。
Cursor.executemany(operation)
Cursor.executemany(operation, seq_of_parameters)
パラメータ:
-
operation – 実行する SQL 文を含む文字列
-
seq_of_parameters – パラメータ・シーケンスまたはマッピングのシーケンス
Cursor.fetchone() は、クエリ内の次の ResultSetRow.DataRow オブジェクト (データ・オフセットの整数の配列)、またはこれ以上データがない場合 None を返します。
Cursor.fetchone()
データは要求に応じてのみ、インデックス化によってフェッチされます。オブジェクトには、行の値を取得するために使用できる整数のオフセットのリストが含まれます。インデックスの値は正の整数である必要があります (1 という値は列 1 を示し、以下同様です)。
SQL が実行されていない、または結果セットが返されていない場合 (SELECT 文ではなかった場合など)、ProgrammingError 例外が発生します。
Cursor.fetchall() は、クエリ結果の残りの行すべてをフェッチします。
Cursor.fetchall()
Cursor.isClosed() は Cursor オブジェクトが既に閉じられている場合に True、それ以外の場合に False を返す、インターシステムズの拡張メソッドです。
Cursor.isClosed()
Cursor.nextset() は、複数の結果セットで反復するためのオプションの DB-API メソッドです。次の結果セットがあれば、そのセットにスキップします。結果セットがある場合は True、ない場合は False を返します (したがって、結果セットや結果セット行にアクセスするためには使用しないでください)。
Cursor.nextset()
例:
for row in cursor.stored_results():
row_values = row[0] // data in all columns
val1 = row[1] // data in column 1
cursor.nextset() // skips to the next result set if multiple result sets
// does nothing (or breaks out of loop) in case of single result set;
Cursor.scroll() は、結果セット内でカーソルを新しい位置までスクロールして、その位置の行を返す、オプションの DB-API メソッドです。
Cursor.scroll(value)
Cursor.scroll(value, mode)
スクロール操作で結果セットを残したままにすると、IndexError が発生します。
パラメータ:
-
value – 新しいターゲット位置を指定する整数値。
-
mode が relative (既定値) の場合、value は、結果セット内の現在の位置に対する正または負のオフセットです。
-
mode が absolute の場合、value は、ターゲットの絶対位置です (負の値は無効です)。
-
-
mode – オプション。有効な値は、relative または absolute です。
例:
例えば結果セットが全部で 10 行あり、フェッチされる行数の初期値が 5 だとします。結果セットのインデックス値は 0 から始まるため、現在の位置は rs[4] (5 行目) となります。
# Scroll forward 3 rows relative to rs[4] (mode defaults to 'relative')
datarow = Cursor.scroll(3) // returns rs[7] (8th row in resultset)
# Scroll to absolute position 3
datarow = Cursor.scroll(3,'absolute') // returns rs[2] (3rd row in resultset)
# Scroll backward 4 rows relative to rs[4] (mode defaults to 'relative')
datarow = Cursor.scroll(-4) // returns rs[0]
# Scroll to absolute position -4
datarow = Cursor.scroll(-4,'absolute') // Throws IndexError (negative row number not valid)
Cursor.setinputsizes() は InterSystems IRIS には適用できません。ここではこの機能は実装されず、必要とされません。呼び出された場合、NotImplementedError をスローします。
Cursor.setoutputsize() は InterSystems IRIS には適用できません。ここではこの機能は実装されず、必要とされません。呼び出された場合、NotImplementedError をスローします。
Cursor.stored_results() は、プロシージャ・タイプが 'query' の場合はリスト反復子 (各結果セットの最初の行を含む) を返し、プロシージャ・タイプが 'function' の場合は空のリストを返す、インターシステムズの拡張メソッドです。
Cursor.stored_results()
例:
for row in cursor.stored_results(): // row is DataRow object for 1st row of result set
row_values = row[0] // data in all columns
val1 = row[1] // data in column 1
Incorrect Syntax:
row = cursor.stored_results() // row values not accessible using row[0] since it is a list iterator
SQLType 列挙値
Cursor.description 属性の有効な値。
-
BIGINT = -5
-
BINARY = -2
-
BIT = -7
-
CHAR = 1
-
DECIMAL = 3
-
DOUBLE = 8
-
FLOAT = 6
-
GUID = -11
-
INTEGER = 4
-
LONGVARBINARY = -4
-
LONGVARCHAR = -1
-
NUMERIC = 2
-
REAL = 7
-
SMALLINT = 5
-
DATE = 9
-
TIME = 10
-
TIMESTAMP = 11
-
TINYINT = -6
-
TYPE_DATE = 91
-
TYPE_TIME = 92
-
TYPE_TIMESTAMP = 93
-
VARBINARY = -3
-
VARCHAR = 12
-
WCHAR = -8
-
WLONGVARCHAR = -10
-
WVARCHAR = -9
-
DATE_HOROLOG = 1091
-
TIME_HOROLOG = 1092
-
TIMESTAMP_POSIX = 1093