Python DB-API の使用法

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既定値は 10000 です。

• sharedmemory (オプション) — bool を True に指定すると、ホスト名が localhost または 127.0.0.1 の場合に共有メモリ接続を試行します。False に指定すると、TCP/IP 経由の接続を強制します。既定値は True です。

• logfile (オプション) — クライアント側のログ・ファイル・パスを指定する strパスの最大長は、255 文字の ASCII 文字です。

Connection.close() は、即座に接続を閉じます。接続とその接続に関連付けられたすべてのカーソルは使用できなくなります。関連付けられたカーソルによるコミットされていないすべての変更に対して、暗黙的なロールバックが実行されます。

   Connection.close()

閉じられた接続で、または関連するカーソルで何らかの操作が試みられると、ProgrammingError 例外が発生します。

Connection.commit() は、前回のコミット以降にこの接続で実行されたすべての SQL 文をコミットします。ロールバックは、この接続を使用する任意のカーソルによって行われたすべての変更に影響を与えます。このメソッドへの明示的な呼び出しは必要ありません。

   Connection.commit()

Connection.rollback() は、(前回のコミットまたはロールバック以降に) このカーソルを作成した接続で実行されたすべての SQL 文をロールバックします。ロールバックは、この接続を使用する任意のカーソルによって行われたすべての変更に影響を与えます。

   Connection.rollback()

Connection.cursor() は、この接続を使用する、新しい Cursor オブジェクトを返します。

   Connection.cursor()

1 つのカーソルにより行われたデータベースへの任意の変更は、同じ接続から作成されたその他すべてのカーソルに即座に表示されます。ロールバックとコミットは、この接続を使用する任意のカーソルによって行われたすべての変更に影響を与えます。

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.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.fetchmany() は、クエリの次の行の結果セットをフェッチし、シーケンスのシーケンス (タプルのリスト) を返します。size 引数が指定されていない場合、一度にフェッチする行数は、Cursor.arraysize 属性で設定されます (既定値は 1)。これ以上使用できる行がない場合は空のシーケンスが返されます。

   Cursor.fetchmany()
   Cursor.fetchmany(size)

パラメータ：

• size – オプション。既定値は、属性 Cursor.arraysize の現在の値です。

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