Class: PG::Connection

Inherits:
Object show all
Defined in:
lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb

Overview

The PostgreSQL connection class. The interface for this class is based on libpq, the C application programmer’s interface to PostgreSQL. Some familiarity with libpq is recommended, but not necessary.

For example, to send query to the database on the localhost:

require 'pg'
conn = PG::Connection.open(:dbname => 'test')
res = conn.exec_params('SELECT $1 AS a, $2 AS b, $3 AS c', [1, 2, nil])
# Equivalent to:
#  res  = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')

See the PG::Result class for information on working with the results of a query.

Many methods of this class have three variants kind of:

  1. #exec - the base method which is an alias to #async_exec . This is the method that should be used in general.

  2. #async_exec - the async aware version of the method, implemented by libpq’s async API.

  3. #sync_exec - the method version that is implemented by blocking function(s) of libpq.

Sync and async version of the method can be switched by Connection.async_api= , however it is not recommended to change the default.

Constant Summary collapse

CONNECT_ARGUMENT_ORDER =

The order the options are passed to the ::connect method.

%w[host port options tty dbname user password]
REDIRECT_CLASS_METHODS = 
{
  :new => [:async_connect, :sync_connect],
  :connect => [:async_connect, :sync_connect],
  :open => [:async_connect, :sync_connect],
  :setdb => [:async_connect, :sync_connect],
  :setdblogin => [:async_connect, :sync_connect],
  :ping => [:async_ping, :sync_ping],
}
REDIRECT_SEND_METHODS =

These methods are affected by PQsetnonblocking

{
  :isnonblocking => [:async_isnonblocking, :sync_isnonblocking],
  :nonblocking? => [:async_isnonblocking, :sync_isnonblocking],
  :put_copy_data => [:async_put_copy_data, :sync_put_copy_data],
  :put_copy_end => [:async_put_copy_end, :sync_put_copy_end],
  :flush => [:async_flush, :sync_flush],
}
REDIRECT_METHODS = 
{
  :exec => [:async_exec, :sync_exec],
  :query => [:async_exec, :sync_exec],
  :exec_params => [:async_exec_params, :sync_exec_params],
  :prepare => [:async_prepare, :sync_prepare],
  :exec_prepared => [:async_exec_prepared, :sync_exec_prepared],
  :describe_portal => [:async_describe_portal, :sync_describe_portal],
  :describe_prepared => [:async_describe_prepared, :sync_describe_prepared],
  :setnonblocking => [:async_setnonblocking, :sync_setnonblocking],
  :get_result => [:async_get_result, :sync_get_result],
  :get_last_result => [:async_get_last_result, :sync_get_last_result],
  :get_copy_data => [:async_get_copy_data, :sync_get_copy_data],
  :reset => [:async_reset, :sync_reset],
  :set_client_encoding => [:async_set_client_encoding, :sync_set_client_encoding],
  :client_encoding= => [:async_set_client_encoding, :sync_set_client_encoding],
  :cancel => [:async_cancel, :sync_cancel],
}

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.async_api=(enable) ⇒ Object

Switch between sync and async libpq API.

PG::Connection.async_api = true

this is the default. It sets an alias from #exec to #async_exec, #reset to #async_reset and so on.

PG::Connection.async_api = false

sets an alias from #exec to #sync_exec, #reset to #sync_reset and so on.

pg-1.1.0+ defaults to libpq’s async API for query related blocking methods. pg-1.3.0+ defaults to libpq’s async API for all possibly blocking methods.

PLEASE NOTE: This method is not part of the public API and is for debug and development use only. Do not use this method in production code. Any issues with the default setting of async_api=true should be reported to the maintainers instead.



864
865
866
867
868
869
870
871
872
873
874
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 864

def async_api=(enable)
  self.async_send_api = enable
  REDIRECT_METHODS.each do |ali, (async, sync)|
    remove_method(ali) if method_defined?(ali)
    alias_method( ali, enable ? async : sync )
  end
  REDIRECT_CLASS_METHODS.each do |ali, (async, sync)|
    singleton_class.remove_method(ali) if method_defined?(ali)
    singleton_class.alias_method(ali, enable ? async : sync )
  end
end

.async_send_api=(enable) ⇒ Object 



841
842
843
844
845
846
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 841

def async_send_api=(enable)
  REDIRECT_SEND_METHODS.each do |ali, (async, sync)|
    undef_method(ali) if method_defined?(ali)
    alias_method( ali, enable ? async : sync )
  end
end

.conndefaults_hash ⇒ Object

Return the Postgres connection defaults structure as a Hash keyed by option keyword (as a Symbol).

See also #conndefaults



282
283
284
285
286
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 282

def self.conndefaults_hash
  return self.conndefaults.each_with_object({}) do |info, hash|
    hash[ info[:keyword].to_sym ] = info[:val]
  end
end

.connect_hash_to_string(hash) ⇒ Object

Convert Hash options to connection String

Values are properly quoted and escaped.



45
46
47
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 45

def self.connect_hash_to_string( hash )
  hash.map { |k,v| "#{k}=#{quote_connstr(v)}" }.join( ' ' )
end

.new(*args) ⇒ Object Also known as: async_connect, connect, open, setdb, setdblogin

call-seq:

PG::Connection.new -> conn
PG::Connection.new(connection_hash) -> conn
PG::Connection.new(connection_string) -> conn
PG::Connection.new(host, port, options, tty, dbname, user, password) ->  conn

Create a connection to the specified server.

connection_hash must be a ruby Hash with connection parameters. See the list of valid parameters in the PostgreSQL documentation.

There are two accepted formats for connection_string: plain keyword = value strings and URIs. See the documentation of connection strings.

The positional parameter form has the same functionality except that the missing parameters will always take on default values. The parameters are:

host

server hostname

port

server port number

options

backend options

tty

(ignored in all versions of PostgreSQL)

dbname

connecting database name

user

login user name

password

login password

Examples:

# Connect using all defaults
PG::Connection.new

# As a Hash
PG::Connection.new( dbname: 'test', port: 5432 )

# As a String
PG::Connection.new( "dbname=test port=5432" )

# As an Array
PG::Connection.new( nil, 5432, nil, nil, 'test', nil, nil )

# As an URI
PG::Connection.new( "postgresql://user:[email protected]:5432/testdb?sslmode=require" )

If the Ruby default internal encoding is set (i.e., Encoding.default_internal != nil), the connection will have its client_encoding set accordingly.

Raises a PG::Error if the connection fails.



694
695
696
697
698
699
700
701
702
703
704
705
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 694

def new(*args)
  conn = connect_to_hosts(*args)

  if block_given?
    begin
      return yield conn
    ensure
      conn.finish
    end
  end
  conn
end

.parse_connect_args(*args) ⇒ Object

Parse the connection args into a connection-parameter string. See PG::Connection.new for valid arguments.

It accepts:

  • an option String kind of “host=name port=5432”

  • an option Hash kind of “name”, port: 5432

  • URI string

  • URI object

  • positional arguments

The method adds the option “fallback_application_name” if it isn’t already set. It returns a connection string with “key=value” pairs.



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 61

def self.parse_connect_args( *args )
  hash_arg = args.last.is_a?( Hash ) ? args.pop.transform_keys(&:to_sym) : {}
  iopts = {}

  if args.length == 1
    case args.first
    when URI, /=/, /:\/\//
      # Option or URL string style
      conn_string = args.first.to_s
      iopts = PG::Connection.conninfo_parse(conn_string).each_with_object({}){|h, o| o[h[:keyword].to_sym] = h[:val] if h[:val] }
    else
      # Positional parameters (only host given)
      iopts[CONNECT_ARGUMENT_ORDER.first.to_sym] = args.first
    end
  else
    # Positional parameters with host and more
    max = CONNECT_ARGUMENT_ORDER.length
    raise ArgumentError,
        "Extra positional parameter %d: %p" % [ max + 1, args[max] ] if args.length > max

    CONNECT_ARGUMENT_ORDER.zip( args ) do |(k,v)|
      iopts[ k.to_sym ] = v if v
    end
    iopts.delete(:tty) # ignore obsolete tty parameter
  end

  iopts.merge!( hash_arg )

  if !iopts[:fallback_application_name]
    iopts[:fallback_application_name] = $0.sub( /^(.{30}).{4,}(.{30})$/ ){ $1+"..."+$2 }
  end

  return connect_hash_to_string(iopts)
end

.ping(*args) ⇒ Object Also known as: async_ping

call-seq:

PG::Connection.ping(connection_hash)       -> Integer
PG::Connection.ping(connection_string)     -> Integer
PG::Connection.ping(host, port, options, tty, dbname, , password) ->  Integer

Check server status.

See PG::Connection.new for a description of the parameters.

Returns one of:

PQPING_OK

server is accepting connections

PQPING_REJECT

server is alive but rejecting connections

PQPING_NO_RESPONSE

could not establish connection

PQPING_NO_ATTEMPT

connection not attempted (bad params)



789
790
791
792
793
794
795
796
797
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 789

def ping(*args)
  if Fiber.respond_to?(:scheduler) && Fiber.scheduler
    # Run PQping in a second thread to avoid blocking of the scheduler.
    # Unfortunately there's no nonblocking way to run ping.
    Thread.new { sync_ping(*args) }.value
  else
    sync_ping(*args)
  end
end

.quote_connstr(value) ⇒ Object

Quote a single value for use in a connection-parameter string.



38
39
40
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 38

def self.quote_connstr( value )
  return "'" + value.to_s.gsub( /[\\']/ ) {|m| '\\' + m } + "'"
end

Instance Method Details

#cancel ⇒ Object Also known as: async_cancel

call-seq:

conn.cancel() -> String

Requests cancellation of the command currently being processed.

Returns nil on success, or a string containing the error message if a failure occurs.



518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 518

def cancel
  be_pid = backend_pid
  be_key = backend_key
  cancel_request = [0x10, 1234, 5678, be_pid, be_key].pack("NnnNN")

  if Fiber.respond_to?(:scheduler) && Fiber.scheduler && RUBY_PLATFORM =~ /mingw|mswin/
    # Ruby's nonblocking IO is not really supported on Windows.
    # We work around by using threads and explicit calls to wait_readable/wait_writable.
    cl = Thread.new(socket_io.remote_address) { |ra| ra.connect }.value
    begin
      cl.write_nonblock(cancel_request)
    rescue IO::WaitReadable, Errno::EINTR
      cl.wait_writable
      retry
    end
    begin
      cl.read_nonblock(1)
    rescue IO::WaitReadable, Errno::EINTR
      cl.wait_readable
      retry
    rescue EOFError
    end
  elsif RUBY_ENGINE == 'truffleruby'
    begin
      cl = socket_io.remote_address.connect
    rescue NotImplementedError
      # Workaround for truffleruby < 21.3.0
      cl2 = Socket.for_fd(socket_io.fileno)
      cl2.autoclose = false
      adr = cl2.remote_address
      if adr.ip?
        cl = TCPSocket.new(adr.ip_address, adr.ip_port)
        cl.autoclose = false
      else
        cl = UNIXSocket.new(adr.unix_path)
        cl.autoclose = false
      end
    end
    cl.write(cancel_request)
    cl.read(1)
  else
    cl = socket_io.remote_address.connect
    # Send CANCEL_REQUEST_CODE and parameters
    cl.write(cancel_request)
    # Wait for the postmaster to close the connection, which indicates that it's processed the request.
    cl.read(1)
  end

  cl.close
  nil
rescue SystemCallError => err
  err.to_s
end

#conndefaults ⇒ Object

Returns an array of Hashes with connection defaults. See ::conndefaults for details.



274
275
276
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 274

def conndefaults
  return self.class.conndefaults
end

#conndefaults_hash ⇒ Object

Returns a Hash with connection defaults. See ::conndefaults_hash for details.



290
291
292
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 290

def conndefaults_hash
  return self.class.conndefaults_hash
end

#conninfo_hash ⇒ Object

Return the Postgres connection info structure as a Hash keyed by option keyword (as a Symbol).

See also #conninfo



298
299
300
301
302
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 298

def conninfo_hash
  return self.conninfo.each_with_object({}) do |info, hash|
    hash[ info[:keyword].to_sym ] = info[:val]
  end
end

#copy_data(sql, coder = nil) ⇒ Object

call-seq:

conn.copy_data( sql [, coder] ) {|sql_result| ... } -> PG::Result

Execute a copy process for transferring data to or from the server.

This issues the SQL COPY command via #exec. The response to this (if there is no error in the command) is a PG::Result object that is passed to the block, bearing a status code of PGRES_COPY_OUT or PGRES_COPY_IN (depending on the specified copy direction). The application should then use #put_copy_data or #get_copy_data to receive or transmit data rows and should return from the block when finished.

#copy_data returns another PG::Result object when the data transfer is complete. An exception is raised if some problem was encountered, so it isn’t required to make use of any of them. At this point further SQL commands can be issued via #exec. (It is not possible to execute other SQL commands using the same connection while the COPY operation is in progress.)

This method ensures, that the copy process is properly terminated in case of client side or server side failures. Therefore, in case of blocking mode of operation, #copy_data is preferred to raw calls of #put_copy_data, #get_copy_data and #put_copy_end.

coder can be a PG::Coder derivation (typically PG::TextEncoder::CopyRow or PG::TextDecoder::CopyRow). This enables encoding of data fields given to #put_copy_data or decoding of fields received by #get_copy_data.

Example with CSV input format:

conn.exec "create table my_table (a text,b text,c text,d text)"
conn.copy_data "COPY my_table FROM STDIN CSV" do
  conn.put_copy_data "some,data,to,copy\n"
  conn.put_copy_data "more,data,to,copy\n"
end

This creates my_table and inserts two CSV rows.

The same with text format encoder PG::TextEncoder::CopyRow and Array input:

enco = PG::TextEncoder::CopyRow.new
conn.copy_data "COPY my_table FROM STDIN", enco do
  conn.put_copy_data ['some', 'data', 'to', 'copy']
  conn.put_copy_data ['more', 'data', 'to', 'copy']
end

Example with CSV output format:

conn.copy_data "COPY my_table TO STDOUT CSV" do
  while row=conn.get_copy_data
    p row
  end
end

This prints all rows of my_table to stdout:

"some,data,to,copy\n"
"more,data,to,copy\n"

The same with text format decoder PG::TextDecoder::CopyRow and Array output:

deco = PG::TextDecoder::CopyRow.new
conn.copy_data "COPY my_table TO STDOUT", deco do
  while row=conn.get_copy_data
    p row
  end
end

This receives all rows of my_table as ruby array:

["some", "data", "to", "copy"]
["more", "data", "to", "copy"]

Raises:



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 185

def copy_data( sql, coder=nil )
  raise PG::NotInBlockingMode.new("copy_data can not be used in nonblocking mode", connection: self) if nonblocking?
  res = exec( sql )

  case res.result_status
  when PGRES_COPY_IN
    begin
      if coder
        old_coder = self.encoder_for_put_copy_data
        self.encoder_for_put_copy_data = coder
      end
      yield res
    rescue Exception => err
      errmsg = "%s while copy data: %s" % [ err.class.name, err.message ]
      put_copy_end( errmsg )
      get_result
      raise
    else
      put_copy_end
      get_last_result
    ensure
      self.encoder_for_put_copy_data = old_coder if coder
    end

  when PGRES_COPY_OUT
    begin
      if coder
        old_coder = self.decoder_for_get_copy_data
        self.decoder_for_get_copy_data = coder
      end
      yield res
    rescue Exception => err
      cancel
      begin
        while get_copy_data
        end
      rescue PG::Error
        # Ignore error in cleanup to avoid losing original exception
      end
      while get_result
      end
      raise err
    else
      res = get_last_result
      if !res || res.result_status != PGRES_COMMAND_OK
        while get_copy_data
        end
        while get_result
        end
        raise PG::NotAllCopyDataRetrieved.new("Not all COPY data retrieved", connection: self)
      end
      res
    ensure
      self.decoder_for_get_copy_data = old_coder if coder
    end

  else
    raise ArgumentError, "SQL command is no COPY statement: #{sql}"
  end
end

#encrypt_password(password, username, algorithm = nil) ⇒ Object Also known as: async_encrypt_password

call-seq:

conn.encrypt_password( password, username, algorithm=nil ) -> String

This function is intended to be used by client applications that wish to send commands like ALTER USER joe PASSWORD 'pwd'. It is good practice not to send the original cleartext password in such a command, because it might be exposed in command logs, activity displays, and so on. Instead, use this function to convert the password to encrypted form before it is sent.

The password and username arguments are the cleartext password, and the SQL name of the user it is for. algorithm specifies the encryption algorithm to use to encrypt the password. Currently supported algorithms are md5 and scram-sha-256 (on and off are also accepted as aliases for md5, for compatibility with older server versions). Note that support for scram-sha-256 was introduced in PostgreSQL version 10, and will not work correctly with older server versions. If algorithm is omitted or nil, this function will query the server for the current value of the password_encryption setting. That can block, and will fail if the current transaction is aborted, or if the connection is busy executing another query. If you wish to use the default algorithm for the server but want to avoid blocking, query password_encryption yourself before calling #encrypt_password, and pass that value as the algorithm.

Return value is the encrypted password. The caller can assume the string doesn’t contain any special characters that would require escaping.

Available since PostgreSQL-10. See also corresponding libpq function.



491
492
493
494
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 491

def encrypt_password( password, username, algorithm=nil )
  algorithm ||= exec("SHOW password_encryption").getvalue(0,0)
  sync_encrypt_password(password, username, algorithm)
end

#get_copy_data(async = false, decoder = nil) ⇒ Object Also known as: async_get_copy_data

call-seq:

conn.get_copy_data( [ nonblock = false [, decoder = nil ]] ) -> Object

Return one row of data, nil if the copy is done, or false if the call would block (only possible if nonblock is true).

If decoder is not set or nil, data is returned as binary string.

If decoder is set to a PG::Coder derivation, the return type depends on this decoder. PG::TextDecoder::CopyRow decodes the received data fields from one row of PostgreSQL’s COPY text format to an Array of Strings. Optionally the decoder can type cast the single fields to various Ruby types in one step, if PG::TextDecoder::CopyRow#type_map is set accordingly.

See also #copy_data.



359
360
361
362
363
364
365
366
367
368
369
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 359

def get_copy_data(async=false, decoder=nil)
  if async
    return sync_get_copy_data(async, decoder)
  else
    while (res=sync_get_copy_data(true, decoder)) == false
      socket_io.wait_readable
      consume_input
    end
    return res
  end
end

#get_result ⇒ Object Also known as: async_get_result

call-seq:

conn.get_result() -> PG::Result
conn.get_result() {|pg_result| block }

Blocks waiting for the next result from a call to #send_query (or another asynchronous command), and returns it. Returns nil if no more results are available.

Note: call this function repeatedly until it returns nil, or else you will not be able to issue further commands.

If the optional code block is given, it will be passed result as an argument, and the PG::Result object will automatically be cleared when the block terminates. In this instance, conn.exec returns the value of the block.



336
337
338
339
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 336

def get_result
  block
  sync_get_result
end

#inspect ⇒ Object

Return a String representation of the object suitable for debugging.



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 97

def inspect
  str = self.to_s
  str[-1,0] = if finished?
    " finished"
  else
    stats = []
    stats << " status=#{ PG.constants.grep(/CONNECTION_/).find{|c| PG.const_get(c) == status} }" if status != CONNECTION_OK
    stats << " transaction_status=#{ PG.constants.grep(/PQTRANS_/).find{|c| PG.const_get(c) == transaction_status} }" if transaction_status != PG::PQTRANS_IDLE
    stats << " nonblocking=#{ isnonblocking }" if isnonblocking
    stats << " pipeline_status=#{ PG.constants.grep(/PQ_PIPELINE_/).find{|c| PG.const_get(c) == pipeline_status} }" if respond_to?(:pipeline_status) && pipeline_status != PG::PQ_PIPELINE_OFF
    stats << " client_encoding=#{ get_client_encoding }" if get_client_encoding != "UTF8"
    stats << " type_map_for_results=#{ type_map_for_results.to_s }" unless type_map_for_results.is_a?(PG::TypeMapAllStrings)
    stats << " type_map_for_queries=#{ type_map_for_queries.to_s }" unless type_map_for_queries.is_a?(PG::TypeMapAllStrings)
    stats << " encoder_for_put_copy_data=#{ encoder_for_put_copy_data.to_s }" if encoder_for_put_copy_data
    stats << " decoder_for_get_copy_data=#{ decoder_for_get_copy_data.to_s }" if decoder_for_get_copy_data
    " host=#{host} port=#{port} user=#{user}#{stats.join}"
  end
  return str
end

#isnonblocking ⇒ Object Also known as: async_isnonblocking, nonblocking?

call-seq:

conn.isnonblocking() -> Boolean

Returns the blocking status of the database connection. Returns true if the connection is set to nonblocking mode and false if blocking.



407
408
409
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 407

def isnonblocking
  false
end

#put_copy_data(buffer, encoder = nil) ⇒ Object Also known as: async_put_copy_data

call-seq:

conn.put_copy_data( buffer [, encoder] ) -> Boolean

Transmits buffer as copy data to the server. Returns true if the data was sent, false if it was not sent (false is only possible if the connection is in nonblocking mode, and this command would block).

encoder can be a PG::Coder derivation (typically PG::TextEncoder::CopyRow). This encodes the data fields given as buffer from an Array of Strings to PostgreSQL’s COPY text format inclusive proper escaping. Optionally the encoder can type cast the fields from various Ruby types in one step, if PG::TextEncoder::CopyRow#type_map is set accordingly.

Raises an exception if an error occurs.

See also #copy_data.



431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 431

def put_copy_data(buffer, encoder=nil)
  # sync_put_copy_data does a non-blocking attept to flush data.
  until res=sync_put_copy_data(buffer, encoder)
    # It didn't flush immediately and allocation of more buffering memory failed.
    # Wait for all data sent by doing a blocking flush.
    res = flush
  end

  # And do a blocking flush every 100 calls.
  # This is to avoid memory bloat, when sending the data is slower than calls to put_copy_data happen.
  if (@calls_to_put_copy_data += 1) > 100
    @calls_to_put_copy_data = 0
    res = flush
  end
  res
end

#put_copy_end(*args) ⇒ Object Also known as: async_put_copy_end

call-seq:

conn.put_copy_end( [ error_message ] ) -> Boolean

Sends end-of-data indication to the server.

error_message is an optional parameter, and if set, forces the COPY command to fail with the string error_message.

Returns true if the end-of-data was sent, #false* if it was not sent (false is only possible if the connection is in nonblocking mode, and this command would block).



461
462
463
464
465
466
467
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 461

def put_copy_end(*args)
  until sync_put_copy_end(*args)
    flush
  end
  @calls_to_put_copy_data = 0
  flush
end

#reset ⇒ Object Also known as: async_reset

call-seq:

conn.reset()

Resets the backend connection. This method closes the backend connection and tries to re-connect.



503
504
505
506
507
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 503

def reset
  reset_start
  async_connect_or_reset(:reset_poll)
  self
end

#setnonblocking(enabled) ⇒ Object Also known as: async_setnonblocking

call-seq:

conn.setnonblocking(Boolean) -> nil

Sets the nonblocking status of the connection. In the blocking state, calls to #send_query will block until the message is sent to the server, but will not wait for the query results. In the nonblocking state, calls to #send_query will return an error if the socket is not ready for writing. Note: This function does not affect #exec, because that function doesn’t return until the server has processed the query and returned the results.

Returns nil.



393
394
395
396
397
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 393

def setnonblocking(enabled)
  singleton_class.async_send_api = !enabled
  self.flush_data = !enabled
  sync_setnonblocking(true)
end

#ssl_attributes ⇒ Object

call-seq:

conn.ssl_attributes -> Hash<String,String>

Returns SSL-related information about the connection as key/value pairs

The available attributes varies depending on the SSL library being used, and the type of connection.

See also #ssl_attribute



315
316
317
318
319
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 315

def ssl_attributes
  ssl_attribute_names.each.with_object({}) do |n,h|
    h[n] = ssl_attribute(n)
  end
end

#transaction ⇒ Object

call-seq:

conn.transaction { |conn| ... } -> result of the block

Executes a BEGIN at the start of the block, and a COMMIT at the end of the block, or ROLLBACK if any exception occurs.



258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/pg-1.4.5/lib/pg/connection.rb', line 258

def transaction
  rollback = false
  exec "BEGIN"
  yield(self)
rescue Exception
  rollback = true
  cancel if transaction_status == PG::PQTRANS_ACTIVE
  block
  exec "ROLLBACK"
  raise
ensure
  exec "COMMIT" unless rollback
end