[Home] [ダウンロード] [インストール] [使用方法] [使用例] [FAQ]

pgbash の使用方法

 pgbashは、SQL;をシェルコマンドとして実行することができます。exec_sqlコマンドを使用して、各種のオプション付きでSQLを実行することもできます。以下の説明では、pgbashは"/usr/local/bin"ディレクトリにあるものとします。
◎ pgbashの起動と終了方法
  1. サブシェルとして使用する場合

     サブシェルとは、既に使用しているシェルの上で起動されたシェルのことをいいます。bashシェルを使用してログインした後に、/usr/local/bin/pgbash と入力すると、pgbashがサブシェルとして起動します。pgbashの起動時は、~/.bashrc と ~/.pgbashrc が読みこまれ次の Welcomeメッセージが表示されます。
      prompt> /usr/local/bin/pgbash
      Welcome to the PGBASH version 2.X (bash-2.0X)
    
        Type '[time] SQL; [pipeline][redirection][&]' to execute SQL.
        Type 'exec_sql [option] ["SQL"]' to execute SQL with options.
        Type '?' for HELP. (This help is defined with ~/.pgbashrc)
    
      pgbash> exit
    
     exit を入力しますと、サブシェル(pgbash)を終了し元のログインシェルに戻ります。

    尚、 pgbashを使用中に ~/.bashrc や ~/.pgbashrc を変更した場合は、source コマンドを使用して環境を更新します。例えば、 source ~/.pgbashrc とします。

  2. シェルスクリプトで使用する場合

    シェルスクリプトでは、シェルスクリプトの先頭に #!/usr/local/bin/pgbash を記述します。
    #!/usr/local/bin/pgbash
    source ~/.pgbashrc
    #
    connect to db2@dbserc.xxx.co.jp as db2 user postgres;
    m

    ~/.pgbashrc に設定された環境を利用したい場合は、sourceコマンドを実行する必要があります。上例の"m"は~/.pgbashrc に定義されたデータベース接続一覧表の出力コマンドです。


◎ SQL文の指定方法
     対話型環境およびシェルスクリプトのいずれも、SQL;(終端子はセミコロン)と入力するだけでSQLを実行することができます。 SQL; は、time、パイプ、リダイレクション、バックグランドジョブ指定で実行することが可能です。SQLの指定方法は次です。

    [timespec] SQL; [pipeline][redirection][&]

     SQL文は単語の切れ目で自由に改行することができます。改行すると > プロンプトが表示されますので続けてSQL文を入力します。セミコロンが現れた時点でSQLの終了とみなします。

    例)
    pgbash> select * from test;
    pgbash> time select * from test; | more > /tmp/sel.dat &
    pgbash> insert into test values(111,
    > 'aaa','bbb');

    SQL; の形式はif文、while文の後ろに記述することはできません。SQLの実行状態を知りたい場合は、$SQLCODE を利用します。
    例) 
    select * from test;
    if [ $SQLCODE -eq $SQL_OK ]; then
       ...
    fi
    
     SQL; のなかで、シェル変数を利用することができます。 但し、fetch into文のinto句のホスト変数部分は、':'とシェル変数名にします。

    例)
    insert into test values($_AA, '$_BB', '$_CC');
    fetch in cur into :_AA, :_BB, :_CC;

◎ exec_sql の実行方法とオプション
     各種オプションを付けてSQLを実行したい場合は、exec_sqlコマンドを使用します。書式は次です。

    exec_sql [option] ["SQL"]

  1. SQL文の指定方法

     SQL文は" "の中に記述します。SQL文の最後に';'はあっても無くてもかまいません。SQL文は、単語の切れ目で自由に改行することができます。
      例) exec_sql "select aa,bb,cc from test_table
                              where a>'123' and dd<'999'"            
    
  2. exec_sqlコマンドのオプション
        -i        set CGI mode and set DATA received from WWW server
        -h item   help item: select,insert,.. or next command:
                 (HElp,ALl,OPtion,ERrno,EXample) <2 char are judged>
        -v        display VERSION of pgbash(exec_sql)
        -s        display SQLCA(SQLCODE,etc..) (after SQL execution)
    
        -d conn   set current CONNect_name defined in CONNECT_SQL
        -e        turn on  printing of QUERY sent to the backend
        -q        turn off printing of SYSTEM/SQL error messages
    
        -P        turn on PLAIN output(-P is default in normal mode)
        -H        turn on HTML  output(-H is default in CGI    mode)
        -X        set EXPANDED  type  (ex. -PX or -HX)
        -C cap    set CAPTION of HTML/PLAIN table (ex. -C 'TITLE')
        -O opt    set OPTION  of HTML table (ex. -O 'BORDER=0')
        -L        turn on  OUTER_FRAME of PLAIN table
        -T        turn off HEADINGS    of PLAIN/HTML table
        -B        turn off ROW_COUNT   of PLAIN/HTML table
        -A        turn off ALIGNMENT   of PLAIN table (ex. -PXA)
        -S sep    set SEPARATOR of PLAIN table field(default is '|')
        -N null   set NULL value string (ex. -N 'NULL')
        -Z zero   set ZERO value string (ex. -Z '-0-' )
        
        -m        list all connected databases
        -l obj    list databases objects:       <2 char are judged>
                  (DAtabases, TAbles,    INdices, SEquences, GRant)
                  (FUnctions, OPerators, TYpes,   SYstem_tables   )
        -p tbl    list tables objects (tbl: table_name      or '*')
        -r des    list description:             <2 char are judged>
                  (TAble, FIeld, TYpe, FUnction, OPerator   or '*')
    

◎ ヘルプおよびデータベース表示情報について
     exec_sql コマンドは次のヘルプ機能があります。'HELP','ALL'などのヘルプオプションは、先頭の2文字だけが判断され大文字小文字の区別もありません。
        
      exec_sql -h select         --- SELECT文のヘルプ
      exec_sql -h 'create table' --- CRAETE TABLE文のヘルプ
      exec_sql -h HELP           --- SELECT,CREATEなどの一覧表示
      exec_sql -h ALL            --- SELECT,CREATEなどの全詳細
      exec_sql -h OPTION         --- オプションだけの一覧
      exec_sql -h ERRNO          --- SQLエラーコード一覧表示
      exec_sql -h EXAMPLE        --- 使用例
    
    また、exec_sqlコマンドは次のデータベース情報の表示機能があります。 exec_sql -l databases -l tables -l index -p test1 のように連続して指定することが可能です。尚、'database','table'などデータベース情報の種類を表す言葉は、先頭2文字だけが判断され大文字小文字の区別もありません。
        exec_sql -l da    --- データベース名一覧表示
        exec_sql -l ta    --- テーブル名とビユー名一覧表示
        exec_sql -l in    --- インデックス名一覧表示
        exec_sql -l se    --- シークエンステーブル名一覧表示
        exec_sql -l gr    --- 権限一覧表示
        exec_sql -l fu    --- FUNCTION名一覧表示
        exec_sql -l op    --- オペレータ一覧表示
        exec_sql -l ty    --- データ型一覧表示
        exec_sql -l sy    --- システムテーブル一覧
        exec_sql -p table名 - テーブルの列名、データ型などの表示
        exec_sql -p '*'   --- 全テーブルの列名、データ型などの表示
    
    exec_sqlコマンドのヘルプ機能やデータベース情報表示機能を利用して、~/.pgbashrc では次の短縮形のコマンドを用意してます。プロンプトが表示されているときに ? を入力するとそれらの短縮形のコマンド一覧を表示できます。各短縮形コマンドの設定内容は ~/pgbashrc を参照してください。
      h  [SQL]: help <SQL> syntax or all SQL_commands
      o       : help OPTIONs of 'exec_sql' function
      v       : print PGBASH VERSION
      s       : print STATUS after SQL execution
      u       : list all USERs
      l       : list all DATABASEs
      m       : list all CONNECTIONs
      d  [TBL]: list tables,indices,columns in <TaBLe>, or all tables
      dt      : list only TABLEs
      di      : list only INDEXes
      ds      : list only SEQUENCEs
      dg      : list GRANT/REVOKE permissions
      dA      : list AGGREGATEs
      dD [obj]: list DESCRIPTIONs for <TAble,FIeld,TYp,FU,OP>, or all
      dF      : list PosgreSQL FUNCTIONs
      dO      : list OPERATORs
      dS      : list SYSTEM tables and indexes
      dT      : list TYPEs
    

◎ データベースの接続
     pgbashは、CONNECT, DISCONNECT, SET CONNECTION の3つのSQLを独自に実装してます。CONNECTは、接続名(connect_name)を指定してデータベースに接続します。SET CONNECTIONは、カレントのデータベース接続名を指定します。SET CONNECTIONが無い場合は、最後のCONNECTがカレントの接続名になります。そして最後に DISCONNECT によってデータベースの接続を切断します。それぞれの文法は次です。
      ・CONNECT TO dbname[@server[:port]] | DEFAULT  
                         [AS connect_name] [USER user_name [password]];
      ・DISCONNECT connect_name|CURRENT|DEFAULT|ALL;
      ・SET CONNECTION connect_name|DEFAULT;
    
      例) connect to postgres1 as db1 user postgres xxxxxxxx;
          connect to postgres2 as db2 ;   ....ログインのユーザ名が使用される
          set connection db1;
          select * from test1;
          set connection db2;
          select * from test2;
          disconenct all;
    
    もし、CONNECTを実行せずに SELECTなどのSQLを実行した場合は、自動的に"CONNECT TO DEFAULT"が発行されます。これは、psqlをデータベース名を指定せずに実行した場合と同等です。

    connect文で user を指定して password を指定しない場合は、password: プロンプトが表示されパスワード入力待ち状態になります。パスワードを設定していないユーザは、"CONNECT TO データベース名 USER ユーザ名 NULL"のようにパスワードにNULLを指定してください。ログインユーザ名と同じ名前のユーザ名の場合は、"user"以降を記述する必要はありません。

    disconnect all; で全ての接続を切断することができます。また、ログアウトしたりサブシェルを終了すると自動的に全て切断されます。シェルスクリプトは、シェルスクリプトが終了すると自動的に全て切断されます。
◎ データベースの接続状態表示
    exec_sql -m を指定すると、データベースの接続状態を示します。外枠を付ける場合は -L オプションをつけます。対話型環境では、m と入力するだけで exec_sql -mL が実行されます。例えば次のように3つの接続を行い exec_sql -mL としますと以下のように表示されます。
        connect to default;
        connect to postgres@www2.psn.ne.jp:5432  as db1;
        connect to admin@xxx.psn.ne.jp as db2 user admin;
        exec_sql -mL (対話型環境では m )
        # Connected Databases List (C: current database is '*')
        +---+--------------+-----------+------------------------------+
        | C | connect_name | user_name | target_name                  |
        +---+--------------+-----------+------------------------------+
        |   | _DEFAULT_    | postgres  | postgres:5432                |
        |   | db1          | postgres  | postgres@www.psn.ne.jp:5432  |
        | * | db2          | admin     | admin@xxx.psn.ne.jp:5432     |
        +---+--------------+-----------+------------------------------+
        (3 rows)
    
◎ 複数データベースのデータ操作
    複数のデータベースを取り扱う場合は、set connection文もしくは exec_sql -d オプションでデータベース接続名を指定してSQLを実行します。例えば次のように使用します。
      例) connect to postgres1 as db1;
          connect to postgres2 as db2;
          connect to postgres1 as db3;
          set connection db1;    <-------------- db1をカレントに指定
          exec_sql -d db2 "select * from test2" <-- db2の接続
          exec_sql        "select * from test1" <-- db1の接続
          exec_sql -d db3 "select * from test2" <-- db3の接続
          select * from test;                   <-- db1の接続
    
     set connection文は、カレントの接続名を変更します。以後のSQLは、exec_sql -d で変更しない限りカレントの接続名に対してSQLを実行します。それに対して、exec_sql の -d は、一時的に接続名を変えるだけでカレントの接続名は変更されません。

     CONNECT文は、同じデータベースに対して違う接続名で接続することができます。これを使用すると、1データベースに複数ユーザが接続しているテスト環境を容易に作成することができます。
◎ 検索結果のシェル変数への代入
     pgbashは、FETCH INTO文を使用して、検索結果をシェル変数に代入することができます。FETCH INTO文の文法は次です。
      FETCH [FORWARD|BACKWARD] [number|ALL] [IN cursorname]
            [INTO :host_var1 [[INDICATOR] :ind_var1], ...
                  :host_varN [[INDICATOR] :ind_varN]];
    
    INTO句を使用する場合は、number,ALLは不用です。但し、number, ALLを指定しても検索結果が1タプルの場合は、INTO句が有効となりシェル変数に代入されます。検索結果が複数タプルになった場合は、シェル変数には代入されずに標準出力に出力されます。

    (例)
    begin; 
    declare cur cursor for select * from test;
    declares -i x ; let x=0;  while ((x < 10))  
    do
       fetch in cur into :CODE indicator :IND_C,
                         :NAME:IND_N, :ADDRESS :IND_A;
        if (( SQLCODE == SQL_OK )); then
            if ((IND_N != SQL_NULL || IND_A != SQL_NULL)); then
                echo "$CODE, $NAME, $ADDRESS"
                let x=x+1
            fi
        else
            if(( SQLCODE == SQL_NOT_FOUND )); then
                    let x=11
            else
                    echo "$SQLERRMC"
                    let x=x+1
            fi
        fi
    done
    end;
    

    ここで、SQLCODEは SQLエラーコードを、$SQLERRMCは SQLエラーメッセージを表すシェル変数です。また、SQL_NULL, SQL_NOT_FOUNDは pgbashが初期設定している値です。(エラーコードを参照)

    # (( ))演算式のなかでは、整数型シェル変数の先頭'$'は省略することができます。


◎ 出力書式について
  1. 標準の出力モード

     select の検索結果およびデータベース情報の表示のいづれも同じ書式で出力することができます。通常は平文モード(-Pオプション)が標準状態ですが、exec_sql -i を実行すると CGIモード(-H オプション)になりHTML出力<TABLE BORDER=1>が標準状態になります。

  2. タイトルの出力

    平文およびHTMLのいずれの出力に対しても、-C オプションでタイトルを指定(または既存のタイトルの置換)することができます。

  3. 平文出力時の外枠罫線の出力

    従来のバージョンでは、select の検索結果は外枠無し、データベース情報の表示は外枠有りで固定されていましたが、pgbash-1.1.0 からは、初期状態では外枠無し、-L オプションを付けると外枠罫線を表示するようになりました。
    $ exec_sql -L "select * from test"
    +------+------------+----------+
    | code | name       | address  |
    +------+------------+----------+
    | 111  | sakaida    | kobe     |
    | 222  | haruhiko   | hirosima |
    | 333  | nobu       |          |
    |      | youko      | oosaka   |
    +------+------------+----------+
    (4 rows)
    
  4. テーブルのヘッダーと行数の表示の停止

    -T, -B オプションによってテーブルのヘッダーと行数の表示を停止することができます。
    $ exec_sql -L -TB "select * from test"
    +------+------------+----------+
    | 111  | sakaida    | kobe     |
    | 222  | haruhiko   | hirosima |
    | 333  | nobu       |          |
    |      | youko      | oosaka   |
    +------+------------+----------+
    
  5. NULL値、ゼロ値の表示

    NULL値、ゼロ値('')を -N, -Z オプションで文字列として表示することができます。
    $ exec_sql -LTB -N 'NULL' -Z '-0-' "select * from test"
    +------+------------+----------+
    | 111  | sakaida    | kobe     |
    | 222  | haruhiko   | hirosima |
    | 333  | nobu       | -0-      |
    | NULL | youko      | oosaka   |
    +------+------------+----------+
    
◎ COPY命令について
    PostgreSQLの標準機能では、postgresスーパユーザだけがCOPY文においてファイル名を指定することができます。この場合、バックエンドが実際のファイル入出力処理を行います。 これに対して、pgbashは独自のCOPY機能を実装し、一般ユーザであってもファイル名を指定してファイルのコピーを行うことができます。また、列名を指定してコピーすることもできます。COPY文の文法を次に示します。

    COPY table ( [col1[,col2..]] ) {FROM | TO}
    {filename | STDIN | STDOUT}
    [ USING DELIMITERS 'delimiter' ] [ WITH NULL AS 'nullstring' ];

    pgbash独自実装のCOPY文は、テーブル名の後ろに()を付けます。()の中に列名を指定しない場合は、全列のコピーになります。尚、テーブル名の後ろに()が無い場合は、PostgreSQL標準のCOPY文として実行されます。

    (1) データベースへの書きこみ

    copy tbname(col1,col2) from /tmp/oo; のように指定された場合、pgbash内部では次のように変換されて実行されます
      begin;
      insert into tbname(col1,col2) values(読み込まれたデータ1)
      insert into tbname(col1,col2) values(読み込まれたデータ2)
      ...
      end;
    
    書きこみの途中でエラーを起こすと rollback されます。

    (2) データベースからの読み込み

    copy tbname(col1,col2) to /tmp/oo; のように指定された場合、pgbash内部では次のように変換されて実行されます
      begin;
      declare copy_cur00 cursor for select col1,col2 from tbname;
      fetch 300 in copy_cur00 >> /tmp/oo
      fetch 300 in copy_cur00 >> /tmp/oo
      ..
      end;
    

◎ CGI モードの設定とデータの読みこみ
     exec_sql -i を実行すると、HTML出力<TABLE BORDER=1>をデフォルトにします。また GET/POSTメソッドによるWWWサーバからのデータ入力およびHTTP_COOKIEのデータ読込を行います。

  1. CGIスクリプトの記述例

     例えば、次のようなホームページがあるものとします。
    <HTML>
    <FORM METHOD=POST ACTION="pgbash-test.sh">
    <INPUT TYPE=password NAME=passwd >
    <INPUT TYPE=text NAME="MYNAME" VALUE="sakaida">
    <INPUT TYPE=text NAME="ADDRESS" VALUE="Osaka">
    <INPUT TYPE=submit VALUE=submit>
    </HTML>

    このとき、CGIスクリプト(pgbash-test.sh)は、プログラムの先頭で exec 2>&1、Content-typeの指定、enable文および exec_sql -i を指定します。
    #!/usr/local/bin/pgbash
    exec 2>&1 ............ (1)
    echo "Content-type: text/html" ........................ (2)
    echo ""
    exec_sql -i ......(3)
    #
    connect to dbname as db1 user nopbody $passwd;
    insert into test values( '$MYNAME','$ADDRESS');
    select * from test order by name limit 100;

    (1) exec 2>&1 は、標準エラー出力を標準出力に出力するための指定です。これで、bashが出力するエラーメッセージもホームページに表示することができます。
    (2) echo "Content-type: text/html"と echo ""は必須です。
    (3) enable 文の後に必ず exec_sql -i を実行します。exec_sql -i はこのシェルスクリプトをCGIモードに設定し、またホームページで入力されたデータをシェル変数として設定します。

  2. GET/POSTメソッドによるデータの読みこみ

    exec_sql -i を実行すると、ホームページでのデータ名(上例では passwd, MYNAME, ADDRESS)をそのままシェル変数として扱うことができます。(上記の(4),(5)を参照)

  3. クッキーのデータ読みこみ

    クッキーが設定されている場合は、$HTTP_COOKIE の値を分解して次のシェル変数に代入します。
      $HTTP_NCOOKIE        : クッキーの個数
      ${HTTP_COOKIEKEY[i]} : クッキーのキー名
      ${HTTP_COOKIEVAL[i]} : クッキーの値   
     (但し、i は 0 から HTTP_NCOOKIE-1 までです。)

◎ SQL実行状態を表すシェル変数
     pgbashは、SQL実行後の処理結果をシェル変数にセットします。このシェル変数はSQL実行毎に毎回更新されますので、この値を保持したい場合は別のシェル変数に代入しておく必要があります。主なシェル変数は次です。
      $SQLOID     :(整数型) 最新のinsertのOIDの値
     $SQLCODE    :(整数型) SQLエラーコード (9.エラーコード参照)
                     0    --- 正常終了          
                     100  --- EOF(Eond Of File)  
                     負値 --- SQLエラー         
      $SQLERRMC   :(文字型) SQLエラーメッセージ(最大70字)
     $SQLERRML   :(整数型) SQL エラーメッセージの長さ(<70)
      $SQLERRD2   :(整数型) 検索結果の行数(PQntuples()の値)
      $SQLERRD3   :(整数型) 検索結果の列数(PQnfields()の値)
      $SQLNTUPLE  :(整数型) SQLERRD2と同じ
      $SQLNFIELD  :(整数型) SQLERRD3と同じ
    
      ${SQLFIELDNAME[i]} : 列名並び(i は 0 から SQLNFIELD-1 まで)
    
◎ エラーコード
     pgbashは、SQLエラーコードを次のシェル変数にセットしています。シェル変数は'exec_sql -h errno'(対話型環境では、'h errno')で見ることができます。
        SQL_OK                 :    0 : normal end. 
        SQL_NOT_FOUND          :  100 : EOF(End Of File). 
        SQL_SYSTEM_ERROR       : -200 : system error. 
        SQL_TOO_MANY_ARGUMENTS : -201 : too many arguments in fetch_stmt. 
        SQL_TOO_FEW_ARGUMENTS  : -202 : too few  arguments in fetch_stmt. 
        SQL_CONNECT_ERROR      : -203 : Database connection error. 
        SQL_INVALID_STMT       : -230 : invalid statements. 
        SQL_READONLY_SHELLVAR  : -231 : can not set read-only shell variable. 
        SQL_DB_NOT_OPEN        : -232 : DB not open. 
        SQL_CNAME_NOT_FOUND    : -233 : connect-name not found. 
        SQL_CNAME_ALREADY_USE  : -234 : connect-name already exist. 
        SQL_INVALID_COMMAND    : -235 : invalid command. 
        SQL_BAD_RESPONSE       : -400 : bad response(backend maybe died)." 
        SQL_EMPTY_QUERY        : -401 : empty query (backend lost query). 
        SQL_CONNECTION_BAD     : -402 : connection bad(disconnect backend)" 
        SQL_FATAL_ERROR        : -403 : query fatal error   (SQL error on backend) 
       SQL_NONFATAL_ERROR     : -404 : query nonfatal error(SQL error on backend) 
        SQL_NULL               :   -1 : indicator is NULL. 
    
     エラーコードは、(( ))演算式を利用してシェルスクリプトの中で次のように使用します。
     (例)
     insert into test values(111,'aaa','bbb');
      if(( SQLCODE < SQL_OK ))
      then
         echo $SQLERRMC
      fi
    
    また、SQL実行後に'exec_sql -s'(対話型環境では、's')とすると、エラーコードなどを表示することができます。
    # SQL status (shell variable)                           
      SQLCODE   = -403   (SQL error code)
      SQLNTUPLES= 0      (number of tuples)
      SQLNFIELDS= 0      (number of fields)
      SQLERRML  = 38     (length of SQLERRMC)     
      SQLERRMC  = ERROR:  testxxx: Table does not exist.
    
◎ 制約
  • bashコマンド

     bashの declare、set、selectコマンドは、SQL文の先頭語と同じになります。pgbashでは、SQL文を優先的に取り扱いますので、bashのコマンド名を次のように変更してます。
      bashのdeclareコマンド ==> declares
      bashのsetコマンド     ==> sets
      bashのselectコマンド  ==> selects
    
  • SQL; の位置

    SQL; は、文の先頭からかもしくは、time [option] のタイムスペックの後ろしか記述できません。if文や while文などの後ろには記述できません。

  • SQL実行後のシェル変数の利用

    SQLをパイプライン処理( | more など)やバックグランドジョブ(SQL; & )で実行した場合、SQL実行後のシェル変数(例えば、$SQLCODEなど)は参照できません。これは、パイプライン処理とバックグランド処理が、別プロセスで起動されるため、もとのプロセスにシェル変数の値を返せないからです。例えば次のような使い方は正しくありません。

    (1) SQL状態表示の exec_sql -s ( 対話型環境では s )

    prompt> select * from test; | more
    prompt> s ...上のselect文のSQL状態は参照できません。

    (2) バックグランドジョブの fetch into

    fetch in cur into :aa, :bb; & ... $aa,$bbの値を参照できません


[Home] [ダウンロード] [インストール] [使用方法] [使用例] [FAQ]

Last Modified at 2000/05/10