logo

class

sql::Connection

sys::Obj
  sql::Connection
   1  //
   2  // Copyright (c) 2007, Brian Frank and Andy Frank
   3  // Licensed under the Academic Free License version 3.0
   4  //
   5  // History:
   6  //   30 Jun 07  Brian Frank  Creation
   7  //
   8  
   9  **
  10  ** Connection manages a logical connection to an SQL database.
  11  **
  12  ** Refer to the [Sql docs]`docLib::Sql` for more details.
  13  **
  14  class Connection
  15  {
  16  
  17  //////////////////////////////////////////////////////////////////////////
  18  // Lifecycle
  19  //////////////////////////////////////////////////////////////////////////
  20  
  21    **
  22    ** Open a connection to a SQL database.  Throw 'Err' on failure.
  23    **
  24    ** In a Java platform, the connection is opened using JDBC.  The
  25    ** database Str specifies the 'java.sql.Connection' URL.  The JDBC
  26    ** driver class should be preloaded - the simplest mechanism is to
  27    ** add it to "sys.props".
  28    **
  29    static native Connection open(Str database, Str username, Str password)
  30  
  31    **
  32    ** Internal constructor.
  33    **
  34    internal new make() {}
  35  
  36    **
  37    ** Return if this connection has been closed.
  38    **
  39    native Bool isClosed()
  40  
  41    **
  42    ** Close the connection.  This method is guaranteed to never throw
  43    ** an 'Err'.  Return true if the connection was closed successfully
  44    ** or 'false' if closed abnormally.
  45    **
  46    native Bool close()
  47  
  48  //////////////////////////////////////////////////////////////////////////
  49  // Database metadata
  50  //////////////////////////////////////////////////////////////////////////
  51  
  52    **
  53    ** List the tables in the database.  Returns a list of the
  54    ** table names.
  55    **
  56    native Str[] tables()
  57  
  58    **
  59    ** Get a default row instance for the specified table.  The
  60    ** result has a field for each table column.
  61    **
  62    native Obj tableRow(Str tableName)
  63  
  64  //////////////////////////////////////////////////////////////////////////
  65  // Statements
  66  //////////////////////////////////////////////////////////////////////////
  67  
  68    **
  69    ** Execute an SQL query which returns a relational table as a
  70    ** result.  If 'of' is 'null', the result is returned as a 'List'
  71    ** of 'Rows'.  The 'Cols' are available from 'List.of.fields' or
  72    ** on 'type.fields' of each row instance.  If 'of' is specified,
  73    ** then the result is returned as a 'List' of that type.  Columns
  74    ** are mapped to the type's fields.  If a column cannot be mapped
  75    ** to a field, then an 'SqlErr' is thrown.
  76    **
  77    native Obj[] query(Str sql, Type of := null)
  78  
  79    **
  80    ** Execute an SQL query.  For each row in the result, invoke
  81    ** the specified function 'c'.  If 'of' is null, the 'Obj'
  82    ** passed to the 'each' function will be of type 'Row'.
  83    ** Otherwise the 'of' type specifies the row type passed
  84    ** to the 'each' function.
  85    **
  86    native Void queryEach(Str sql, Type of, |Obj row| each)
  87    
  88    **
  89    ** Execute a SQL statement and if applicable return
  90    ** the number of rows modified.
  91    **
  92    native Int execute(Str sql)
  93    
  94    **
  95    ** Prepare a statement for use later with this connection.
  96    **
  97    Statement prepare(Str sql)
  98    {
  99      return Statement.make(this, sql).prepare()
 100    }
 101  
 102  //////////////////////////////////////////////////////////////////////////
 103  // Transactions
 104  //////////////////////////////////////////////////////////////////////////
 105  
 106    **
 107    ** If auto commit is 'true', then each statement is executed
 108    ** immediately.  Otherwise statements are executed inside a
 109    ** transaction which is terminated by a call to 'commit'
 110    ** or 'rollback'.  Auto commit defaults to 'true'.
 111    **
 112    Bool autoCommit
 113    {
 114      get { return getAutoCommit }
 115      set { setAutoCommit(val) }
 116    }
 117    private native Bool getAutoCommit()
 118    private native Void setAutoCommit(Bool b)
 119  
 120  
 121    **
 122    ** Commit all the changes made inside the current transaction.
 123    **
 124    native Void commit()
 125  
 126    **
 127    ** Undo any changes made inside the current transaction.
 128    **
 129    native Void rollback()
 130  
 131  }