sqlpostgres 1.2.4

data/lib/sqlpostgres/Connection.rb

@@ -0,0 +1,198 @@
+module SqlPostgres
+
+  # This class holds a connection to the database.
+
+  class Connection
+
+    require 'pg'
+
+    # If true, then PGError exceptions have the offending statement
+    # added to them.
+
+    attr_accessor 'statement_in_exception'
+
+    # The underlying instance of PGconn.  This is for when PGconn does
+    # something that this library doesn't do.
+
+    attr_reader :pgconn
+
+    @@pgClass = PG
+    @@default = nil
+
+    # Get the default connection.  If there isn't one, returns the
+    # NullConnection instead.
+
+    def Connection.default
+      if @@default.nil?
+        NullConnection.new
+      else
+        @@default
+      end
+    end
+
+    # Set the default connection.
+
+    def Connection.default=(value)
+      @@default = value
+    end
+
+    # Open a connection, pass it to the block, then close it.
+    # The connection is closed even if an exception occurs.
+    # Returns the result of the block.
+    #
+    # Takes the same arguments as new.
+    #
+    # Note: If an exception occurs, then any exception from closing
+    # the connection is ignored.  This is to avoid masking the original
+    # (and presumably more important) exception.
+
+    def Connection.open(*args)
+      connection = Connection.new(*args)
+      begin
+        result = yield(connection)
+      rescue
+        begin
+          connection.close
+        rescue
+        end
+        raise
+      else
+        connection.close
+      end
+      result
+    end
+
+    # Create a connection.  
+    #
+    # To create a new connection, pass zero or more of the following
+    # arguments They get passed through to PGconn.connect.
+    #
+    # 'host_name':: 
+    #    The host to connect to.  Defaults to 'localhost'
+    # 'port':: 
+    #    The port to connect to.  Defaults to 5432
+    # 'options':: 
+    #    Back end options.  Defaults to ''
+    # 'tty':: 
+    #    Name of TTY for back end messages.  Defaults to ''
+    # 'db_name':: 
+    #    Database name.  '', the default, means to use the database
+    #    with the same name as the user.
+    # 'login':: 
+    #    Login name.  nil, the default, means to use the user's name.
+    #    to nil.
+    # 'password'::
+    #    Password.  nil, the default, means no password.
+    #
+    # To wrap an existing connection, pass this argument:
+    #
+    # 'connection'::
+    #   The PGConn instance to wrap.
+    #
+    # The following arguments influence SqlPostgres's behavior; 
+    # they're not actually used to establish the connection to postgres:
+    #
+    # 'statement_in_exception'::
+    #   If true, add the offending statement PGError exceptions.  Defaults
+    #   to true.
+
+    def initialize(args = {})
+      raise ArgumentError, "Block not allowed" if block_given?
+      @pgconn = args['connection']
+      if @pgconn.nil?
+        hostName = args['host_name'] || "localhost"
+        dbName = args['db_name'] || ""
+        port = args['port'] || 5432
+        options = args['options'] || ""
+        tty = args['tty'] || ""
+        login = args['login']
+        password = args['password']
+        @pgconn = @@pgClass.connect(hostName, port, options, tty, dbName, 
+                                    login, password)
+      end
+      @statement_in_exception = args['statement_in_exception']
+      @statement_in_exception = true if @statement_in_exception.nil?
+      @pgconn.set_client_encoding("unicode")
+    end
+
+    # close the connection.  If it's already closed, do nothing.
+
+    def close
+      return if @pgconn.nil?
+      @pgconn.close
+      @pgconn = nil
+    end
+
+    # Send an SQL statement to the backend.  Returns a PGResult.  This
+    # is just a thin wrapper around PGConn.exec, and exists for when
+    # you want to do some SQL that Insert, Update, Select, or
+    # Transaction won't do for you (ie, "create temporary table").  
+    #
+    # If a PGError exception occurs and statement_in_exception is
+    # true, then statement is added to the exception.
+
+    def exec(statement)
+      begin
+        @pgconn.exec(statement)
+      rescue PGError => e
+        if statement_in_exception
+          e = e.exception(e.message + 
+                          "The offending statement is: #{statement.inspect}")
+        end
+        raise e
+      end
+    end
+
+    # Send an SQL statement to the backend.  Returns an array of arrays.
+    #
+    # If a PGError exception occurs and statement_in_exception is
+    # true, then statement is added to the exception.
+
+    def query(statement)
+      result = exec(statement)
+      result.send(result_method(result))
+    end
+
+    # This is a hook for rspec (mock this method to find out what sql
+    # is being executed, and to inject translated results).
+
+    def exec_and_translate(statement, columns)
+      translate_pgresult(exec(statement), columns)
+    end
+
+    private
+
+    def result_method(result)
+      if result.respond_to?(:result)
+        :result
+      else
+        :values
+      end
+    end
+
+    def translate_pgresult(pgresult, columns)
+      pgresult.values.collect do |row|
+        hash = {}
+        columns.each_with_index do |column, i|
+          unless column.converter.nil?
+            typeCode = pgresult.ftype(i)
+            value = row[i]
+            args = [value]
+            args << typeCode if column.converter.arity == 2
+            hash[column.as || column.value] = 
+              value && column.converter.call(*args)
+          end
+        end
+        hash
+      end
+    end
+
+  end
+
+end
+
+# Local Variables:
+# tab-width: 2
+# ruby-indent-level: 2
+# indent-tabs-mode: nil
+# End:

data/lib/sqlpostgres/Cursor.rb

@@ -0,0 +1,157 @@
+module SqlPostgres
+
+  # This class creates and manages a cursor.
+  #
+  # Example:
+  #** example: cursor
+  #   Transaction.new(connection) do
+  #     select = Select.new(connection)
+  #     select.select('i')
+  #     select.from('foo')
+  #     Cursor.new('my_cursor', select, {}, connection) do |cursor|
+  #       while !(rows = cursor.fetch).empty?
+  #         for row in rows
+  #           p row # {"i"=>0}
+  #                 # {"i"=>1}
+  #                 # {"i"=>2}
+  #                 # {"i"=>3}
+  #                 # {"i"=>4}
+  #           end
+  #       end
+  #     end
+  #   end
+  #**
+  #
+  # Fetching a single row at a time, the default for fetch, is slow.
+  # Usually you will want to speed things up by calling, for example,
+  # fetch(1000).
+
+  class Cursor
+
+    # Create a cursor.  If a block is given, yield the cursor to the
+    # block, closing the cursor when the block returns, and returning
+    # results of the block.
+    #
+    # If no connection is given, then the default connection is used.
+    #
+    # [name]
+    #   The cursor's name
+    # [select]
+    #   a Select statement
+    # [opts]
+    #   Options hash.  Keys are:
+    #     :scroll=>(boolean)    If true, create a SCROLL cursor.  If false,
+    #                           create a NO SCROLL cursor.  If not specified,
+    #                           the default is to allow scrolling in cases
+    #                           where performance will not suffer.
+    #     :hold=>(boolean)      If true, create a WITH HOLD cursor.  If
+    #                           false, create a HOLD cursor.  WITHOUT HOLD
+    #                           is the default.  A HOLD cursor can be used
+    #                           outside of the transaction that created it.
+    # [connection]
+    #   The database connection
+
+    def initialize(name, select, opts = {}, connection = Connection.default)
+      if block_given?
+        cursor = self.class.new(name, select, opts, connection)
+        result = yield(cursor)
+        cursor.close
+        result
+      else
+        @name = name
+        @select = select
+        @opts = opts
+        @connection = connection
+        declare_cursor
+      end
+    end
+
+    # Fetch a row or rows from the cursor.
+    #
+    # [direction]
+    #   A string specifying which row or rows to fetch.  See the
+    #   postgres documentation for the "DECLARE" statement.
+    #     NEXT
+    #     PRIOR
+    #     FIRST
+    #     LAST
+    #     ABSOLUTE count
+    #     RELATIVE count
+    #     count
+    #     ALL
+    #     FORWARD
+    #     FORWARD count
+    #     FORWARD ALL
+    #     BACKWARD
+    #     BACKWARD count
+    #     BACKWARD ALL
+    
+    def fetch(direction = 'NEXT')
+      @select.fetch_by_cursor(@name, direction, @connection)
+    end
+
+    # Seek a cursor.  Works exactly the same (and takes the same
+    # arguments) as fetch, but returns no rows.
+    #
+    # [direction]
+    #   See #fetch
+
+    def move(direction = 'NEXT')
+      statement = "move #{direction} from #{@name}"
+      @connection.exec(statement)
+    end
+
+    # Close the cursor.  Once closed, it may closed or fetched from
+    # again.
+
+    def close
+      statement = "close #{@name}"
+      @connection.exec(statement)
+    end
+
+    private
+
+    def declare_cursor
+      statement = [
+        'declare',
+        @name,
+        scroll_declaration,
+        'cursor',
+        hold_declaration,
+        'for',
+        @select.statement
+      ].compact.join(' ')
+      @connection.exec(statement)
+    end
+
+    def scroll_declaration
+      value = @opts.fetch(:scroll, :default)
+      if value == :default
+        nil
+      elsif value
+        "SCROLL"
+      else
+        "NO SCROLL"
+      end
+    end
+
+    def hold_declaration
+      value = @opts.fetch(:hold, :default)
+      if value == :default
+        nil
+      elsif value
+        "WITH HOLD"
+      else
+        "WITHOUT HOLD"
+      end
+    end
+
+  end
+
+end
+
+# Local Variables:
+# tab-width: 2
+# ruby-indent-level: 2
+# indent-tabs-mode: nil
+# End:

data/lib/sqlpostgres/Delete.rb

@@ -0,0 +1,67 @@
+module SqlPostgres
+
+  # This class creates and executes an SQL delete statement.
+
+  class Delete
+
+    # Create a delete statement
+    #
+    # [table]
+    #   The table name
+    # [connection]
+    #   If supplied, the connection to use.  If not supplied, use the
+    #   default.
+    
+    def initialize(table, connection = Connection.default)
+      @table = table
+      @connection = connection
+      @where = []
+    end
+
+    # Add a "where" condition to this statement.
+    #
+    # [expression]
+    #   The condition.  Should be one of:
+    #   [A string] The expression
+    #   [An array] An expression converted using #substitute_values
+
+    def where(expression)
+      @where << Translate.substitute_values(expression)
+    end
+
+    # Return the SQL statement
+
+    def statement
+      "delete from #{@table}#{where_clause}"
+    end
+
+    # Execute the delete statement
+    #
+    # [connection]
+    #   If present, the connection to use.
+    #   If nil, uses the connection passed to new, or if no connection was
+    #   passed to new, uses the default connection.
+
+    def exec(connection = @connection)
+      connection.exec(statement)
+    end
+
+    private
+
+    def where_clause
+      if @where.empty?
+        ""
+      else
+        " where " + @where.join(' and ')
+      end
+    end
+
+  end
+
+end
+
+# Local Variables:
+# tab-width: 2
+# ruby-indent-level: 2
+# indent-tabs-mode: nil
+# End:

data/lib/sqlpostgres/Exceptions.rb

@@ -0,0 +1,15 @@
+module SqlPostgres
+
+  # A function requiring a database connection was called, but the object
+  # didn't have a database connection.
+
+  class NoConnection < Exception
+  end
+
+end
+
+# Local Variables:
+# tab-width: 2
+# ruby-indent-level: 2
+# indent-tabs-mode: nil
+# End:

data/lib/sqlpostgres/Insert.rb

@@ -0,0 +1,279 @@
+module SqlPostgres
+
+  # This class creates and executes an SQL insert statement.
+  #
+  # Example:
+  #** Example: insert
+  #   insert = Insert.new('foo', connection)
+  #   insert.insert('i', 1)
+  #   insert.insert('t', 'foo')
+  #   p insert.statement           # "insert into foo (i, t) values (1, 
+  #                                # E'foo')"
+  #   insert.exec
+  #**
+
+  class Insert
+
+    # Create an insert statement
+    #
+    # [table]
+    #   The table name
+    # [connection]
+    #   If supplied, the connection to use.  If not supplied, use the
+    #   default.
+    
+    def initialize(table, connection = Connection.default)
+      @table = table
+      @connection = connection
+      @columns = []
+      @values = []
+      @query = nil
+    end
+
+    # Add a column to the statement.  This is for all column types
+    # *except* bytea.
+    #
+    # [column]
+    #   The column name
+    # [value]
+    #   The value to add.  The value is SQL escaped.
+    #   Should be one of:
+    #   * a String
+    #   * an Integer
+    #   * a Float
+    #   * a Time
+    #   * false
+    #   * true
+    #   * nil
+    #   * a Select
+    #   * :default
+    #   * :no_value
+    # 
+    # Special values:
+    # [a Select]
+    #   The select's SQL is added in parentheses
+    # [:default] 
+    #   Add the SQL keyword "default" to the statement.
+    # [:no_value] 
+    #     Do not add a value for this column.  This is used when the
+    #     values are being provided by a Select statement.
+    #
+    # Example (simple)
+    #** Example: insert_insert
+    #   insert = Insert.new('foo')
+    #   insert.insert('t', 'bar')
+    #   p insert.statement         # "insert into foo (t) values (E'bar')"
+    #**
+    #
+    # Example (select)
+    #** Example: insert_insert_select
+    #   select = Select.new
+    #   select.select('j')
+    #   select.from('bar')
+    #   select.limit(1)
+    #   insert = Insert.new('foo')
+    #   insert.insert('i', select)
+    #   p insert.statement           # "insert into foo (i) values ((select j 
+    #                                # from bar limit 1))"
+    #**
+    #
+    # Example (default)
+    #** Example: insert_insert_default
+    #   insert = Insert.new('foo')
+    #   insert.insert('i', :default)
+    #   p insert.statement             # "insert into foo (i) values 
+    #                                  # (default)"
+    #**
+
+    def insert(column, value = :no_value)
+      @columns << column
+      @values << Translate.escape_sql(value) unless value == :no_value
+    end
+
+    # Insert into an array (int[], text[], etc) column.  This is not
+    # for byte array (bytea) column types: For that, call
+    # #insert_bytea.
+    #
+    # [column]
+    #   The column name
+    # [value]
+    #  The value to add.
+    #
+    # This is used for inserting literals and expressions.  To insert
+    # the result of an SQL query, or to insert the default value,
+    # call #insert.
+
+    def insert_array(column, value)
+      @columns << column
+      @values << Translate.escape_array(value)
+    end
+
+    # Insert into a bytea column.  You must use this function, not
+    # #insert, when inserting a string into a bytea column.  That's
+    # because bytea columns need special escaping.
+    #
+    # [column]
+    #   The column name
+    # [value]
+    #   The value to add.
+    #   Should be one of:
+    #   * a String
+    #   * :default
+    #   * :no_value
+    # 
+    # Special values:
+    # [a Select]
+    #   The select's SQL is added in parentheses
+    # [:default] 
+    #   Add the SQL keyword "default" to the statement.
+    # [:no_value] 
+    #     Do not add a value for this column.  This is used when the
+    #     values are being provided by a Select statement.
+    #
+    # Example:
+    #** Example: insert_bytea
+    #   insert = Insert.new('foo')
+    #   insert.insert_bytea('t', "\000\001\002\003")
+    #   p insert.statement     # "insert into foo (t) values 
+    #                          # (E'\\\\000\\\\001\\\\002\\\\003')"
+    #**
+
+    def insert_bytea(column, value = :no_value)
+      @columns << column
+      @values << Translate.escape_bytea(value) unless value == :no_value
+    end
+
+    # Insert into a bytea[] (bytea array) column.  You must use this
+    # function, not #insert or #insert_array, because bytea[] columns
+    # need special escaping.
+    #
+    #** Example: insert_bytea_array
+    #   insert = Insert.new('foo')
+    #   insert.insert_bytea_array('t', ["foo", "\000bar\nbaz"])
+    #   p insert.statement     # "insert into foo (t) values 
+    #                          # ('{\"foo\",\"\\\\\\\\000bar\nbaz\"}')"
+    #   
+    #**
+
+    def insert_bytea_array(column, value = :no_value)
+      @columns << column
+      @values << Translate.escape_bytea_array(value) unless value == :no_value
+    end
+
+    # Insert into a "char" column.  This is a Postgres specific data
+    # type that is different than char or character (yes, the quotes
+    # are part of the type name).  "char" values are escaped
+    # differently than normal test, so be sure to use this method and
+    # not #insert when inserting into a "char" column.
+    #
+    # [column]
+    #   The column name
+    # [value]
+    #   A string of length 1
+    #
+    # Example:
+    #** Example: insert_qchar
+    #**
+
+    def insert_qchar(column, value = :no_value)
+      @columns << column
+      @values << Translate.escape_qchar(value)
+    end
+
+    # Insert the results of a select statement
+    #
+    # Example:
+    #** Example: insert_select
+    #   select = Select.new
+    #   select.select('i')
+    #   select.from('bar')
+    #   insert = Insert.new('foo')
+    #   insert.insert('i')
+    #   insert.select(select)
+    #   p insert.statement     # "insert into foo (i) select i from bar"
+    #**
+
+    def select(select)
+      @query = select.statement
+    end
+
+    # Define return clause
+    #
+    # Example: (simple)
+    #** Example: insert_returning
+    #   insert = Insert.new('foo')
+    #   insert.insert('i', 3)
+    #   insert.returning('i')
+    #   p insert.statement       # "insert into foo (i) values (3) returning i
+    #
+    # Example: (expression_with_alias)
+    #** Example: insert_returning_with_alias
+    #   insert = Insert.new('foo')
+    #   insert.insert('i', 3)
+    #   insert.returning('i*3', 'calc')
+    #   p insert.statement       # "insert into foo (i) values (3) returning i*3 as calc
+
+    def returning(expression, name=nil)
+      str = "returning #{expression}"
+      str += " as #{name}" if name
+      @returning_expression = str
+    end
+
+    # insert default values
+    #
+    # Example:
+    #** Example: insert_default_values
+    #   insert = Insert.new('foo')
+    #   insert.default_values
+    #   p insert.statement     # "insert into foo default values"
+    #**
+
+    def default_values
+      @query = "default values"
+    end
+
+    # Return the SQL statement.  Especially useful for debugging.
+
+    def statement
+      [
+        "insert into",
+        @table,
+        column_list,
+        query_expression,
+      ].compact.join(' ')
+    end
+
+    # Execute the statement.
+    #
+    # [connection]
+    #   If present, the connection to use.
+    #   If nil, uses the connection passed to new or, if no connection was
+    #   passed to new, uses the default connection.
+
+    def exec(connection = @connection)
+      connection.exec(statement)
+    end
+
+    private
+
+    def query_expression
+      @query || source
+    end
+
+    def column_list
+      "(#{@columns.join(', ')})" unless @columns.empty?
+    end
+
+    def source
+      "values (#{@values.join(', ')}) #{@returning_expression}".strip
+    end
+
+  end
+
+end
+
+# Local Variables:
+# tab-width: 2
+# ruby-indent-level: 2
+# indent-tabs-mode: nil
+# End: