# class PG::Connection

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.

### Public Class Methods

async_api=(enable) click to toggle source

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.

    # File lib/pg/connection.rb, line 1079
    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

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
Alias for: new
PG::Connection.ping(connection_hash) → Integer
PG::Connection.ping(connection_string) → Integer
PG::Connection.ping(host, port, options, tty, dbname, login, password) → Integer
Alias for: ping
async_send_api=(enable) click to toggle source

    # File lib/pg/connection.rb, line 1056
    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

PG::Connection.conndefaults() → Array click to toggle source

Returns an array of hashes. Each hash has the keys:

`:keyword`

  the name of the option

`:envvar`

  the environment variable to fall back to

`:compiled`

  the compiled in option as a secondary fallback

`:val`

  the option’s current value, or `nil` if not known

`:label`

  the label for the field

`:dispchar`

  “” for normal, “D” for debug, and “*” for password

`:dispsize`

  field size

    static VALUE
    pgconn_s_conndefaults(VALUE self)
    {
            PQconninfoOption *options = PQconndefaults();
            VALUE array = pgconn_make_conninfo_array( options );

            PQconninfoFree(options);

            UNUSED( self );

            return array;
    }

conndefaults_hash() click to toggle source

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

See also `conndefaults`

    # File lib/pg/connection.rb, line 336
    def self.conndefaults_hash
            return self.conndefaults.each_with_object({}) do |info, hash|
                    hash[ info[:keyword].to_sym ] = info[:val]
            end
    end

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
Alias for: new
connect_hash_to_string( hash ) click to toggle source

Convert Hash options to connection String

Values are properly quoted and escaped.

    # File lib/pg/connection.rb, line 43
    def self.connect_hash_to_string( hash )
            hash.map { |k,v| "#{k}=#{quote_connstr(v)}" }.join( ' ' )
    end

PG::Connection.connect_start(connection_hash) → conn click to toggle source
PG::Connection.connect_start(connection_string) → conn
PG::Connection.connect_start(host, port, options, tty, dbname, login, password) → conn

This is an asynchronous version of `PG::Connection.new`.

Use `connect_poll` to poll the status of the connection.

NOTE: this does not set the connection’s `client_encoding` for you if `Encoding.default_internal` is set. To set it after the connection is established, call `internal_encoding=`. You can also set it automatically by setting `ENV['PGCLIENTENCODING']`, or include the ‘options’ connection parameter.

See also the ‘sample’ directory of this gem and the corresponding libpq functions.

    static VALUE
    pgconn_s_connect_start( int argc, VALUE *argv, VALUE klass )
    {
            VALUE rb_conn;
            VALUE conninfo;
            t_pg_connection *this;

            /*
             * PG::Connection.connect_start must act as both alloc() and initialize()
             * because it is not invoked by calling new().
             */
            rb_conn  = pgconn_s_allocate( klass );
            this = pg_get_connection( rb_conn );
            conninfo = rb_funcall2( klass, rb_intern("parse_connect_args"), argc, argv );
            this->pgconn = gvl_PQconnectStart( StringValueCStr(conninfo) );

            if( this->pgconn == NULL )
                    rb_raise(rb_ePGerror, "PQconnectStart() unable to allocate PGconn structure");

            if ( PQstatus(this->pgconn) == CONNECTION_BAD )
                    pg_raise_conn_error( rb_eConnectionBad, rb_conn, "%s", PQerrorMessage(this->pgconn));

            if ( rb_block_given_p() ) {
                    return rb_ensure( rb_yield, rb_conn, pgconn_finish, rb_conn );
            }
            return rb_conn;
    }

PG::Connection.conninfo_parse(conninfo_string) → Array click to toggle source

Returns parsed connection options from the provided connection string as an array of hashes. Each hash has the same keys as `PG::Connection.conndefaults()` . The values from the `conninfo_string` are stored in the `:val` key.

    static VALUE
    pgconn_s_conninfo_parse(VALUE self, VALUE conninfo)
    {
            VALUE array;
            char *errmsg = NULL;
            PQconninfoOption *options = PQconninfoParse(StringValueCStr(conninfo), &errmsg);
            if(errmsg){
                    VALUE error = rb_str_new_cstr(errmsg);
                    PQfreemem(errmsg);
                    rb_raise(rb_ePGerror, "%"PRIsVALUE, error);
            }
            array = pgconn_make_conninfo_array( options );

            PQconninfoFree(options);

            UNUSED( self );

            return array;
    }

PG::Connection.encrypt_password( password, username ) → String click to toggle source

This is an older, deprecated version of `encrypt_password`. The difference is that this function always uses `md5` as the encryption algorithm.

    static VALUE
    pgconn_s_encrypt_password(VALUE self, VALUE password, VALUE username)
    {
            char *encrypted = NULL;
            VALUE rval = Qnil;

            UNUSED( self );

            Check_Type(password, T_STRING);
            Check_Type(username, T_STRING);

            encrypted = PQencryptPassword(StringValueCStr(password), StringValueCStr(username));
            rval = rb_str_new2( encrypted );
            PQfreemem( encrypted );

            return rval;
    }

escape_bytea( string ) → String click to toggle source

Escapes binary data for use within an SQL command with the type `bytea`.

Certain byte values must be escaped (but all byte values may be escaped) when used as part of a `bytea` literal in an SQL statement. In general, to escape a byte, it is converted into the three digit octal number equal to the octet value, and preceded by two backslashes. The single quote (‘) and backslash () characters have special alternative escape sequences. `escape_bytea` performs this operation, escaping only the minimally required bytes.

Consider using `exec_params`, which avoids the need for passing values inside of SQL commands.

NOTE: This class version of this method can only be used safely in client programs that use a single PostgreSQL connection at a time (in this case it can find out what it needs to know “behind the scenes”). It might give the wrong results if used in programs that use multiple database connections; use the same method on the connection object in such cases.

    static VALUE
    pgconn_s_escape_bytea(VALUE self, VALUE str)
    {
            unsigned char *from, *to;
            size_t from_len, to_len;
            VALUE ret;

            Check_Type(str, T_STRING);
            from      = (unsigned char*)RSTRING_PTR(str);
            from_len  = RSTRING_LEN(str);

            if ( rb_obj_is_kind_of(self, rb_cPGconn) ) {
                    to = PQescapeByteaConn(pg_get_pgconn(self), from, from_len, &to_len);
            } else {
                    to = PQescapeBytea( from, from_len, &to_len);
            }

            ret = rb_str_new((char*)to, to_len - 1);
            PQfreemem(to);
            return ret;
    }

escape_string( str ) → String click to toggle source

Returns a SQL-safe version of the String str. This is the preferred way to make strings safe for inclusion in SQL queries.

Consider using `exec_params`, which avoids the need for passing values inside of SQL commands.

Character encoding of escaped string will be equal to client encoding of connection.

NOTE: This class version of this method can only be used safely in client programs that use a single PostgreSQL connection at a time (in this case it can find out what it needs to know “behind the scenes”). It might give the wrong results if used in programs that use multiple database connections; use the same method on the connection object in such cases.

See also convenience functions `escape_literal` and `escape_identifier` which also add proper quotes around the string.

    static VALUE
    pgconn_s_escape(VALUE self, VALUE string)
    {
            size_t size;
            int error;
            VALUE result;
            int enc_idx;
            int singleton = !rb_obj_is_kind_of(self, rb_cPGconn);

            StringValueCStr(string);
            enc_idx = singleton ? ENCODING_GET(string) : pg_get_connection(self)->enc_idx;
            if( ENCODING_GET(string) != enc_idx ){
                    string = rb_str_export_to_enc(string, rb_enc_from_index(enc_idx));
            }

            result = rb_str_new(NULL, RSTRING_LEN(string) * 2 + 1);
            PG_ENCODING_SET_NOCHECK(result, enc_idx);
            if( !singleton ) {
                    size = PQescapeStringConn(pg_get_pgconn(self), RSTRING_PTR(result),
                            RSTRING_PTR(string), RSTRING_LEN(string), &error);
                    if(error)
                            pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(pg_get_pgconn(self)));

            } else {
                    size = PQescapeString(RSTRING_PTR(result), RSTRING_PTR(string), RSTRING_LEN(string));
            }
            rb_str_set_len(result, size);

            return result;
    }

PG::Connection.new → conn click to toggle source
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

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.

### 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:pass@pgsql.example.com:5432/testdb?sslmode=require" )

### Specifying Multiple Hosts¶ ↑

It is possible to specify multiple hosts to connect to, so that they are tried in the given order or optionally in random order. In the Keyword/Value format, the host, hostaddr, and port options accept comma-separated lists of values. The details to libpq describe how it works, but there are two small differences how ruby-pg handles multiple hosts:

- All hosts are resolved before the first connection is tried. This means that when `load_balance_hosts` is set to `random`, then all resolved addresses are tried randomly in one level. When a host resolves to more than one address, it is therefore tried more often than a host that has only one address.

- When a timeout occurs due to the value of `connect_timeout`, then the given `host`, `hostaddr` and `port` combination is not tried a second time, even if it’s specified several times. It’s still possible to do load balancing with `load_balance_hosts` set to `random` and to increase the number of connections a node gets, when the hostname is provided multiple times in the host string. This is because in non-timeout cases the host is tried multiple times.

    # File lib/pg/connection.rb, line 869
    def new(*args)
            conn = connect_to_hosts(*args)

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

Also aliased as: async_connect, connect, open, setdb, setdblogin
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
Alias for: new
parse_connect_args( *args ) click to toggle source

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 {host: “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.

    # File lib/pg/connection.rb, line 63
    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.to_s
                    when /=/, /:\/\//
                            # 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] = PROGRAM_NAME.sub( /^(.{30}).{4,}(.{30})$/ ){ $1+"..."+$2 }
            end

            return connect_hash_to_string(iopts)
    end

PG::Connection.ping(connection_hash) → Integer click to toggle source
PG::Connection.ping(connection_string) → Integer
PG::Connection.ping(host, port, options, tty, dbname, login, password) → Integer

PQpingParams reports the status of the server.

It accepts connection parameters identical to those of PQ::Connection.new . It is not necessary to supply correct user name, password, or database name values to obtain the server status; however, if incorrect values are provided, the server will log a failed connection attempt.

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)

See also `check_socket` for a way to check the connection without doing any server communication.

    # File lib/pg/connection.rb, line 984
    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

Also aliased as: async_ping
quote_connstr( value ) click to toggle source

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

    # File lib/pg/connection.rb, line 36
    def self.quote_connstr( value )
            return "'" + value.to_s.gsub( /[\\']/ ) {|m| '\\' + m } + "'"
    end

quote_ident( str ) → String click to toggle source
quote_ident( array ) → String
PG::Connection.quote_ident( str ) → String
PG::Connection.quote_ident( array ) → String

Returns a string that is safe for inclusion in a SQL query as an identifier. Note: this is not a quote function for values, but for identifiers.

For example, in a typical SQL query: `SELECT FOO FROM MYTABLE` The identifier `FOO` is folded to lower case, so it actually means `foo`. If you really want to access the case-sensitive field name `FOO`, use this function like `conn.quote_ident('FOO')`, which will return `"FOO"` (with double-quotes). PostgreSQL will see the double-quotes, and it will not fold to lower case.

Similarly, this function also protects against special characters, and other things that might allow SQL injection if the identifier comes from an untrusted source.

If the parameter is an Array, then all it’s values are separately quoted and then joined by a “.” character. This can be used for identifiers in the form “schema”.“table”.“column” .

This method is functional identical to the encoder `PG::TextEncoder::Identifier` .

If the instance method form is used and the input string character encoding is different to the connection encoding, then the string is converted to this encoding, so that the returned string is always encoded as `PG::Connection#internal_encoding` .

In the singleton form (`PG::Connection.quote_ident`) the character encoding of the result string is set to the character encoding of the input string.

    static VALUE
    pgconn_s_quote_ident(VALUE self, VALUE str_or_array)
    {
            VALUE ret;
            int enc_idx;

            if( rb_obj_is_kind_of(self, rb_cPGconn) ){
                    enc_idx = pg_get_connection(self)->enc_idx;
            }else{
                    enc_idx = RB_TYPE_P(str_or_array, T_STRING) ? ENCODING_GET( str_or_array ) : rb_ascii8bit_encindex();
            }
            pg_text_enc_identifier(NULL, str_or_array, NULL, &ret, enc_idx);

            return ret;
    }

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
Alias for: new
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
Alias for: new
sync_connect(*args) click to toggle source

    static VALUE
    pgconn_s_sync_connect(int argc, VALUE *argv, VALUE klass)
    {
            t_pg_connection *this;
            VALUE conninfo;
            VALUE self = pgconn_s_allocate( klass );

            this = pg_get_connection( self );
            conninfo = rb_funcall2( rb_cPGconn, rb_intern("parse_connect_args"), argc, argv );
            this->pgconn = gvl_PQconnectdb(StringValueCStr(conninfo));

            if(this->pgconn == NULL)
                    rb_raise(rb_ePGerror, "PQconnectdb() unable to allocate PGconn structure");

            if (PQstatus(this->pgconn) == CONNECTION_BAD)
                    pg_raise_conn_error( rb_eConnectionBad, self, "%s", PQerrorMessage(this->pgconn));

            pgconn_set_default_encoding( self );

            if (rb_block_given_p()) {
                    return rb_ensure(rb_yield, self, pgconn_finish, self);
            }
            return self;
    }

sync_ping(*args) click to toggle source

    static VALUE
    pgconn_s_sync_ping( int argc, VALUE *argv, VALUE klass )
    {
            PGPing ping;
            VALUE conninfo;

            conninfo = rb_funcall2( klass, rb_intern("parse_connect_args"), argc, argv );
            ping     = gvl_PQping( StringValueCStr(conninfo) );

            return INT2FIX((int)ping);
    }

PG::Connection.unescape_bytea( string ) click to toggle source

Converts an escaped string representation of binary data into binary data — the reverse of `escape_bytea`. This is needed when retrieving `bytea` data in text format, but not when retrieving it in binary format.

    static VALUE
    pgconn_s_unescape_bytea(VALUE self, VALUE str)
    {
            unsigned char *from, *to;
            size_t to_len;
            VALUE ret;

            UNUSED( self );

            Check_Type(str, T_STRING);
            from = (unsigned char*)StringValueCStr(str);

            to = PQunescapeBytea(from, &to_len);

            ret = rb_str_new((char*)to, to_len);
            PQfreemem(to);
            return ret;
    }

### Public Instance Methods

async_cancel
Alias for: cancel
async_close_portal
Alias for: close_portal
async_close_prepared
Alias for: close_prepared
async_describe_portal
Alias for: describe_portal
async_describe_prepared
Alias for: describe_prepared
async_encrypt_password
Alias for: encrypt_password
async_exec
Also aliased as: async_query
Alias for: exec
async_exec_params
Alias for: exec_params
async_exec_prepared
Alias for: exec_prepared
async_flush
Alias for: flush
async_get_copy_data
Alias for: get_copy_data
async_get_last_result
Alias for: get_last_result
async_get_result
Alias for: get_result
async_isnonblocking
Alias for: isnonblocking
pipeline_sync
Alias for: pipeline_sync
async_prepare
Alias for: prepare
async_put_copy_data
Alias for: put_copy_data
async_put_copy_end
Alias for: put_copy_end
async_query(*args)

Sends SQL query request specified by sql to PostgreSQL. On success, it returns a `PG::Result` instance with all result rows and columns. On failure, it raises a `PG::Error`.

For backward compatibility, if you pass more than one parameter to this method, it will call `exec_params` for you. New code should explicitly use `exec_params` if argument placeholders are used.

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.

`exec` is an alias for `async_exec` which is almost identical to `sync_exec` . `sync_exec` is implemented on the simpler synchronous command processing API of libpq, whereas `async_exec` is implemented on the asynchronous API and on ruby’s IO mechanisms. Only `async_exec` is compatible to `Fiber.scheduler` based asynchronous IO processing introduced in ruby-3.0. Both methods ensure that other threads can process while waiting for the server to complete the request, but `sync_exec` blocks all signals to be processed until the query is finished. This is most notably visible by a delayed reaction to Control+C. It’s not recommended to use explicit sync or async variants but `exec` instead, unless you have a good reason to do so.

See also corresponding libpq function.

Alias for: async_exec
async_reset
Alias for: reset
async_set_client_encoding
Alias for: set_client_encoding
async_setnonblocking
Alias for: setnonblocking
backend_key() → Integer click to toggle source

Returns the key of the backend server process for this connection. This key can be used to cancel queries on the server.

    static VALUE
    pgconn_backend_key(VALUE self)
    {
            int be_key;
            struct pg_cancel *cancel;
            PGconn *conn = pg_get_pgconn(self);

            cancel = (struct pg_cancel*)PQgetCancel(conn);
            if(cancel == NULL)
                    pg_raise_conn_error( rb_ePGerror, self, "Invalid connection!");

            if( cancel->be_pid != PQbackendPID(conn) )
                    rb_raise(rb_ePGerror,"Unexpected binary struct layout - please file a bug report at ruby-pg!");

            be_key = cancel->be_key;

            PQfreeCancel(cancel);

            return INT2NUM(be_key);
    }

backend_pid() → Integer click to toggle source

Returns the process ID of the backend server process for this connection. Note that this is a PID on database server host.

    static VALUE
    pgconn_backend_pid(VALUE self)
    {
            return INT2NUM(PQbackendPID(pg_get_pgconn(self)));
    }

block( [ timeout ] ) → Boolean click to toggle source

Blocks until the server is no longer busy, or until the optional timeout is reached, whichever comes first. timeout is measured in seconds and can be fractional.

Returns `false` if timeout is reached, `true` otherwise.

If `true` is returned, `conn.is_busy` will return `false` and `conn.get_result` will not block.

    VALUE
    pgconn_block( int argc, VALUE *argv, VALUE self ) {
            struct timeval timeout;
            struct timeval *ptimeout = NULL;
            VALUE timeout_in;
            double timeout_sec;
            void *ret;

            if ( rb_scan_args(argc, argv, "01", &timeout_in) == 1 ) {
                    timeout_sec = NUM2DBL( timeout_in );
                    timeout.tv_sec = (time_t)timeout_sec;
                    timeout.tv_usec = (suseconds_t)((timeout_sec - (long)timeout_sec) * 1e6);
                    ptimeout = &timeout;
            }

            ret = wait_socket_readable( self, ptimeout, get_result_readable);

            if( !ret )
                    return Qfalse;

            return Qtrue;
    }

cancel() → String click to toggle source

Requests cancellation of the command currently being processed.

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

On PostgreSQL-17+ client libaray the class `PG::CancelConnection` is used. On older client library a pure ruby implementation is used.

    # File lib/pg/connection.rb, line 625
    def cancel
            cancon = PG::CancelConnection.new(self)
            cancon.async_cancel
    rescue PG::Error => err
            err.to_s
    end

Also aliased as: async_cancel
check_socket() click to toggle source

Read all pending socket input to internal memory and raise an exception in case of errors.

This verifies that the connection socket is in a usable state and not aborted in any way. No communication is done with the server. Only pending data is read from the socket - the method doesn’t wait for any outstanding server answers.

Raises a kind of `PG::Error` if there was an error reading the data or if the socket is in a failure state.

The method doesn’t verify that the server is still responding. To verify that the communication to the server works, it is recommended to use something like `conn.exec('')` instead.

    # File lib/pg/connection.rb, line 383
    def check_socket
            while socket_io.wait_readable(0)
                    consume_input
            end
            nil
    end

client_encoding=
Alias for: set_client_encoding
finish

Closes the backend connection.

Alias for: finish
close_portal( portal_name ) → PG::Result click to toggle source

Submits a request to close the specified portal, and waits for completion.

`close_portal` allows an application to trigger a close of a previously created portal. Closing a portal releases all of its associated resources on the server and allows its name to be reused. (pg does not provide any direct access to portals, but you can use this function to close a cursor created with a DECLARE CURSOR SQL command.)

`portal_name` can be “” or `nil` to reference the unnamed portal. It is fine if no portal exists with this name, in that case the operation is a no-op. On success, a `PG::Result` with status PGRES_COMMAND_OK is returned.

See also corresponding libpq function.

Available since PostgreSQL-17.

    static VALUE
    pgconn_async_close_portal(VALUE self, VALUE portal)
    {
            return pgconn_async_describe_close_prepared_potral(self, portal, pgconn_send_close_portal);
    }

Also aliased as: async_close_portal
close_prepared( statement_name ) → PG::Result click to toggle source

Submits a request to close the specified prepared statement, and waits for completion. `close_prepared` allows an application to close a previously prepared statement. Closing a statement releases all of its associated resources on the server and allows its name to be reused. It’s the same as using the `DEALLOCATE` SQL statement, but on a lower protocol level.

`statement_name` can be “” or `nil` to reference the unnamed statement. It is fine if no statement exists with this name, in that case the operation is a no-op. On success, a `PG::Result` with status PGRES_COMMAND_OK is returned.

See also corresponding libpq function.

Available since PostgreSQL-17.

    static VALUE
    pgconn_async_close_prepared(VALUE self, VALUE stmt_name)
    {
            return pgconn_async_describe_close_prepared_potral(self, stmt_name, pgconn_send_close_prepared);
    }

Also aliased as: async_close_prepared
conndefaults() click to toggle source

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

    # File lib/pg/connection.rb, line 328
    def conndefaults
            return self.class.conndefaults
    end

conndefaults_hash() click to toggle source

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

    # File lib/pg/connection.rb, line 344
    def conndefaults_hash
            return self.class.conndefaults_hash
    end

connect_poll() → Integer click to toggle source

Returns one of:

`PGRES_POLLING_READING`

  wait until the socket is ready to read

`PGRES_POLLING_WRITING`

  wait until the socket is ready to write

`PGRES_POLLING_FAILED`

  the asynchronous connection has failed

`PGRES_POLLING_OK`

  the asynchronous connection is ready

Example:

    require "io/wait"

    conn = PG::Connection.connect_start(dbname: 'mydatabase')
    status = conn.connect_poll
    while(status != PG::PGRES_POLLING_OK) do
      # do some work while waiting for the connection to complete
      if(status == PG::PGRES_POLLING_READING)
        unless conn.socket_io.wait_readable(10.0)
          raise "Asynchronous connection timed out!"
        end
      elsif(status == PG::PGRES_POLLING_WRITING)
        unless conn.socket_io.wait_writable(10.0)
          raise "Asynchronous connection timed out!"
        end
      end
      status = conn.connect_poll
    end
    # now conn.status == CONNECTION_OK, and connection
    # is ready.

    static VALUE
    pgconn_connect_poll(VALUE self)
    {
            PostgresPollingStatusType status;

            pgconn_close_socket_io(self);
            status = gvl_PQconnectPoll(pg_get_pgconn(self));

            return INT2FIX((int)status);
    }

connection_needs_password() → Boolean click to toggle source

Returns `true` if the authentication method required a password, but none was available. `false` otherwise.

    static VALUE
    pgconn_connection_needs_password(VALUE self)
    {
            return PQconnectionNeedsPassword(pg_get_pgconn(self)) ? Qtrue : Qfalse;
    }

connection_used_password() → Boolean click to toggle source

Returns `true` if the authentication method used a caller-supplied password, `false` otherwise.

    static VALUE
    pgconn_connection_used_password(VALUE self)
    {
            return PQconnectionUsedPassword(pg_get_pgconn(self)) ? Qtrue : Qfalse;
    }

conninfo → hash click to toggle source

Returns the connection options used by a live connection.

    static VALUE
    pgconn_conninfo( VALUE self )
    {
            PGconn *conn = pg_get_pgconn(self);
            PQconninfoOption *options = PQconninfo( conn );
            VALUE array = pgconn_make_conninfo_array( options );

            PQconninfoFree(options);

            return array;
    }

conninfo_hash() click to toggle source

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

See also `conninfo`

    # File lib/pg/connection.rb, line 352
    def conninfo_hash
            return self.conninfo.each_with_object({}) do |info, hash|
                    hash[ info[:keyword].to_sym ] = info[:val]
            end
    end

consume_input() click to toggle source

If input is available from the server, consume it. After calling `consume_input`, you can check `is_busy` or notifies to see if the state has changed.

    static VALUE
    pgconn_consume_input(VALUE self)
    {
            PGconn *conn = pg_get_pgconn(self);
            /* returns 0 on error */
            if(PQconsumeInput(conn) == 0) {
                    pgconn_close_socket_io(self);
                    pg_raise_conn_error( rb_eConnectionBad, self, "%s", PQerrorMessage(conn));
            }

            return Qnil;
    }

copy_data( sql [, coder] ) {|sql_result| ... } → PG::Result click to toggle source

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

All 4 CopyRow classes can take a type map to specify how the columns are mapped to and from the database format. For details see the particular CopyRow class description.

`PG::BinaryEncoder::CopyRow` can be used to send data in binary format to the server. In this case `copy_data` generates the header and trailer data automatically:

    enco = PG::BinaryEncoder::CopyRow.new
    conn.copy_data "COPY my_table FROM STDIN (FORMAT binary)", 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"]

Also `PG::BinaryDecoder::CopyRow` can be used to retrieve data in binary format from the server. In this case the header and trailer data is processed by the decoder and the remaining `nil` from `get_copy_data` is processed by `copy_data`, so that binary data can be processed equally to text data:

    deco = PG::BinaryDecoder::CopyRow.new
    conn.copy_data "COPY my_table TO STDOUT (FORMAT binary)", 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"]

    # File lib/pg/connection.rb, line 213
    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 && res.binary_tuples == 1
                                    # Binary file header (11 byte signature, 32 bit flags and 32 bit extension length)
                                    put_copy_data(BinarySignature + ("\x00" * 8))
                            end

                            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 ]
                            begin
                                    put_copy_end( errmsg )
                            rescue PG::Error
                                    # Ignore error in cleanup to avoid losing original exception
                            end
                            discard_results
                            raise err
                    else
                            begin
                                    self.encoder_for_put_copy_data = old_coder if coder

                                    if coder && res.binary_tuples == 1
                                            put_copy_data("\xFF\xFF") # Binary file trailer 16 bit "-1"
                                    end

                                    put_copy_end
                            rescue PG::Error => err
                                    raise PG::LostCopyState.new("#{err} (probably by executing another SQL query while running a COPY command)", connection: self)
                            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
                            cancel
                            discard_results
                            raise
                    else
                            if coder && res.binary_tuples == 1
                                    # There are two end markers in binary mode: file trailer and the final nil.
                                    # The file trailer is expected to be processed by BinaryDecoder::CopyRow and already returns nil, so that the remaining NULL from PQgetCopyData is retrieved here:
                                    if get_copy_data
                                            discard_results
                                            raise PG::NotAllCopyDataRetrieved.new("Not all binary COPY data retrieved", connection: self)
                                    end
                            end
                            res = get_last_result
                            if !res
                                    discard_results
                                    raise PG::LostCopyState.new("Lost COPY state (probably by executing another SQL query while running a COPY command)", connection: self)
                            elsif res.result_status != PGRES_COMMAND_OK
                                    discard_results
                                    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

db() click to toggle source

Returns the connected database name.

    static VALUE
    pgconn_db(VALUE self)
    {
            char *db = PQdb(pg_get_pgconn(self));
            if (!db) return Qnil;
            return rb_str_new2(db);
    }

decoder_for_get_copy_data → PG::Coder click to toggle source

Returns the default coder object that is currently set for type casting of received data by `get_copy_data` .

Returns either:

- a kind of `PG::Coder`

- `nil` - type encoding is disabled, returned data will be a String.

Default is `nil` .

See also `decoder_for_get_copy_data=`

    static VALUE
    pgconn_decoder_for_get_copy_data_get(VALUE self)
    {
            t_pg_connection *this = pg_get_connection( self );

            return this->decoder_for_get_copy_data;
    }

decoder_for_get_copy_data = decoder click to toggle source

Set the default coder that is used for type casting of received data by `get_copy_data` . It can be overwritten per `decoder` parameter of `get_copy_data` and `coder` parameter of `copy_data`.

`decoder` can be:

- a kind of `PG::Coder`

- `nil` - disable type decoding, returned data will be a String.

See also `decoder_for_get_copy_data`

    static VALUE
    pgconn_decoder_for_get_copy_data_set(VALUE self, VALUE decoder)
    {
            t_pg_connection *this = pg_get_connection( self );

            rb_check_frozen(self);
            if( decoder != Qnil ){
                    t_pg_coder *co;
                    UNUSED(co);
                    /* Check argument type */
                    TypedData_Get_Struct(decoder, t_pg_coder, &pg_coder_type, co);
            }
            RB_OBJ_WRITE(self, &this->decoder_for_get_copy_data, decoder);

            return decoder;
    }

describe_portal( portal_name ) → PG::Result click to toggle source

Retrieve information about the portal portal_name.

See also corresponding libpq function.

    static VALUE
    pgconn_async_describe_portal(VALUE self, VALUE portal)
    {
            return pgconn_async_describe_close_prepared_potral(self, portal, pgconn_send_describe_portal);
    }

Also aliased as: async_describe_portal
describe_prepared( statement_name ) → PG::Result click to toggle source

Retrieve information about the prepared statement statement_name.

See also corresponding libpq function.

    static VALUE
    pgconn_async_describe_prepared(VALUE self, VALUE stmt_name)
    {
            return pgconn_async_describe_close_prepared_potral(self, stmt_name, pgconn_send_describe_prepared);
    }

Also aliased as: async_describe_prepared
discard_results() click to toggle source

Silently discard any prior query result that application didn’t eat. This is internally used prior to `Connection#exec` and sibling methods. It doesn’t raise an exception on connection errors, but returns `false` instead.

Returns:

- `nil` when the connection is already idle

- `true` when some results have been discarded

- `false` when a failure occurred and the connection was closed

    static VALUE
    pgconn_discard_results(VALUE self)
    {
            PGconn *conn = pg_get_pgconn(self);
            VALUE socket_io;

            switch( PQtransactionStatus(conn) ) {
                    case PQTRANS_IDLE:
                    case PQTRANS_INTRANS:
                    case PQTRANS_INERROR:
                            return Qnil;
                    default:;
            }

            socket_io = pgconn_socket_io(self);

            for(;;) {
                    PGresult *cur;
                    int status;

                    /* pgconn_block() raises an exception in case of errors.
                    * To avoid this call pg_rb_io_wait() and PQconsumeInput() without rb_raise().
                    */
                    while( gvl_PQisBusy(conn) ){
                            int events;

                            switch( PQflush(conn) ) {
                                    case 1:
                                            events = RB_NUM2INT(pg_rb_io_wait(socket_io, RB_INT2NUM(PG_RUBY_IO_READABLE | PG_RUBY_IO_WRITABLE), Qnil));
                                            if (events & PG_RUBY_IO_READABLE){
                                                    if ( PQconsumeInput(conn) == 0 ) goto error;
                                            }
                                            break;
                                    case 0:
                                            pg_rb_io_wait(socket_io, RB_INT2NUM(PG_RUBY_IO_READABLE), Qnil);
                                            if ( PQconsumeInput(conn) == 0 ) goto error;
                                            break;
                                    default:
                                            goto error;
                            }
                    }

                    cur = gvl_PQgetResult(conn);
                    if( cur == NULL) break;

                    status = PQresultStatus(cur);
                    PQclear(cur);
                    if (status == PGRES_COPY_IN){
                            while( gvl_PQputCopyEnd(conn, "COPY terminated by new query or discard_results") == 0 ){
                                    pgconn_async_flush(self);
                            }
                    }
                    if (status == PGRES_COPY_OUT){
                            for(;;) {
                                    char *buffer = NULL;
                                    int st = gvl_PQgetCopyData(conn, &buffer, 1);
                                    if( st == 0 ) {
                                            /* would block -> wait for readable data */
                                            pg_rb_io_wait(socket_io, RB_INT2NUM(PG_RUBY_IO_READABLE), Qnil);
                                            if ( PQconsumeInput(conn) == 0 ) goto error;
                                    } else if( st > 0 ) {
                                            /* some data retrieved -> discard it */
                                            PQfreemem(buffer);
                                    } else {
                                            /* no more data */
                                            break;
                                    }
                            }
                    }
            }

            return Qtrue;

    error:
            pgconn_close_socket_io(self);
            return Qfalse;
    }

encoder_for_put_copy_data → PG::Coder click to toggle source

Returns the default coder object that is currently set for type casting of parameters to `put_copy_data` .

Returns either:

- a kind of `PG::Coder`

- `nil` - type encoding is disabled, data must be a String.

Default is `nil` . See also `encoder_for_put_copy_data=`

    static VALUE
    pgconn_encoder_for_put_copy_data_get(VALUE self)
    {
            t_pg_connection *this = pg_get_connection( self );

            return this->encoder_for_put_copy_data;
    }

encoder_for_put_copy_data = encoder click to toggle source

Set the default coder that is used for type casting of parameters to `put_copy_data` . It can be overwritten per `encoder` parameter of `put_copy_data` and `coder` parameter of `copy_data`.

`encoder` can be:

- a kind of `PG::Coder`

- `nil` - disable type encoding, data must be a String.

See also `encoder_for_put_copy_data`

    static VALUE
    pgconn_encoder_for_put_copy_data_set(VALUE self, VALUE encoder)
    {
            t_pg_connection *this = pg_get_connection( self );

            rb_check_frozen(self);
            if( encoder != Qnil ){
                    t_pg_coder *co;
                    UNUSED(co);
                    /* Check argument type */
                    TypedData_Get_Struct(encoder, t_pg_coder, &pg_coder_type, co);
            }
            RB_OBJ_WRITE(self, &this->encoder_for_put_copy_data, encoder);

            return encoder;
    }

encrypt_password( password, username, algorithm=nil ) → String click to toggle source

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.

    # File lib/pg/connection.rb, line 578
    def encrypt_password( password, username, algorithm=nil )
            algorithm ||= exec("SHOW password_encryption").getvalue(0,0)
            sync_encrypt_password(password, username, algorithm)
    end

Also aliased as: async_encrypt_password
enter_pipeline_mode → nil click to toggle source

Causes a connection to enter pipeline mode if it is currently idle or already in pipeline mode.

Raises `PG::Error` and has no effect if the connection is not currently idle, i.e., it has a result ready, or it is waiting for more input from the server, etc. This function does not actually send anything to the server, it just changes the libpq connection state.

See the PostgreSQL documentation.

Available since PostgreSQL-14

    static VALUE
    pgconn_enter_pipeline_mode(VALUE self)
    {
            PGconn *conn = pg_get_pgconn(self);
            int res = PQenterPipelineMode(conn);
            if( res != 1 )
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(conn));

            return Qnil;
    }

error_message → String click to toggle source

Returns the error message most recently generated by an operation on the connection.

Nearly all libpq functions will set a message for conn.error_message if they fail. Note that by libpq convention, a nonempty `error_message` result can consist of multiple lines, and will include a trailing newline.

    static VALUE
    pgconn_error_message(VALUE self)
    {
            char *error = PQerrorMessage(pg_get_pgconn(self));
            if (!error) return Qnil;
            return rb_str_new2(error);
    }

escape
Alias for: escape_string
escape_bytea( string ) → String click to toggle source

Escapes binary data for use within an SQL command with the type `bytea`.

Certain byte values must be escaped (but all byte values may be escaped) when used as part of a `bytea` literal in an SQL statement. In general, to escape a byte, it is converted into the three digit octal number equal to the octet value, and preceded by two backslashes. The single quote (‘) and backslash () characters have special alternative escape sequences. `escape_bytea` performs this operation, escaping only the minimally required bytes.

Consider using `exec_params`, which avoids the need for passing values inside of SQL commands.

NOTE: This class version of this method can only be used safely in client programs that use a single PostgreSQL connection at a time (in this case it can find out what it needs to know “behind the scenes”). It might give the wrong results if used in programs that use multiple database connections; use the same method on the connection object in such cases.

    static VALUE
    pgconn_s_escape_bytea(VALUE self, VALUE str)
    {
            unsigned char *from, *to;
            size_t from_len, to_len;
            VALUE ret;

            Check_Type(str, T_STRING);
            from      = (unsigned char*)RSTRING_PTR(str);
            from_len  = RSTRING_LEN(str);

            if ( rb_obj_is_kind_of(self, rb_cPGconn) ) {
                    to = PQescapeByteaConn(pg_get_pgconn(self), from, from_len, &to_len);
            } else {
                    to = PQescapeBytea( from, from_len, &to_len);
            }

            ret = rb_str_new((char*)to, to_len - 1);
            PQfreemem(to);
            return ret;
    }

Also aliased as: escape_bytea
escape_identifier( str ) → String click to toggle source

Escape an arbitrary String `str` as an identifier.

This method does the same as `quote_ident` with a String argument, but it doesn’t support an Array argument and it makes use of libpq to process the string.

    static VALUE
    pgconn_escape_identifier(VALUE self, VALUE string)
    {
            t_pg_connection *this = pg_get_connection_safe( self );
            char *escaped = NULL;
            VALUE result = Qnil;
            int enc_idx = this->enc_idx;

            StringValueCStr(string);
            if( ENCODING_GET(string) != enc_idx ){
                    string = rb_str_export_to_enc(string, rb_enc_from_index(enc_idx));
            }

            escaped = PQescapeIdentifier(this->pgconn, RSTRING_PTR(string), RSTRING_LEN(string));
            if (escaped == NULL)
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(this->pgconn));

            result = rb_str_new2(escaped);
            PQfreemem(escaped);
            PG_ENCODING_SET_NOCHECK(result, enc_idx);

            return result;
    }

escape_literal( str ) → String click to toggle source

Escape an arbitrary String `str` as a literal.

See also `PG::TextEncoder::QuotedLiteral` for a type cast integrated version of this function.

    static VALUE
    pgconn_escape_literal(VALUE self, VALUE string)
    {
            t_pg_connection *this = pg_get_connection_safe( self );
            char *escaped = NULL;
            VALUE result = Qnil;
            int enc_idx = this->enc_idx;

            StringValueCStr(string);
            if( ENCODING_GET(string) != enc_idx ){
                    string = rb_str_export_to_enc(string, rb_enc_from_index(enc_idx));
            }

            escaped = PQescapeLiteral(this->pgconn, RSTRING_PTR(string), RSTRING_LEN(string));
            if (escaped == NULL)
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(this->pgconn));

            result = rb_str_new2(escaped);
            PQfreemem(escaped);
            PG_ENCODING_SET_NOCHECK(result, enc_idx);

            return result;
    }

escape_string( str ) → String click to toggle source

Returns a SQL-safe version of the String str. This is the preferred way to make strings safe for inclusion in SQL queries.

Consider using `exec_params`, which avoids the need for passing values inside of SQL commands.

Character encoding of escaped string will be equal to client encoding of connection.

NOTE: This class version of this method can only be used safely in client programs that use a single PostgreSQL connection at a time (in this case it can find out what it needs to know “behind the scenes”). It might give the wrong results if used in programs that use multiple database connections; use the same method on the connection object in such cases.

See also convenience functions `escape_literal` and `escape_identifier` which also add proper quotes around the string.

    static VALUE
    pgconn_s_escape(VALUE self, VALUE string)
    {
            size_t size;
            int error;
            VALUE result;
            int enc_idx;
            int singleton = !rb_obj_is_kind_of(self, rb_cPGconn);

            StringValueCStr(string);
            enc_idx = singleton ? ENCODING_GET(string) : pg_get_connection(self)->enc_idx;
            if( ENCODING_GET(string) != enc_idx ){
                    string = rb_str_export_to_enc(string, rb_enc_from_index(enc_idx));
            }

            result = rb_str_new(NULL, RSTRING_LEN(string) * 2 + 1);
            PG_ENCODING_SET_NOCHECK(result, enc_idx);
            if( !singleton ) {
                    size = PQescapeStringConn(pg_get_pgconn(self), RSTRING_PTR(result),
                            RSTRING_PTR(string), RSTRING_LEN(string), &error);
                    if(error)
                            pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(pg_get_pgconn(self)));

            } else {
                    size = PQescapeString(RSTRING_PTR(result), RSTRING_PTR(string), RSTRING_LEN(string));
            }
            rb_str_set_len(result, size);

            return result;
    }

Also aliased as: escape_string, escape
exec(sql) → PG::Result click to toggle source
exec(sql) {|pg_result| block }

Sends SQL query request specified by sql to PostgreSQL. On success, it returns a `PG::Result` instance with all result rows and columns. On failure, it raises a `PG::Error`.

For backward compatibility, if you pass more than one parameter to this method, it will call `exec_params` for you. New code should explicitly use `exec_params` if argument placeholders are used.

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.

`exec` is an alias for `async_exec` which is almost identical to `sync_exec` . `sync_exec` is implemented on the simpler synchronous command processing API of libpq, whereas `async_exec` is implemented on the asynchronous API and on ruby’s IO mechanisms. Only `async_exec` is compatible to `Fiber.scheduler` based asynchronous IO processing introduced in ruby-3.0. Both methods ensure that other threads can process while waiting for the server to complete the request, but `sync_exec` blocks all signals to be processed until the query is finished. This is most notably visible by a delayed reaction to Control+C. It’s not recommended to use explicit sync or async variants but `exec` instead, unless you have a good reason to do so.

See also corresponding libpq function.

    static VALUE
    pgconn_async_exec(int argc, VALUE *argv, VALUE self)
    {
            VALUE rb_pgresult = Qnil;

            pgconn_discard_results( self );
            pgconn_send_query( argc, argv, self );
            rb_pgresult = pgconn_async_get_last_result( self );

            if ( rb_block_given_p() ) {
                    return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
            }
            return rb_pgresult;
    }

Also aliased as: async_exec
exec_params(sql, params [, result_format [, type_map ]] ) → nil click to toggle source
exec_params(sql, params [, result_format [, type_map ]] ) {|pg_result| block }

Sends SQL query request specified by `sql` to PostgreSQL using placeholders for parameters.

Returns a `PG::Result` instance on success. On failure, it raises a `PG::Error`.

`params` is an array of the bind parameters for the SQL query. Each element of the `params` array may be either:

    a hash of the form:
      {:value  => String (value of bind parameter)
       :type   => Integer (oid of type of bind parameter)
       :format => Integer (0 for text, 1 for binary)
      }
    or, it may be a String. If it is a string, that is equivalent to the hash:
      { :value => <string value>, :type => 0, :format => 0 }

PostgreSQL bind parameters are represented as $1, $2, $3, etc., inside the SQL query. The 0th element of the `params` array is bound to $1, the 1st element is bound to $2, etc. `nil` is treated as `NULL`.

If the types are not specified, they will be inferred by PostgreSQL. Instead of specifying type oids, it’s recommended to simply add explicit casts in the query to ensure that the right type is used.

For example: “SELECT $1::int”

The optional `result_format` should be 0 for text results, 1 for binary.

`type_map` can be a `PG::TypeMap` derivation (such as `PG::BasicTypeMapForQueries`). This will type cast the params from various Ruby types before transmission based on the encoders defined by the type map. When a type encoder is used the format and oid of a given bind parameter are retrieved from the encoder instead out of the hash form described above.

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.

The primary advantage of `exec_params` over `exec` is that parameter values can be separated from the command string, thus avoiding the need for tedious and error-prone quoting and escaping. Unlike `exec`, `exec_params` allows at most one SQL command in the given string. (There can be semicolons in it, but not more than one nonempty command.) This is a limitation of the underlying protocol, but has some usefulness as an extra defense against SQL-injection attacks.

See also corresponding libpq function.

    static VALUE
    pgconn_async_exec_params(int argc, VALUE *argv, VALUE self)
    {
            VALUE rb_pgresult = Qnil;

            pgconn_discard_results( self );
            /* If called with no or nil parameters, use PQsendQuery for compatibility */
            if ( argc == 1 || (argc >= 2 && argc <= 4 && NIL_P(argv[1]) )) {
                    pg_deprecated(3, ("forwarding async_exec_params to async_exec is deprecated"));
                    pgconn_send_query( argc, argv, self );
            } else {
                    pgconn_send_query_params( argc, argv, self );
            }
            rb_pgresult = pgconn_async_get_last_result( self );

            if ( rb_block_given_p() ) {
                    return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
            }
            return rb_pgresult;
    }

Also aliased as: async_exec_params
exec_prepared(statement_name [, params, result_format[, type_map]] ) → PG::Result click to toggle source
exec_prepared(statement_name [, params, result_format[, type_map]] ) {|pg_result| block }

Execute prepared named statement specified by statement_name. Returns a `PG::Result` instance on success. On failure, it raises a `PG::Error`.

`params` is an array of the optional bind parameters for the SQL query. Each element of the `params` array may be either:

    a hash of the form:
      {:value  => String (value of bind parameter)
       :format => Integer (0 for text, 1 for binary)
      }
    or, it may be a String. If it is a string, that is equivalent to the hash:
      { :value => <string value>, :format => 0 }

PostgreSQL bind parameters are represented as $1, $2, $3, etc., inside the SQL query. The 0th element of the `params` array is bound to $1, the 1st element is bound to $2, etc. `nil` is treated as `NULL`.

The optional `result_format` should be 0 for text results, 1 for binary.

`type_map` can be a `PG::TypeMap` derivation (such as `PG::BasicTypeMapForQueries`). This will type cast the params from various Ruby types before transmission based on the encoders defined by the type map. When a type encoder is used the format and oid of a given bind parameter are retrieved from the encoder instead out of the hash form described above.

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_prepared` returns the value of the block.

See also corresponding libpq function.

    static VALUE
    pgconn_async_exec_prepared(int argc, VALUE *argv, VALUE self)
    {
            VALUE rb_pgresult = Qnil;

            pgconn_discard_results( self );
            pgconn_send_query_prepared( argc, argv, self );
            rb_pgresult = pgconn_async_get_last_result( self );

            if ( rb_block_given_p() ) {
                    return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
            }
            return rb_pgresult;
    }

Also aliased as: async_exec_prepared
exit_pipeline_mode → nil click to toggle source

Causes a connection to exit pipeline mode if it is currently in pipeline mode with an empty queue and no pending results.

Takes no action if not in pipeline mode. Raises `PG::Error` if the current statement isn’t finished processing, or PQgetResult has not been called to collect results from all previously sent query.

Available since PostgreSQL-14

    static VALUE
    pgconn_exit_pipeline_mode(VALUE self)
    {
            PGconn *conn = pg_get_pgconn(self);
            int res = PQexitPipelineMode(conn);
            if( res != 1 )
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(conn));

            return Qnil;
    }

external_encoding() → Encoding click to toggle source

Return the `server_encoding` of the connected database as a Ruby Encoding object. The `SQL_ASCII` encoding is mapped to to `ASCII_8BIT`.

    static VALUE
    pgconn_external_encoding(VALUE self)
    {
            t_pg_connection *this = pg_get_connection_safe( self );
            rb_encoding *enc = NULL;
            const char *pg_encname = NULL;

            pg_encname = PQparameterStatus( this->pgconn, "server_encoding" );
            enc = pg_get_pg_encname_as_rb_encoding( pg_encname );
            return rb_enc_from_encoding( enc );
    }

field_name_type → Symbol click to toggle source

Get type of field names.

See description at `field_name_type=`

    static VALUE
    pgconn_field_name_type_get(VALUE self)
    {
            t_pg_connection *this = pg_get_connection( self );

            if( this->flags & PG_RESULT_FIELD_NAMES_SYMBOL ){
                    return sym_symbol;
            } else if( this->flags & PG_RESULT_FIELD_NAMES_STATIC_SYMBOL ){
                    return sym_static_symbol;
            } else {
                    return sym_string;
            }
    }

field_name_type = Symbol click to toggle source

Set default type of field names of results retrieved by this connection. It can be set to one of:

- `:string` to use String based field names

- `:symbol` to use Symbol based field names

The default is `:string` .

Settings the type of field names affects only future results.

See further description at `PG::Result#field_name_type=` and `field_name_type` .

    static VALUE
    pgconn_field_name_type_set(VALUE self, VALUE sym)
    {
            t_pg_connection *this = pg_get_connection( self );

            rb_check_frozen(self);
            this->flags &= ~PG_RESULT_FIELD_NAMES_MASK;
            if( sym == sym_symbol ) this->flags |= PG_RESULT_FIELD_NAMES_SYMBOL;
            else if ( sym == sym_static_symbol ) this->flags |= PG_RESULT_FIELD_NAMES_STATIC_SYMBOL;
            else if ( sym == sym_string );
            else rb_raise(rb_eArgError, "invalid argument %+"PRIsVALUE, sym);

            return sym;
    }

finish click to toggle source

Closes the backend connection.

    static VALUE
    pgconn_finish( VALUE self )
    {
            t_pg_connection *this = pg_get_connection_safe( self );

            pgconn_close_socket_io( self );
            PQfinish( this->pgconn );
            this->pgconn = NULL;
            return Qnil;
    }

Also aliased as: close
finished? → boolean click to toggle source

Returns `true` if the backend connection has been closed.

    static VALUE
    pgconn_finished_p( VALUE self )
    {
            t_pg_connection *this = pg_get_connection( self );
            if ( this->pgconn ) return Qfalse;
            return Qtrue;
    }

flush() → Boolean click to toggle source

Attempts to flush any queued output data to the server. Returns `true` if data is successfully flushed, `false` if not. It can only return `false` if connection is in nonblocking mode. Raises `PG::Error` if some other failure occurred.

    static VALUE
    pgconn_async_flush(VALUE self)
    {
            while( pgconn_sync_flush(self) == Qfalse ){
                    /* wait for the socket to become read- or write-ready */
                    int events;
                    VALUE socket_io = pgconn_socket_io(self);
                    events = RB_NUM2INT(pg_rb_io_wait(socket_io, RB_INT2NUM(PG_RUBY_IO_READABLE | PG_RUBY_IO_WRITABLE), Qnil));

                    if (events & PG_RUBY_IO_READABLE){
                            pgconn_consume_input(self);
                    }
            }
            return Qtrue;
    }

Also aliased as: async_flush
get_client_encoding() → String click to toggle source

Returns the client encoding as a String.

    static VALUE
    pgconn_get_client_encoding(VALUE self)
    {
            char *encoding = (char *)pg_encoding_to_char(PQclientEncoding(pg_get_pgconn(self)));
            return rb_str_new2(encoding);
    }

get_copy_data( [ nonblock = false [, decoder = nil ]] ) → Object click to toggle source

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`.

    # File lib/pg/connection.rb, line 427
    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

Also aliased as: async_get_copy_data
get_last_result( ) → PG::Result click to toggle source

This function retrieves all available results on the current connection (from previously issued asynchronous commands like +send_query()+) and returns the last non-NULL result, or `nil` if no results are available.

If the last result contains a bad result_status, an appropriate exception is raised.

This function is similar to `get_result` except that it is designed to get one and only one result and that it checks the result state.

    static VALUE
    pgconn_async_get_last_result(VALUE self)
    {
            PGconn *conn = pg_get_pgconn(self);
            VALUE rb_pgresult = Qnil;
            PGresult *cur, *prev;

            cur = prev = NULL;
            for(;;) {
                    int status;

                    /* Wait for input before reading each result.
                     * That way we support the ruby-3.x IO scheduler and don't block other ruby threads.
                     */
                    wait_socket_readable(self, NULL, get_result_readable);

                    cur = gvl_PQgetResult(conn);
                    if (cur == NULL)
                            break;

                    if (prev) PQclear(prev);
                    prev = cur;

                    status = PQresultStatus(cur);
                    if (status == PGRES_COPY_OUT || status == PGRES_COPY_IN || status == PGRES_COPY_BOTH)
                            break;
            }

            if (prev) {
                    rb_pgresult = pg_new_result( prev, self );
                    pg_result_check(rb_pgresult);
            }

            return rb_pgresult;
    }

Also aliased as: async_get_last_result
get_result() → PG::Result click to toggle source
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.

    # File lib/pg/connection.rb, line 404
    def get_result
            block
            sync_get_result
    end

Also aliased as: async_get_result
host() click to toggle source

Returns the server host name of the active connection. This can be a host name, an IP address, or a directory path if the connection is via Unix socket. (The path case can be distinguished because it will always be an absolute path, beginning with `/` .)

If the connection parameters specified both host and hostaddr, then `host` will return the host information. If only hostaddr was specified, then that is returned. If multiple hosts were specified in the connection parameters, `host` returns the host actually connected to.

If there is an error producing the host information (perhaps if the connection has not been fully established or there was an error), it returns an empty string.

If multiple hosts were specified in the connection parameters, it is not possible to rely on the result of `host` until the connection is established. The status of the connection can be checked using the function `Connection#status` .

    static VALUE
    pgconn_host(VALUE self)
    {
            char *host = PQhost(pg_get_pgconn(self));
            if (!host) return Qnil;
            return rb_str_new2(host);
    }

hostaddr() click to toggle source

Returns the server IP address of the active connection. This can be the address that a host name resolved to, or an IP address provided through the hostaddr parameter. If there is an error producing the host information (perhaps if the connection has not been fully established or there was an error), it returns an empty string.

    static VALUE
    pgconn_hostaddr(VALUE self)
    {
            char *host = PQhostaddr(pg_get_pgconn(self));
            if (!host) return Qnil;
            return rb_str_new2(host);
    }

inspect() click to toggle source

Return a String representation of the object suitable for debugging.

    # File lib/pg/connection.rb, line 99
    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

internal_encoding → Encoding click to toggle source

defined in Ruby 1.9 or later.

Returns:

- an Encoding - client_encoding of the connection as a Ruby Encoding object.

- nil - the client_encoding is ‘SQL_ASCII’

    static VALUE
    pgconn_internal_encoding(VALUE self)
    {
            PGconn *conn = pg_get_pgconn( self );
            rb_encoding *enc = pg_conn_enc_get( conn );

            if ( enc ) {
                    return rb_enc_from_encoding( enc );
            } else {
                    return Qnil;
            }
    }

internal_encoding = value click to toggle source

A wrapper of `set_client_encoding`. defined in Ruby 1.9 or later.

`value` can be one of:

- an Encoding

- a String - a name of Encoding

- `nil` - sets the client_encoding to SQL_ASCII.

    static VALUE
    pgconn_internal_encoding_set(VALUE self, VALUE enc)
    {
            rb_check_frozen(self);
            if (NIL_P(enc)) {
                    pgconn_sync_set_client_encoding( self, rb_usascii_str_new_cstr("SQL_ASCII") );
                    return enc;
            }
            else if ( TYPE(enc) == T_STRING && strcasecmp("JOHAB", StringValueCStr(enc)) == 0 ) {
                    pgconn_sync_set_client_encoding(self, rb_usascii_str_new_cstr("JOHAB"));
                    return enc;
            }
            else {
                    rb_encoding *rbenc = rb_to_encoding( enc );
                    const char *name = pg_get_rb_encoding_as_pg_encoding( rbenc );

                    if ( gvl_PQsetClientEncoding(pg_get_pgconn( self ), name) == -1 ) {
                            VALUE server_encoding = pgconn_external_encoding( self );
                            rb_raise( rb_eEncCompatError, "incompatible character encodings: %s and %s",
                                              rb_enc_name(rb_to_encoding(server_encoding)), name );
                    }
                    pgconn_set_internal_encoding_index( self );
                    return enc;
            }
    }

is_busy() → Boolean click to toggle source

Returns `true` if a command is busy, that is, if `get_result` would block. Otherwise returns `false`.

    static VALUE
    pgconn_is_busy(VALUE self)
    {
            return gvl_PQisBusy(pg_get_pgconn(self)) ? Qtrue : Qfalse;
    }

isnonblocking() → Boolean click to toggle source

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

    # File lib/pg/connection.rb, line 475
    def isnonblocking
            false
    end

Also aliased as: async_isnonblocking, nonblocking?
lo_close( lo_desc ) → nil click to toggle source

Closes the postgres large object of lo_desc.

    static VALUE
    pgconn_loclose(VALUE self, VALUE in_lo_desc)
    {
            PGconn *conn = pg_get_pgconn(self);
            int lo_desc = NUM2INT(in_lo_desc);
            int ret;

            BLOCKING_BEGIN(conn)
                    ret = lo_close(conn,lo_desc);
            BLOCKING_END(conn)

            if(ret < 0)
                    pg_raise_conn_error( rb_ePGerror, self, "lo_close failed");

            return Qnil;
    }

Also aliased as: loclose
lo_creat( [mode] ) → Integer click to toggle source

Creates a large object with mode mode. Returns a large object Oid. On failure, it raises `PG::Error`.

    static VALUE
    pgconn_locreat(int argc, VALUE *argv, VALUE self)
    {
            Oid lo_oid;
            int mode;
            VALUE nmode;
            PGconn *conn = pg_get_pgconn(self);

            if (rb_scan_args(argc, argv, "01", &nmode) == 0)
                    mode = INV_READ;
            else
                    mode = NUM2INT(nmode);

            BLOCKING_BEGIN(conn)
                    lo_oid = lo_creat(conn, mode);
            BLOCKING_END(conn)

            if (lo_oid == 0)
                    pg_raise_conn_error( rb_ePGerror, self, "lo_creat failed");

            return UINT2NUM(lo_oid);
    }

Also aliased as: locreat
lo_create( oid ) → Integer click to toggle source

Creates a large object with oid oid. Returns the large object Oid. On failure, it raises `PG::Error`.

    static VALUE
    pgconn_locreate(VALUE self, VALUE in_lo_oid)
    {
            Oid ret, lo_oid;
            PGconn *conn = pg_get_pgconn(self);
            lo_oid = NUM2UINT(in_lo_oid);

            ret = lo_create(conn, lo_oid);
            if (ret == InvalidOid)
                    pg_raise_conn_error( rb_ePGerror, self, "lo_create failed");

            return UINT2NUM(ret);
    }

Also aliased as: locreate
lo_export( oid, file ) → nil click to toggle source

Saves a large object of oid to a file.

    static VALUE
    pgconn_loexport(VALUE self, VALUE lo_oid, VALUE filename)
    {
            PGconn *conn = pg_get_pgconn(self);
            Oid oid;
            int ret;
            Check_Type(filename, T_STRING);

            oid = NUM2UINT(lo_oid);

            BLOCKING_BEGIN(conn)
                    ret = lo_export(conn, oid, StringValueCStr(filename));
            BLOCKING_END(conn)

            if (ret < 0) {
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(conn));
            }
            return Qnil;
    }

Also aliased as: loexport
lo_import(file) → Integer click to toggle source

Import a file to a large object. Returns a large object Oid.

On failure, it raises a `PG::Error`.

    static VALUE
    pgconn_loimport(VALUE self, VALUE filename)
    {
            Oid lo_oid;

            PGconn *conn = pg_get_pgconn(self);

            Check_Type(filename, T_STRING);

            BLOCKING_BEGIN(conn)
                    lo_oid = lo_import(conn, StringValueCStr(filename));
            BLOCKING_END(conn)

            if (lo_oid == 0) {
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(conn));
            }
            return UINT2NUM(lo_oid);
    }

Also aliased as: loimport
lo_lseek( lo_desc, offset, whence ) → Integer click to toggle source

Move the large object pointer lo_desc to offset offset. Valid values for whence are `SEEK_SET`, `SEEK_CUR`, and `SEEK_END`. (Or 0, 1, or 2.)

    static VALUE
    pgconn_lolseek(VALUE self, VALUE in_lo_desc, VALUE offset, VALUE whence)
    {
            PGconn *conn = pg_get_pgconn(self);
            int lo_desc = NUM2INT(in_lo_desc);
            int ret;

            BLOCKING_BEGIN(conn)
                    ret = lo_lseek(conn, lo_desc, NUM2INT(offset), NUM2INT(whence));
            BLOCKING_END(conn)

            if(ret < 0) {
                    pg_raise_conn_error( rb_ePGerror, self, "lo_lseek failed");
            }

            return INT2FIX(ret);
    }

Also aliased as: lolseek, lo_seek, loseek
lo_open( oid, [mode] ) → Integer click to toggle source

Open a large object of oid. Returns a large object descriptor instance on success. The mode argument specifies the mode for the opened large object,which is either `INV_READ`, or `INV_WRITE`.

If mode is omitted, the default is `INV_READ`.

    static VALUE
    pgconn_loopen(int argc, VALUE *argv, VALUE self)
    {
            Oid lo_oid;
            int fd, mode;
            VALUE nmode, selfid;
            PGconn *conn = pg_get_pgconn(self);

            rb_scan_args(argc, argv, "11", &selfid, &nmode);
            lo_oid = NUM2UINT(selfid);
            if(NIL_P(nmode))
                    mode = INV_READ;
            else
                    mode = NUM2INT(nmode);

            BLOCKING_BEGIN(conn)
                    fd = lo_open(conn, lo_oid, mode);
            BLOCKING_END(conn)

            if(fd < 0) {
                    pg_raise_conn_error( rb_ePGerror, self, "can't open large object: %s", PQerrorMessage(conn));
            }
            return INT2FIX(fd);
    }

Also aliased as: loopen
lo_read( lo_desc, len ) → String click to toggle source

Attempts to read len bytes from large object lo_desc, returns resulting data.

    static VALUE
    pgconn_loread(VALUE self, VALUE in_lo_desc, VALUE in_len)
    {
            int ret;
      PGconn *conn = pg_get_pgconn(self);
            int len = NUM2INT(in_len);
            int lo_desc = NUM2INT(in_lo_desc);
            VALUE str;
            char *buffer;

            if (len < 0)
                    pg_raise_conn_error( rb_ePGerror, self, "negative length %d given", len);

            buffer = ALLOC_N(char, len);

            BLOCKING_BEGIN(conn)
                    ret = lo_read(conn, lo_desc, buffer, len);
            BLOCKING_END(conn)

            if(ret < 0)
                    pg_raise_conn_error( rb_ePGerror, self, "lo_read failed");

            if(ret == 0) {
                    xfree(buffer);
                    return Qnil;
            }

            str = rb_str_new(buffer, ret);
            xfree(buffer);

            return str;
    }

Also aliased as: loread
lo_seek
Alias for: lo_lseek
lo_tell( lo_desc ) → Integer click to toggle source

Returns the current position of the large object lo_desc.

    static VALUE
    pgconn_lotell(VALUE self, VALUE in_lo_desc)
    {
            int position;
            PGconn *conn = pg_get_pgconn(self);
            int lo_desc = NUM2INT(in_lo_desc);

            BLOCKING_BEGIN(conn)
                    position = lo_tell(conn, lo_desc);
            BLOCKING_END(conn)

            if(position < 0)
                    pg_raise_conn_error( rb_ePGerror, self, "lo_tell failed");

            return INT2FIX(position);
    }

Also aliased as: lotell
lo_truncate( lo_desc, len ) → nil click to toggle source

Truncates the large object lo_desc to size len.

    static VALUE
    pgconn_lotruncate(VALUE self, VALUE in_lo_desc, VALUE in_len)
    {
            PGconn *conn = pg_get_pgconn(self);
            int lo_desc = NUM2INT(in_lo_desc);
            size_t len = NUM2INT(in_len);
            int ret;

            BLOCKING_BEGIN(conn)
                    ret = lo_truncate(conn,lo_desc,len);
            BLOCKING_END(conn)

            if(ret < 0)
                    pg_raise_conn_error( rb_ePGerror, self, "lo_truncate failed");

            return Qnil;
    }

Also aliased as: lotruncate
lo_unlink( oid ) → nil click to toggle source

Unlinks (deletes) the postgres large object of oid.

    static VALUE
    pgconn_lounlink(VALUE self, VALUE in_oid)
    {
            PGconn *conn = pg_get_pgconn(self);
            Oid oid = NUM2UINT(in_oid);
            int ret;

            BLOCKING_BEGIN(conn)
                    ret = lo_unlink(conn,oid);
            BLOCKING_END(conn)

            if(ret < 0)
                    pg_raise_conn_error( rb_ePGerror, self, "lo_unlink failed");

            return Qnil;
    }

Also aliased as: lounlink
lo_write( lo_desc, buffer ) → Integer click to toggle source

Writes the string buffer to the large object lo_desc. Returns the number of bytes written.

    static VALUE
    pgconn_lowrite(VALUE self, VALUE in_lo_desc, VALUE buffer)
    {
            int n;
            PGconn *conn = pg_get_pgconn(self);
            int fd = NUM2INT(in_lo_desc);

            Check_Type(buffer, T_STRING);

            if( RSTRING_LEN(buffer) < 0) {
                    pg_raise_conn_error( rb_ePGerror, self, "write buffer zero string");
            }
            BLOCKING_BEGIN(conn)
                    n = lo_write(conn, fd, StringValuePtr(buffer),
                                    RSTRING_LEN(buffer));
            BLOCKING_END(conn)

            if(n < 0) {
                    pg_raise_conn_error( rb_ePGerror, self, "lo_write failed: %s", PQerrorMessage(conn));
            }

            return INT2FIX(n);
    }

Also aliased as: lowrite
loclose
Alias for: lo_close
locreat
Alias for: lo_creat
locreate
Alias for: lo_create
loexport
Alias for: lo_export
loimport
Alias for: lo_import
lolseek
Alias for: lo_lseek
loopen
Alias for: lo_open
loread
Alias for: lo_read
loseek
Alias for: lo_lseek
lotell
Alias for: lo_tell
lotruncate
Alias for: lo_truncate
lounlink
Alias for: lo_unlink
lowrite
Alias for: lo_write
make_empty_pgresult( status ) → PG::Result click to toggle source

Constructs and empty `PG::Result` with status status. status may be one of:

- `PGRES_EMPTY_QUERY`

- `PGRES_COMMAND_OK`

- `PGRES_TUPLES_OK`

- `PGRES_COPY_OUT`

- `PGRES_COPY_IN`

- `PGRES_BAD_RESPONSE`

- `PGRES_NONFATAL_ERROR`

- `PGRES_FATAL_ERROR`

- `PGRES_COPY_BOTH`

- `PGRES_SINGLE_TUPLE`

- `PGRES_TUPLES_CHUNK`

- `PGRES_PIPELINE_SYNC`

- `PGRES_PIPELINE_ABORTED`

    static VALUE
    pgconn_make_empty_pgresult(VALUE self, VALUE status)
    {
            PGresult *result;
            VALUE rb_pgresult;
            PGconn *conn = pg_get_pgconn(self);
            result = PQmakeEmptyPGresult(conn, NUM2INT(status));
            rb_pgresult = pg_new_result(result, self);
            pg_result_check(rb_pgresult);
            return rb_pgresult;
    }

nonblocking?
Alias for: isnonblocking
notifies() click to toggle source

Returns a hash of the unprocessed notifications. If there is no unprocessed notifier, it returns `nil`.

    static VALUE
    pgconn_notifies(VALUE self)
    {
            t_pg_connection *this = pg_get_connection_safe( self );
            PGnotify *notification;
            VALUE hash;
            VALUE sym_relname, sym_be_pid, sym_extra;
            VALUE relname, be_pid, extra;

            sym_relname = ID2SYM(rb_intern("relname"));
            sym_be_pid = ID2SYM(rb_intern("be_pid"));
            sym_extra = ID2SYM(rb_intern("extra"));

            notification = gvl_PQnotifies(this->pgconn);
            if (notification == NULL) {
                    return Qnil;
            }

            hash = rb_hash_new_capa(3);
            relname = rb_str_new2(notification->relname);
            be_pid = INT2NUM(notification->be_pid);
            extra = rb_str_new2(notification->extra);
            PG_ENCODING_SET_NOCHECK( relname, this->enc_idx );
            PG_ENCODING_SET_NOCHECK( extra, this->enc_idx );

            rb_hash_aset(hash, sym_relname, relname);
            rb_hash_aset(hash, sym_be_pid, be_pid);
            rb_hash_aset(hash, sym_extra, extra);

            PQfreemem(notification);
            return hash;
    }

notifies_wait
Alias for: wait_for_notify
options() click to toggle source

Returns backend option string.

    static VALUE
    pgconn_options(VALUE self)
    {
            char *options = PQoptions(pg_get_pgconn(self));
            if (!options) return Qnil;
            return rb_str_new2(options);
    }

parameter_status( param_name ) → String click to toggle source

Returns the setting of parameter param_name, where param_name is one of

- `server_version`

- `server_encoding`

- `client_encoding`

- `is_superuser`

- `session_authorization`

- `DateStyle`

- `TimeZone`

- `integer_datetimes`

- `standard_conforming_strings`

Returns nil if the value of the parameter is not known.

    static VALUE
    pgconn_parameter_status(VALUE self, VALUE param_name)
    {
            const char *ret = PQparameterStatus(pg_get_pgconn(self), StringValueCStr(param_name));
            if(ret == NULL)
                    return Qnil;
            else
                    return rb_str_new2(ret);
    }

pass() click to toggle source

Returns the authenticated password.

    static VALUE
    pgconn_pass(VALUE self)
    {
            char *user = PQpass(pg_get_pgconn(self));
            if (!user) return Qnil;
            return rb_str_new2(user);
    }

pipeline_status → Integer click to toggle source

Returns the current pipeline mode status of the libpq connection.

PQpipelineStatus can return one of the following values:

- PQ_PIPELINE_ON - The libpq connection is in pipeline mode.

- PQ_PIPELINE_OFF - The libpq connection is not in pipeline mode.

- PQ_PIPELINE_ABORTED - The libpq connection is in pipeline mode and an error occurred while processing the current pipeline. The aborted flag is cleared when PQgetResult returns a result of type PGRES_PIPELINE_SYNC.

Available since PostgreSQL-14

    static VALUE
    pgconn_pipeline_status(VALUE self)
    {
            int res = PQpipelineStatus(pg_get_pgconn(self));
            return INT2FIX(res);
    }

pipeline_sync click to toggle source

Marks a synchronization point in a pipeline by sending a sync message and flushing the send buffer. This serves as the delimiter of an implicit transaction and an error recovery point.

See `enter_pipeline_mode`

Raises `PG::Error` if the connection is not in pipeline mode or sending a sync message failed.

Available since PostgreSQL-14

    # File lib/pg/connection.rb, line 550
    def pipeline_sync(*args)
            send_pipeline_sync(*args)
            flush
    end

Also aliased as: async_pipeline_sync
port() click to toggle source

Returns the connected server port number.

    static VALUE
    pgconn_port(VALUE self)
    {
            char* port = PQport(pg_get_pgconn(self));
            if (!port || port[0] == '\0')
                    return INT2NUM(DEF_PGPORT);
            else
                    return INT2NUM(atoi(port));
    }

prepare(stmt_name, sql [, param_types ] ) → PG::Result click to toggle source

Prepares statement sql with name name to be executed later. Returns a `PG::Result` instance on success. On failure, it raises a `PG::Error`.

`param_types` is an optional parameter to specify the Oids of the types of the parameters.

If the types are not specified, they will be inferred by PostgreSQL. Instead of specifying type oids, it’s recommended to simply add explicit casts in the query to ensure that the right type is used.

For example: “SELECT $1::int”

PostgreSQL bind parameters are represented as $1, $2, $3, etc., inside the SQL query.

See also corresponding libpq function.

    static VALUE
    pgconn_async_prepare(int argc, VALUE *argv, VALUE self)
    {
            VALUE rb_pgresult = Qnil;

            pgconn_discard_results( self );
            pgconn_send_prepare( argc, argv, self );
            rb_pgresult = pgconn_async_get_last_result( self );

            if ( rb_block_given_p() ) {
                    return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
            }
            return rb_pgresult;
    }

Also aliased as: async_prepare
protocol_version → Integer click to toggle source

Interrogates the frontend/backend protocol being used.

Applications might wish to use this function to determine whether certain features are supported. Currently, the only value is 3 (3.0 protocol). The protocol version will not change after connection startup is complete, but it could theoretically change during a connection reset. The 3.0 protocol is supported by PostgreSQL server versions 7.4 and above.

`PG::ConnectionBad` is raised if the connection is bad.

    static VALUE
    pgconn_protocol_version(VALUE self)
    {
            int protocol_version = PQprotocolVersion(pg_get_pgconn(self));
            if (protocol_version == 0) {
                    pg_raise_conn_error( rb_eConnectionBad, self, "PQprotocolVersion() can't get protocol version");
            }
            return INT2NUM(protocol_version);
    }

put_copy_data( buffer [, encoder] ) → Boolean click to toggle source

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`.

    # File lib/pg/connection.rb, line 499
    def put_copy_data(buffer, encoder=nil)
            # sync_put_copy_data does a non-blocking attempt 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

Also aliased as: async_put_copy_data
put_copy_end( [ error_message ] ) → Boolean click to toggle source

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).

    # File lib/pg/connection.rb, line 529
    def put_copy_end(*args)
            until sync_put_copy_end(*args)
                    flush
            end
            @calls_to_put_copy_data = 0
            flush
    end

Also aliased as: async_put_copy_end
quote_ident( str ) → String click to toggle source
quote_ident( array ) → String
PG::Connection.quote_ident( str ) → String
PG::Connection.quote_ident( array ) → String

Returns a string that is safe for inclusion in a SQL query as an identifier. Note: this is not a quote function for values, but for identifiers.

For example, in a typical SQL query: `SELECT FOO FROM MYTABLE` The identifier `FOO` is folded to lower case, so it actually means `foo`. If you really want to access the case-sensitive field name `FOO`, use this function like `conn.quote_ident('FOO')`, which will return `"FOO"` (with double-quotes). PostgreSQL will see the double-quotes, and it will not fold to lower case.

Similarly, this function also protects against special characters, and other things that might allow SQL injection if the identifier comes from an untrusted source.

If the parameter is an Array, then all it’s values are separately quoted and then joined by a “.” character. This can be used for identifiers in the form “schema”.“table”.“column” .

This method is functional identical to the encoder `PG::TextEncoder::Identifier` .

If the instance method form is used and the input string character encoding is different to the connection encoding, then the string is converted to this encoding, so that the returned string is always encoded as `PG::Connection#internal_encoding` .

In the singleton form (`PG::Connection.quote_ident`) the character encoding of the result string is set to the character encoding of the input string.

    static VALUE
    pgconn_s_quote_ident(VALUE self, VALUE str_or_array)
    {
            VALUE ret;
            int enc_idx;

            if( rb_obj_is_kind_of(self, rb_cPGconn) ){
                    enc_idx = pg_get_connection(self)->enc_idx;
            }else{
                    enc_idx = RB_TYPE_P(str_or_array, T_STRING) ? ENCODING_GET( str_or_array ) : rb_ascii8bit_encindex();
            }
            pg_text_enc_identifier(NULL, str_or_array, NULL, &ret, enc_idx);

            return ret;
    }

Also aliased as: quote_ident
reset() click to toggle source

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

    # File lib/pg/connection.rb, line 590
    def reset
            # Use connection options from PG::Connection.new to reconnect with the same options but with renewed DNS resolution.
            # Use conninfo_hash as a fallback when connect_start was used to create the connection object.
            iopts = @iopts_for_reset || conninfo_hash.compact
            if iopts[:host] && !iopts[:host].empty? && PG.library_version >= 100000
                    iopts = self.class.send(:resolve_hosts, iopts)
            end
            conninfo = self.class.parse_connect_args( iopts );
            reset_start2(conninfo)
            async_connect_or_reset(:reset_poll)
            self
    end

Also aliased as: async_reset
reset_poll → Integer click to toggle source

Checks the status of a connection reset operation. See `Connection.connect_start` and `connect_poll` for usage information and return values.

    static VALUE
    pgconn_reset_poll(VALUE self)
    {
            PostgresPollingStatusType status;

            pgconn_close_socket_io(self);
            status = gvl_PQresetPoll(pg_get_pgconn(self));

            return INT2FIX((int)status);
    }

reset_start() → nil click to toggle source

Initiate a connection reset in a nonblocking manner. This will close the current connection and attempt to reconnect using the same connection parameters. Use `reset_poll` to check the status of the connection reset.

    static VALUE
    pgconn_reset_start(VALUE self)
    {
            pgconn_close_socket_io( self );
            if(gvl_PQresetStart(pg_get_pgconn(self)) == 0)
                    pg_raise_conn_error( rb_eUnableToSend, self, "reset has failed");
            return Qnil;
    }

send_describe_portal( portal_name ) → nil click to toggle source

Asynchronously send command to the server. Does not block. Use in combination with `conn.get_result`.

    static VALUE
    pgconn_send_describe_portal(VALUE self, VALUE portal)
    {
            return pgconn_send_describe_close_prepared_portal(
                    self, portal, gvl_PQsendDescribePortal,
                    "PQsendDescribePortal");
    }

send_describe_prepared( statement_name ) → nil click to toggle source

Asynchronously send command to the server. Does not block. Use in combination with `conn.get_result`.

    static VALUE
    pgconn_send_describe_prepared(VALUE self, VALUE stmt_name)
    {
            return pgconn_send_describe_close_prepared_portal(
                    self, stmt_name, gvl_PQsendDescribePrepared,
                    "PQsendDescribePrepared");
    }

send_flush_request → nil click to toggle source

Sends a request for the server to flush its output buffer.

The server flushes its output buffer automatically as a result of `Connection#pipeline_sync` being called, or on any request when not in pipeline mode. This function is useful to cause the server to flush its output buffer in pipeline mode without establishing a synchronization point. Note that the request is not itself flushed to the server automatically; use `Connection#flush` if necessary.

Available since PostgreSQL-14

    static VALUE
    pgconn_send_flush_request(VALUE self)
    {
            PGconn *conn = pg_get_pgconn(self);
            int res = PQsendFlushRequest(conn);
            if( res != 1 )
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(conn));

            return Qnil;
    }

send_pipeline_sync → nil click to toggle source

Marks a synchronization point in a pipeline by sending a sync message without flushing the send buffer.

This serves as the delimiter of an implicit transaction and an error recovery point. Raises `PG::Error` if the connection is not in pipeline mode or sending a sync message failed. Note that the message is not itself flushed to the server automatically; use flush if necessary.

Available since PostgreSQL-17

    static VALUE
    pgconn_send_pipeline_sync(VALUE self)
    {
            PGconn *conn = pg_get_pgconn(self);
            int res = gvl_PQsendPipelineSync(conn);
            if( res != 1 )
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(conn));

            return Qnil;
    }

send_prepare( stmt_name, sql [, param_types ] ) → nil click to toggle source

Prepares statement sql with name name to be executed later. Sends prepare command asynchronously, and returns immediately. On failure, it raises a `PG::Error`.

`param_types` is an optional parameter to specify the Oids of the types of the parameters.

If the types are not specified, they will be inferred by PostgreSQL. Instead of specifying type oids, it’s recommended to simply add explicit casts in the query to ensure that the right type is used.

For example: “SELECT $1::int”

PostgreSQL bind parameters are represented as $1, $2, $3, etc., inside the SQL query.

    static VALUE
    pgconn_send_prepare(int argc, VALUE *argv, VALUE self)
    {
            t_pg_connection *this = pg_get_connection_safe( self );
            int result;
            VALUE name, command, in_paramtypes;
            VALUE param;
            int i = 0;
            int nParams = 0;
            Oid *paramTypes = NULL;
            const char *name_cstr;
            const char *command_cstr;
            int enc_idx = this->enc_idx;

            rb_scan_args(argc, argv, "21", &name, &command, &in_paramtypes);
            name_cstr = pg_cstr_enc(name, enc_idx);
            command_cstr = pg_cstr_enc(command, enc_idx);

            if(! NIL_P(in_paramtypes)) {
                    Check_Type(in_paramtypes, T_ARRAY);
                    nParams = (int)RARRAY_LEN(in_paramtypes);
                    paramTypes = ALLOC_N(Oid, nParams);
                    for(i = 0; i < nParams; i++) {
                            param = rb_ary_entry(in_paramtypes, i);
                            if(param == Qnil)
                                    paramTypes[i] = 0;
                            else
                                    paramTypes[i] = NUM2UINT(param);
                    }
            }
            result = gvl_PQsendPrepare(this->pgconn, name_cstr, command_cstr, nParams, paramTypes);

            xfree(paramTypes);

            if(result == 0) {
                    pg_raise_conn_error( rb_eUnableToSend, self, "PQsendPrepare %s", PQerrorMessage(this->pgconn));
            }
            pgconn_wait_for_flush( self );
            return Qnil;
    }

send_query(sql) → nil click to toggle source

Sends SQL query request specified by sql to PostgreSQL for asynchronous processing, and immediately returns. On failure, it raises a `PG::Error`.

For backward compatibility, if you pass more than one parameter to this method, it will call `send_query_params` for you. New code should explicitly use `send_query_params` if argument placeholders are used.

    static VALUE
    pgconn_send_query(int argc, VALUE *argv, VALUE self)
    {
            t_pg_connection *this = pg_get_connection_safe( self );

            /* If called with no or nil parameters, use PQexec for compatibility */
            if ( argc == 1 || (argc >= 2 && argc <= 4 && NIL_P(argv[1]) )) {
                    if(gvl_PQsendQuery(this->pgconn, pg_cstr_enc(argv[0], this->enc_idx)) == 0)
                            pg_raise_conn_error( rb_eUnableToSend, self, "PQsendQuery %s", PQerrorMessage(this->pgconn));

                    pgconn_wait_for_flush( self );
                    return Qnil;
            }

            pg_deprecated(2, ("forwarding async_exec to async_exec_params and send_query to send_query_params is deprecated"));

            /* If called with parameters, and optionally result_format,
             * use PQsendQueryParams
             */
            return pgconn_send_query_params( argc, argv, self);
    }

send_query_params(sql, params [, result_format [, type_map ]] ) → nil click to toggle source

Sends SQL query request specified by sql to PostgreSQL for asynchronous processing, and immediately returns. On failure, it raises a `PG::Error`.

`params` is an array of the bind parameters for the SQL query. Each element of the `params` array may be either:

    a hash of the form:
      {:value  => String (value of bind parameter)
       :type   => Integer (oid of type of bind parameter)
       :format => Integer (0 for text, 1 for binary)
      }
    or, it may be a String. If it is a string, that is equivalent to the hash:
      { :value => <string value>, :type => 0, :format => 0 }

PostgreSQL bind parameters are represented as $1, $2, $3, etc., inside the SQL query. The 0th element of the `params` array is bound to $1, the 1st element is bound to $2, etc. `nil` is treated as `NULL`.

If the types are not specified, they will be inferred by PostgreSQL. Instead of specifying type oids, it’s recommended to simply add explicit casts in the query to ensure that the right type is used.

For example: “SELECT $1::int”

The optional `result_format` should be 0 for text results, 1 for binary.

`type_map` can be a `PG::TypeMap` derivation (such as `PG::BasicTypeMapForQueries`). This will type cast the params from various Ruby types before transmission based on the encoders defined by the type map. When a type encoder is used the format and oid of a given bind parameter are retrieved from the encoder instead out of the hash form described above.

    static VALUE
    pgconn_send_query_params(int argc, VALUE *argv, VALUE self)
    {
            t_pg_connection *this = pg_get_connection_safe( self );
            int result;
            VALUE command, in_res_fmt;
            int nParams;
            int resultFormat;
            struct query_params_data paramsData = { this->enc_idx };

            rb_scan_args(argc, argv, "22", &command, &paramsData.params, &in_res_fmt, &paramsData.typemap);
            paramsData.with_types = 1;

            pgconn_query_assign_typemap( self, &paramsData );
            resultFormat = NIL_P(in_res_fmt) ? 0 : NUM2INT(in_res_fmt);
            nParams = alloc_query_params( &paramsData );

            result = gvl_PQsendQueryParams(this->pgconn, pg_cstr_enc(command, paramsData.enc_idx), nParams, paramsData.types,
                    (const char * const *)paramsData.values, paramsData.lengths, paramsData.formats, resultFormat);

            free_query_params( &paramsData );

            if(result == 0)
                    pg_raise_conn_error( rb_eUnableToSend, self, "PQsendQueryParams %s", PQerrorMessage(this->pgconn));

            pgconn_wait_for_flush( self );
            return Qnil;
    }

send_query_prepared( statement_name [, params, result_format[, type_map ]] ) click to toggle source
→ nil

Execute prepared named statement specified by statement_name asynchronously, and returns immediately. On failure, it raises a `PG::Error`.

`params` is an array of the optional bind parameters for the SQL query. Each element of the `params` array may be either:

    a hash of the form:
      {:value  => String (value of bind parameter)
       :format => Integer (0 for text, 1 for binary)
      }
    or, it may be a String. If it is a string, that is equivalent to the hash:
      { :value => <string value>, :format => 0 }

PostgreSQL bind parameters are represented as $1, $2, $3, etc., inside the SQL query. The 0th element of the `params` array is bound to $1, the 1st element is bound to $2, etc. `nil` is treated as `NULL`.

The optional `result_format` should be 0 for text results, 1 for binary.

`type_map` can be a `PG::TypeMap` derivation (such as `PG::BasicTypeMapForQueries`). This will type cast the params from various Ruby types before transmission based on the encoders defined by the type map. When a type encoder is used the format and oid of a given bind parameter are retrieved from the encoder instead out of the hash form described above.

    static VALUE
    pgconn_send_query_prepared(int argc, VALUE *argv, VALUE self)
    {
            t_pg_connection *this = pg_get_connection_safe( self );
            int result;
            VALUE name, in_res_fmt;
            int nParams;
            int resultFormat;
            struct query_params_data paramsData = { this->enc_idx };

            rb_scan_args(argc, argv, "13", &name, &paramsData.params, &in_res_fmt, &paramsData.typemap);
            paramsData.with_types = 0;

            if(NIL_P(paramsData.params)) {
                    paramsData.params = rb_ary_new2(0);
            }
            pgconn_query_assign_typemap( self, &paramsData );

            resultFormat = NIL_P(in_res_fmt) ? 0 : NUM2INT(in_res_fmt);
            nParams = alloc_query_params( &paramsData );

            result = gvl_PQsendQueryPrepared(this->pgconn, pg_cstr_enc(name, paramsData.enc_idx), nParams,
                    (const char * const *)paramsData.values, paramsData.lengths, paramsData.formats,
                    resultFormat);

            free_query_params( &paramsData );

            if(result == 0)
                    pg_raise_conn_error( rb_eUnableToSend, self, "PQsendQueryPrepared %s", PQerrorMessage(this->pgconn));

            pgconn_wait_for_flush( self );
            return Qnil;
    }

server_version → Integer click to toggle source

Returns an integer representing the server version.

Applications might use this function to determine the version of the database server they are connected to. The result is formed by multiplying the server’s major version number by 10000 and adding the minor version number. For example, version 10.1 will be returned as 100001, and version 11.0 will be returned as 110000.

`PG::ConnectionBad` is raised if the connection is bad.

Prior to major version 10, PostgreSQL used three-part version numbers in which the first two parts together represented the major version. For those versions, PQserverVersion uses two digits for each part; for example version 9.1.5 will be returned as 90105, and version 9.2.0 will be returned as 90200.

Therefore, for purposes of determining feature compatibility, applications should divide the result of PQserverVersion by 100 not 10000 to determine a logical major version number. In all release series, only the last two digits differ between minor releases (bug-fix releases).

    static VALUE
    pgconn_server_version(VALUE self)
    {
            int server_version = PQserverVersion(pg_get_pgconn(self));
            if (server_version == 0) {
                    pg_raise_conn_error( rb_eConnectionBad, self, "PQserverVersion() can't get server version");
            }
            return INT2NUM(server_version);
    }

set_chunked_rows_mode → self click to toggle source

Select chunked mode for the currently-executing query.

This function is similar to `set_single_row_mode`, except that it specifies retrieval of up to `chunk_size` rows per PGresult, not necessarily just one row. This function can only be called immediately after `send_query` or one of its sibling functions, before any other operation on the connection such as `consume_input` or get_result. If called at the correct time, the function activates chunked mode for the current query. Otherwise the mode stays unchanged and the function raises an error. In any case, the mode reverts to normal after completion of the current query.

Example:

    conn.send_query( "your SQL command" )
    conn.set_chunked_rows_mode(10)
    loop do
      res = conn.get_result or break
      res.check
      res.each do |row|
        # do something with the received max. 10 rows
      end
    end

Available since PostgreSQL-17

    static VALUE
    pgconn_set_chunked_rows_mode(VALUE self, VALUE chunk_size)
    {
            PGconn *conn = pg_get_pgconn(self);

            rb_check_frozen(self);
            if( PQsetChunkedRowsMode(conn, NUM2INT(chunk_size)) == 0 )
                    pg_raise_conn_error( rb_ePGerror, self, "PQsetChunkedRowsMode %s", PQerrorMessage(conn));

            return self;
    }

set_client_encoding( encoding ) click to toggle source

Sets the client encoding to the encoding String.

    static VALUE
    pgconn_async_set_client_encoding(VALUE self, VALUE encname)
    {
            VALUE query_format, query;

            rb_check_frozen(self);
            Check_Type(encname, T_STRING);
            query_format = rb_str_new_cstr("set client_encoding to '%s'");
            query = rb_funcall(query_format, rb_intern("%"), 1, encname);

            pgconn_async_exec(1, &query, self);
            pgconn_set_internal_encoding_index( self );

            return Qnil;
    }

Also aliased as: async_set_client_encoding, client_encoding=
set_default_encoding() → Encoding click to toggle source

If Ruby has its Encoding.default_internal set, set PostgreSQL’s client_encoding to match. Returns the new Encoding, or `nil` if the default internal encoding wasn’t set.

    static VALUE
    pgconn_set_default_encoding( VALUE self )
    {
            PGconn *conn = pg_get_pgconn( self );
            rb_encoding *rb_enc;

            rb_check_frozen(self);
            if (( rb_enc = rb_default_internal_encoding() )) {
                    rb_encoding * conn_encoding = pg_conn_enc_get( conn );

                    /* Don't set the server encoding, if it's unnecessary.
                     * This is important for connection proxies, who disallow configuration settings.
                     */
                    if ( conn_encoding != rb_enc ) {
                            const char *encname = pg_get_rb_encoding_as_pg_encoding( rb_enc );
                            if ( pgconn_set_client_encoding_async(self, rb_str_new_cstr(encname)) != 0 )
                                    rb_warning( "Failed to set the default_internal encoding to %s: '%s'",
                                                                    encname, PQerrorMessage(conn) );
                    }
                    pgconn_set_internal_encoding_index( self );
                    return rb_enc_from_encoding( rb_enc );
            } else {
                    pgconn_set_internal_encoding_index( self );
                    return Qnil;
            }
    }

set_error_context_visibility( context_visibility ) → Integer click to toggle source

Sets connection’s context display mode to context_visibility and returns the previous setting. Available settings are:

- PQSHOW_CONTEXT_NEVER

- PQSHOW_CONTEXT_ERRORS

- PQSHOW_CONTEXT_ALWAYS

This mode controls whether the CONTEXT field is included in messages (unless the verbosity setting is TERSE, in which case CONTEXT is never shown). The NEVER mode never includes CONTEXT, while ALWAYS always includes it if available. In ERRORS mode (the default), CONTEXT fields are included only for error messages, not for notices and warnings.

Changing this mode does not affect the messages available from already-existing `PG::Result` objects, only subsequently-created ones. (But see `PG::Result#verbose_error_message` if you want to print a previous error with a different display mode.)

See also corresponding libpq function.

    static VALUE
    pgconn_set_error_context_visibility(VALUE self, VALUE in_context_visibility)
    {
            PGconn *conn = pg_get_pgconn(self);
            PGContextVisibility context_visibility = NUM2INT(in_context_visibility);
            return INT2FIX(PQsetErrorContextVisibility(conn, context_visibility));
    }

set_error_verbosity( verbosity ) → Integer click to toggle source

Sets connection’s verbosity to verbosity and returns the previous setting. Available settings are:

- PQERRORS_TERSE

- PQERRORS_DEFAULT

- PQERRORS_VERBOSE

- PQERRORS_SQLSTATE

Changing the verbosity does not affect the messages available from already-existing `PG::Result` objects, only subsequently-created ones. (But see `PG::Result#verbose_error_message` if you want to print a previous error with a different verbosity.)

See also corresponding libpq function.

    static VALUE
    pgconn_set_error_verbosity(VALUE self, VALUE in_verbosity)
    {
            PGconn *conn = pg_get_pgconn(self);
            PGVerbosity verbosity = NUM2INT(in_verbosity);
            return INT2FIX(PQsetErrorVerbosity(conn, verbosity));
    }

set_notice_processor {|message| ... } → Proc click to toggle source

See `set_notice_receiver` for the description of what this and the notice_processor methods do.

This function takes a new block to act as the notice processor and returns the Proc object previously set, or `nil` if it was previously the default. The block should accept a single String object.

If you pass no arguments, it will reset the handler to the default.

    static VALUE
    pgconn_set_notice_processor(VALUE self)
    {
            VALUE proc, old_proc;
            t_pg_connection *this = pg_get_connection_safe( self );

            rb_check_frozen(self);
            /* If default_notice_processor is unset, assume that the current
             * notice processor is the default, and save it to a global variable.
             * This should not be a problem because the default processor is
             * always the same, so won't vary among connections.
             */
            if(this->default_notice_processor == NULL)
                    this->default_notice_processor = PQsetNoticeProcessor(this->pgconn, NULL, NULL);

            old_proc = this->notice_processor;
            if( rb_block_given_p() ) {
                    proc = rb_block_proc();
                    PQsetNoticeProcessor(this->pgconn, gvl_notice_processor_proxy, (void *)self);
            } else {
                    /* if no block is given, set back to default */
                    proc = Qnil;
                    PQsetNoticeProcessor(this->pgconn, this->default_notice_processor, NULL);
            }

            RB_OBJ_WRITE(self, &this->notice_processor, proc);
            return old_proc;
    }

set_notice_receiver {|result| ... } → Proc click to toggle source

Notice and warning messages generated by the server are not returned by the query execution functions, since they do not imply failure of the query. Instead they are passed to a notice handling function, and execution continues normally after the handler returns. The default notice handling function prints the message on `stderr`, but the application can override this behavior by supplying its own handling function.

For historical reasons, there are two levels of notice handling, called the notice receiver and notice processor. The default behavior is for the notice receiver to format the notice and pass a string to the notice processor for printing. However, an application that chooses to provide its own notice receiver will typically ignore the notice processor layer and just do all the work in the notice receiver.

This function takes a new block to act as the handler, which should accept a single parameter that will be a `PG::Result` object, and returns the Proc object previously set, or `nil` if it was previously the default.

If you pass no arguments, it will reset the handler to the default.

Note: The `result` passed to the block should not be used outside of the block, since the corresponding C object could be freed after the block finishes.

    static VALUE
    pgconn_set_notice_receiver(VALUE self)
    {
            VALUE proc, old_proc;
            t_pg_connection *this = pg_get_connection_safe( self );

            rb_check_frozen(self);
            /* If default_notice_receiver is unset, assume that the current
             * notice receiver is the default, and save it to a global variable.
             * This should not be a problem because the default receiver is
             * always the same, so won't vary among connections.
             */
            if(this->default_notice_receiver == NULL)
                    this->default_notice_receiver = PQsetNoticeReceiver(this->pgconn, NULL, NULL);

            old_proc = this->notice_receiver;
            if( rb_block_given_p() ) {
                    proc = rb_block_proc();
                    PQsetNoticeReceiver(this->pgconn, gvl_notice_receiver_proxy, (void *)self);
            } else {
                    /* if no block is given, set back to default */
                    proc = Qnil;
                    PQsetNoticeReceiver(this->pgconn, this->default_notice_receiver, NULL);
            }

            RB_OBJ_WRITE(self, &this->notice_receiver, proc);
            return old_proc;
    }

set_single_row_mode → self click to toggle source

To enter single-row mode, call this method immediately after a successful call of `send_query` (or a sibling function). This mode selection is effective only for the currently executing query. Then call `Connection#get_result` repeatedly, until it returns nil.

Each (but the last) received Result has exactly one row and a Result#result_status of PGRES_SINGLE_TUPLE. The last Result has zero rows and is used to indicate a successful execution of the query. All of these Result objects will contain the same row description data (column names, types, etc) that an ordinary Result object for the query would have.

Caution: While processing a query, the server may return some rows and then encounter an error, causing the query to be aborted. Ordinarily, pg discards any such rows and reports only the error. But in single-row or chunked mode, some rows may have already been returned to the application. Hence, the application will see some PGRES_SINGLE_TUPLE or PGRES_TUPLES_CHUNK `PG::Result` objects followed by a `PG::Error` raised in get_result. For proper transactional behavior, the application must be designed to discard or undo whatever has been done with the previously-processed rows, if the query ultimately fails.

Example:

    conn.send_query( "your SQL command" )
    conn.set_single_row_mode
    loop do
      res = conn.get_result or break
      res.check
      res.each do |row|
        # do something with the received row
      end
    end

    static VALUE
    pgconn_set_single_row_mode(VALUE self)
    {
            PGconn *conn = pg_get_pgconn(self);

            rb_check_frozen(self);
            if( PQsetSingleRowMode(conn) == 0 )
                    pg_raise_conn_error( rb_ePGerror, self, "PQsetSingleRowMode %s", PQerrorMessage(conn));

            return self;
    }

setnonblocking(Boolean) → nil click to toggle source

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`.

    # File lib/pg/connection.rb, line 461
    def setnonblocking(enabled)
            singleton_class.async_send_api = !enabled
            self.flush_data = !enabled
            sync_setnonblocking(true)
    end

Also aliased as: async_setnonblocking
socket() → Integer click to toggle source

This method is deprecated. Please use the more portable method `socket_io` .

Returns the socket’s file descriptor for this connection. `IO.for_fd()` can be used to build a proper IO object to the socket. If you do so, you will likely also want to set `autoclose=false` on it to prevent Ruby from closing the socket to PostgreSQL if it goes out of scope. Alternatively, you can use `socket_io`, which creates an IO that’s associated with the connection object itself, and so won’t go out of scope until the connection does.

Note: On Windows the file descriptor is not usable, since it can not be used to build a Ruby IO object.

    static VALUE
    pgconn_socket(VALUE self)
    {
            int sd;
            pg_deprecated(4, ("conn.socket is deprecated and should be replaced by conn.socket_io"));

            if( (sd = PQsocket(pg_get_pgconn(self))) < 0)
                    pg_raise_conn_error( rb_eConnectionBad, self, "PQsocket() can't get socket descriptor");

            return INT2NUM(sd);
    }

socket_io() → IO click to toggle source

Fetch an IO object created from the Connection’s underlying socket. This object can be used per `socket_io.wait_readable`, `socket_io.wait_writable` or for `IO.select` to wait for events while running asynchronous API calls. `IO#wait_*able` is `Fiber.scheduler` compatible in contrast to `IO.select`.

The IO object can change while the connection is established, but is memorized afterwards. So be sure not to cache the IO object, but repeat calling `conn.socket_io` instead.

Using this method also works on Windows in contrast to using `socket` . It also avoids the problem of the underlying connection being closed by Ruby when an IO created using `IO.for_fd(conn.socket)` goes out of scope.

    static VALUE
    pgconn_socket_io(VALUE self)
    {
            t_pg_connection *this = pg_get_connection_safe( self );

            if ( !RTEST(this->socket_io) ) {
                    int sd;
                    if( (sd = PQsocket(this->pgconn)) < 0){
                            pg_raise_conn_error( rb_eConnectionBad, self, "PQsocket() can't get socket descriptor");
                    }
                    return pg_wrap_socket_io( sd, self, &this->socket_io, &this->ruby_sd);
            }

            return this->socket_io;
    }

ssl_attribute(attribute_name) → String click to toggle source

Returns SSL-related information about the connection.

The list of available attributes varies depending on the SSL library being used, and the type of connection. If an attribute is not available, returns nil.

The following attributes are commonly available:

`library`

  Name of the SSL implementation in use. (Currently, only “OpenSSL” is implemented)

`protocol`

  SSL/TLS version in use. Common values are “SSLv2”, “SSLv3”, “TLSv1”, “TLSv1.1” and “TLSv1.2”, but an implementation may return other strings if some other protocol is used.

`key_bits`

  Number of key bits used by the encryption algorithm.

`cipher`

  A short name of the ciphersuite used, e.g. “DHE-RSA-DES-CBC3-SHA”. The names are specific to each SSL implementation.

`compression`

  If SSL compression is in use, returns the name of the compression algorithm, or “on” if compression is used but the algorithm is not known. If compression is not in use, returns “off”.

See also `ssl_attribute_names` and the corresponding libpq function.

    static VALUE
    pgconn_ssl_attribute(VALUE self, VALUE attribute_name)
    {
            const char *p_attr;

            p_attr = PQsslAttribute(pg_get_pgconn(self), StringValueCStr(attribute_name));
            return p_attr ? rb_str_new_cstr(p_attr) : Qnil;
    }

ssl_attribute_names → Array<String> click to toggle source

Return an array of SSL attribute names available.

See also `ssl_attribute`

    static VALUE
    pgconn_ssl_attribute_names(VALUE self)
    {
            int i;
            const char * const * p_list = PQsslAttributeNames(pg_get_pgconn(self));
            VALUE ary = rb_ary_new();

            for ( i = 0; p_list[i]; i++ ) {
                    rb_ary_push( ary, rb_str_new_cstr( p_list[i] ));
            }
            return ary;
    }

ssl_attributes → Hash<String,String> click to toggle source

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`

    # File lib/pg/connection.rb, line 367
    def ssl_attributes
            ssl_attribute_names.each.with_object({}) do |n,h|
                    h[n] = ssl_attribute(n)
            end
    end

ssl_in_use? → Boolean click to toggle source

Returns `true` if the connection uses SSL/TLS, `false` if not.

    static VALUE
    pgconn_ssl_in_use(VALUE self)
    {
            return PQsslInUse(pg_get_pgconn(self)) ? Qtrue : Qfalse;
    }

status() click to toggle source

Returns the status of the connection, which is one:

    PG::Constants::CONNECTION_OK
    PG::Constants::CONNECTION_BAD

… and other constants of kind PG::Constants::CONNECTION_*

This method returns the status of the last command from memory. It doesn’t do any socket access hence is not suitable to test the connectivity. See `check_socket` for a way to verify the socket state.

Example:

    PG.constants.grep(/CONNECTION_/).find{|c| PG.const_get(c) == conn.status} # => :CONNECTION_OK

    static VALUE
    pgconn_status(VALUE self)
    {
            return INT2NUM(PQstatus(pg_get_pgconn(self)));
    }

sync_cancel() click to toggle source

    HAVE_PQSETCHUNKEDROWSMODE
    static VALUE
    pgconn_sync_cancel(VALUE self)
    {
            char errbuf[256];
            PGcancel *cancel;
            VALUE retval;
            int ret;

            cancel = PQgetCancel(pg_get_pgconn(self));
            if(cancel == NULL)
                    pg_raise_conn_error( rb_ePGerror, self, "Invalid connection!");

            ret = gvl_PQcancel(cancel, errbuf, sizeof(errbuf));
            if(ret == 1)
                    retval = Qnil;
            else
                    retval = rb_str_new2(errbuf);

            PQfreeCancel(cancel);
            return retval;
    }

sync_close_portal( portal_name ) → PG::Result click to toggle source

This function has the same behavior as `async_close_portal`, but is implemented using the synchronous command processing API of libpq. See `async_exec` for the differences between the two API variants. It’s not recommended to use explicit sync or async variants but `close_portal` instead, unless you have a good reason to do so.

Available since PostgreSQL-17.

    static VALUE
    pgconn_sync_close_portal(VALUE self, VALUE stmt_name)
    {
            return pgconn_sync_describe_close_prepared_portal(self, stmt_name, gvl_PQclosePortal);
    }

sync_close_prepared( stmt_name ) → PG::Result click to toggle source

This function has the same behavior as `async_close_prepared`, but is implemented using the synchronous command processing API of libpq. See `async_exec` for the differences between the two API variants. It’s not recommended to use explicit sync or async variants but `close_prepared` instead, unless you have a good reason to do so.

Available since PostgreSQL-17.

    static VALUE
    pgconn_sync_close_prepared(VALUE self, VALUE stmt_name)
    {
            return pgconn_sync_describe_close_prepared_portal(self, stmt_name, gvl_PQclosePrepared);
    }

sync_describe_portal( portal_name ) → PG::Result click to toggle source

This function has the same behavior as `async_describe_portal`, but is implemented using the synchronous command processing API of libpq. See `async_exec` for the differences between the two API variants. It’s not recommended to use explicit sync or async variants but `describe_portal` instead, unless you have a good reason to do so.

    static VALUE
    pgconn_sync_describe_portal(VALUE self, VALUE stmt_name)
    {
            return pgconn_sync_describe_close_prepared_portal(self, stmt_name, gvl_PQdescribePortal);
    }

sync_describe_prepared( statement_name ) → PG::Result click to toggle source

This function has the same behavior as `async_describe_prepared`, but is implemented using the synchronous command processing API of libpq. See `async_exec` for the differences between the two API variants. It’s not recommended to use explicit sync or async variants but `describe_prepared` instead, unless you have a good reason to do so.

    static VALUE
    pgconn_sync_describe_prepared(VALUE self, VALUE stmt_name)
    {
            return pgconn_sync_describe_close_prepared_portal(self, stmt_name, gvl_PQdescribePrepared);
    }

sync_encrypt_password(p1, p2, p3 = v3) click to toggle source

    static VALUE
    pgconn_sync_encrypt_password(int argc, VALUE *argv, VALUE self)
    {
            char *encrypted = NULL;
            VALUE rval = Qnil;
            VALUE password, username, algorithm;
            PGconn *conn = pg_get_pgconn(self);

            rb_scan_args( argc, argv, "21", &password, &username, &algorithm );

            Check_Type(password, T_STRING);
            Check_Type(username, T_STRING);

            encrypted = gvl_PQencryptPasswordConn(conn, StringValueCStr(password), StringValueCStr(username), RTEST(algorithm) ? StringValueCStr(algorithm) : NULL);
            if ( encrypted ) {
                    rval = rb_str_new2( encrypted );
                    PQfreemem( encrypted );
            } else {
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(conn));
            }

            return rval;
    }

sync_exec(sql) → PG::Result click to toggle source
sync_exec(sql) {|pg_result| block }

This function has the same behavior as `async_exec`, but is implemented using the synchronous command processing API of libpq. It’s not recommended to use explicit sync or async variants but `exec` instead, unless you have a good reason to do so.

Both `sync_exec` and `async_exec` release the GVL while waiting for server response, so that concurrent threads will get executed. However `async_exec` has two advantages:

1. `async_exec` can be aborted by signals (like Ctrl-C), while `exec` blocks signal processing until the query is answered.

2. Ruby VM gets notified about IO blocked operations and can pass them through `Fiber.scheduler`. So only `async_*` methods are compatible to event based schedulers like the async gem.

    static VALUE
    pgconn_sync_exec(int argc, VALUE *argv, VALUE self)
    {
            t_pg_connection *this = pg_get_connection_safe( self );
            PGresult *result = NULL;
            VALUE rb_pgresult;

            /* If called with no or nil parameters, use PQexec for compatibility */
            if ( argc == 1 || (argc >= 2 && argc <= 4 && NIL_P(argv[1]) )) {
                    VALUE query_str = argv[0];

                    result = gvl_PQexec(this->pgconn, pg_cstr_enc(query_str, this->enc_idx));
                    rb_pgresult = pg_new_result(result, self);
                    pg_result_check(rb_pgresult);
                    if (rb_block_given_p()) {
                            return rb_ensure(rb_yield, rb_pgresult, pg_result_clear, rb_pgresult);
                    }
                    return rb_pgresult;
            }
            pg_deprecated(0, ("forwarding exec to exec_params is deprecated"));

            /* Otherwise, just call #exec_params instead for backward-compatibility */
            return pgconn_sync_exec_params( argc, argv, self );

    }

sync_exec_params(sql, params[, result_format[, type_map]] ) → PG::Result click to toggle source
sync_exec_params(sql, params[, result_format[, type_map]] ) {|pg_result| block }

This function has the same behavior as `async_exec_params`, but is implemented using the synchronous command processing API of libpq. See `async_exec` for the differences between the two API variants. It’s not recommended to use explicit sync or async variants but `exec_params` instead, unless you have a good reason to do so.

    static VALUE
    pgconn_sync_exec_params( int argc, VALUE *argv, VALUE self )
    {
            t_pg_connection *this = pg_get_connection_safe( self );
            PGresult *result = NULL;
            VALUE rb_pgresult;
            VALUE command, in_res_fmt;
            int nParams;
            int resultFormat;
            struct query_params_data paramsData = { this->enc_idx };

            /* For compatibility we accept 1 to 4 parameters */
            rb_scan_args(argc, argv, "13", &command, &paramsData.params, &in_res_fmt, &paramsData.typemap);
            paramsData.with_types = 1;

            /*
             * For backward compatibility no or +nil+ for the second parameter
             * is passed to #exec
             */
            if ( NIL_P(paramsData.params) ) {
                    pg_deprecated(1, ("forwarding exec_params to exec is deprecated"));
                    return pgconn_sync_exec( 1, argv, self );
            }
            pgconn_query_assign_typemap( self, &paramsData );

            resultFormat = NIL_P(in_res_fmt) ? 0 : NUM2INT(in_res_fmt);
            nParams = alloc_query_params( &paramsData );

            result = gvl_PQexecParams(this->pgconn, pg_cstr_enc(command, paramsData.enc_idx), nParams, paramsData.types,
                    (const char * const *)paramsData.values, paramsData.lengths, paramsData.formats, resultFormat);

            free_query_params( &paramsData );

            rb_pgresult = pg_new_result(result, self);
            pg_result_check(rb_pgresult);

            if (rb_block_given_p()) {
                    return rb_ensure(rb_yield, rb_pgresult, pg_result_clear, rb_pgresult);
            }

            return rb_pgresult;
    }

sync_exec_prepared(statement_name [, params, result_format[, type_map]] ) → PG::Result click to toggle source
sync_exec_prepared(statement_name [, params, result_format[, type_map]] ) {|pg_result| block }

This function has the same behavior as `async_exec_prepared`, but is implemented using the synchronous command processing API of libpq. See `async_exec` for the differences between the two API variants. It’s not recommended to use explicit sync or async variants but `exec_prepared` instead, unless you have a good reason to do so.

    static VALUE
    pgconn_sync_exec_prepared(int argc, VALUE *argv, VALUE self)
    {
            t_pg_connection *this = pg_get_connection_safe( self );
            PGresult *result = NULL;
            VALUE rb_pgresult;
            VALUE name, in_res_fmt;
            int nParams;
            int resultFormat;
            struct query_params_data paramsData = { this->enc_idx };

            rb_scan_args(argc, argv, "13", &name, &paramsData.params, &in_res_fmt, &paramsData.typemap);
            paramsData.with_types = 0;

            if(NIL_P(paramsData.params)) {
                    paramsData.params = rb_ary_new2(0);
            }
            pgconn_query_assign_typemap( self, &paramsData );

            resultFormat = NIL_P(in_res_fmt) ? 0 : NUM2INT(in_res_fmt);
            nParams = alloc_query_params( &paramsData );

            result = gvl_PQexecPrepared(this->pgconn, pg_cstr_enc(name, paramsData.enc_idx), nParams,
                    (const char * const *)paramsData.values, paramsData.lengths, paramsData.formats,
                    resultFormat);

            free_query_params( &paramsData );

            rb_pgresult = pg_new_result(result, self);
            pg_result_check(rb_pgresult);
            if (rb_block_given_p()) {
                    return rb_ensure(rb_yield, rb_pgresult,
                            pg_result_clear, rb_pgresult);
            }
            return rb_pgresult;
    }

sync_flush() click to toggle source

    static VALUE
    pgconn_sync_flush(VALUE self)
    {
            PGconn *conn = pg_get_pgconn(self);
            int ret = PQflush(conn);
            if(ret == -1)
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(conn));

            return (ret) ? Qfalse : Qtrue;
    }

sync_get_copy_data(p1 = v1, p2 = v2) click to toggle source

    static VALUE
    pgconn_sync_get_copy_data(int argc, VALUE *argv, VALUE self )
    {
            VALUE async_in;
            VALUE result;
            int ret;
            char *buffer;
            VALUE decoder;
            t_pg_coder *p_coder = NULL;
            t_pg_connection *this = pg_get_connection_safe( self );

            rb_scan_args(argc, argv, "02", &async_in, &decoder);

            if( NIL_P(decoder) ){
                    if( !NIL_P(this->decoder_for_get_copy_data) ){
                            p_coder = RTYPEDDATA_DATA( this->decoder_for_get_copy_data );
                    }
            } else {
                    /* Check argument type and use argument decoder */
                    TypedData_Get_Struct(decoder, t_pg_coder, &pg_coder_type, p_coder);
            }

            ret = gvl_PQgetCopyData(this->pgconn, &buffer, RTEST(async_in));
            if(ret == -2){ /* error */
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(this->pgconn));
            }
            if(ret == -1) { /* No data left */
                    return Qnil;
            }
            if(ret == 0) { /* would block */
                    return Qfalse;
            }

            if( p_coder ){
                    t_pg_coder_dec_func dec_func = pg_coder_dec_func( p_coder, p_coder->format );
                    result =  dec_func( p_coder, buffer, ret, 0, 0, this->enc_idx );
            } else {
                    result = rb_str_new(buffer, ret);
            }

            PQfreemem(buffer);
            return result;
    }

sync_get_last_result( ) → PG::Result click to toggle source

This function has the same behavior as `async_get_last_result`, but is implemented using the synchronous command processing API of libpq. See `async_exec` for the differences between the two API variants. It’s not recommended to use explicit sync or async variants but `get_last_result` instead, unless you have a good reason to do so.

    static VALUE
    pgconn_sync_get_last_result(VALUE self)
    {
            PGconn *conn = pg_get_pgconn(self);
            VALUE rb_pgresult = Qnil;
            PGresult *cur, *prev;

            cur = prev = NULL;
            while ((cur = gvl_PQgetResult(conn)) != NULL) {
                    int status;

                    if (prev) PQclear(prev);
                    prev = cur;

                    status = PQresultStatus(cur);
                    if (status == PGRES_COPY_OUT || status == PGRES_COPY_IN || status == PGRES_COPY_BOTH)
                            break;
            }

            if (prev) {
                    rb_pgresult = pg_new_result( prev, self );
                    pg_result_check(rb_pgresult);
            }

            return rb_pgresult;
    }

sync_get_result() click to toggle source

    endif

    static VALUE
    pgconn_sync_get_result(VALUE self)
    {
            PGconn *conn = pg_get_pgconn(self);
            PGresult *result;
            VALUE rb_pgresult;

            result = gvl_PQgetResult(conn);
            if(result == NULL)
                    return Qnil;
            rb_pgresult = pg_new_result(result, self);
            if (rb_block_given_p()) {
                    return rb_ensure(rb_yield, rb_pgresult,
                            pg_result_clear, rb_pgresult);
            }
            return rb_pgresult;
    }

sync_isnonblocking() click to toggle source

    static VALUE
    pgconn_sync_isnonblocking(VALUE self)
    {
            return PQisnonblocking(pg_get_pgconn(self)) ? Qtrue : Qfalse;
    }

sync_pipeline_sync → nil click to toggle source

This function has the same behavior as `async_pipeline_sync`, but is implemented using the synchronous command processing API of libpq. See `async_exec` for the differences between the two API variants. It’s not recommended to use explicit sync or async variants but `pipeline_sync` instead, unless you have a good reason to do so.

Available since PostgreSQL-14

    static VALUE
    pgconn_sync_pipeline_sync(VALUE self)
    {
            PGconn *conn = pg_get_pgconn(self);
            int res = gvl_PQpipelineSync(conn);
            if( res != 1 )
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(conn));

            return Qnil;
    }

sync_prepare(stmt_name, sql [, param_types ] ) → PG::Result click to toggle source

This function has the same behavior as `async_prepare`, but is implemented using the synchronous command processing API of libpq. See `async_exec` for the differences between the two API variants. It’s not recommended to use explicit sync or async variants but `prepare` instead, unless you have a good reason to do so.

    static VALUE
    pgconn_sync_prepare(int argc, VALUE *argv, VALUE self)
    {
            t_pg_connection *this = pg_get_connection_safe( self );
            PGresult *result = NULL;
            VALUE rb_pgresult;
            VALUE name, command, in_paramtypes;
            VALUE param;
            int i = 0;
            int nParams = 0;
            Oid *paramTypes = NULL;
            const char *name_cstr;
            const char *command_cstr;
            int enc_idx = this->enc_idx;

            rb_scan_args(argc, argv, "21", &name, &command, &in_paramtypes);
            name_cstr = pg_cstr_enc(name, enc_idx);
            command_cstr = pg_cstr_enc(command, enc_idx);

            if(! NIL_P(in_paramtypes)) {
                    Check_Type(in_paramtypes, T_ARRAY);
                    nParams = (int)RARRAY_LEN(in_paramtypes);
                    paramTypes = ALLOC_N(Oid, nParams);
                    for(i = 0; i < nParams; i++) {
                            param = rb_ary_entry(in_paramtypes, i);
                            if(param == Qnil)
                                    paramTypes[i] = 0;
                            else
                                    paramTypes[i] = NUM2UINT(param);
                    }
            }
            result = gvl_PQprepare(this->pgconn, name_cstr, command_cstr, nParams, paramTypes);

            xfree(paramTypes);

            rb_pgresult = pg_new_result(result, self);
            pg_result_check(rb_pgresult);
            return rb_pgresult;
    }

sync_put_copy_data(p1, p2 = v2) click to toggle source

    static VALUE
    pgconn_sync_put_copy_data(int argc, VALUE *argv, VALUE self)
    {
            int ret;
            int len;
            t_pg_connection *this = pg_get_connection_safe( self );
            VALUE value;
            VALUE buffer = Qnil;
            VALUE encoder;
            VALUE intermediate = Qnil;
            t_pg_coder *p_coder = NULL;

            rb_scan_args( argc, argv, "11", &value, &encoder );

            if( NIL_P(encoder) ){
                    if( NIL_P(this->encoder_for_put_copy_data) ){
                            buffer = value;
                    } else {
                            p_coder = RTYPEDDATA_DATA( this->encoder_for_put_copy_data );
                    }
            } else {
                    /* Check argument type and use argument encoder */
                    TypedData_Get_Struct(encoder, t_pg_coder, &pg_coder_type, p_coder);
            }

            if( p_coder ){
                    t_pg_coder_enc_func enc_func;
                    int enc_idx = this->enc_idx;

                    enc_func = pg_coder_enc_func( p_coder );
                    len = enc_func( p_coder, value, NULL, &intermediate, enc_idx);

                    if( len == -1 ){
                            /* The intermediate value is a String that can be used directly. */
                            buffer = intermediate;
                    } else {
                            buffer = rb_str_new(NULL, len);
                            len = enc_func( p_coder, value, RSTRING_PTR(buffer), &intermediate, enc_idx);
                            rb_str_set_len( buffer, len );
                    }
            }

            Check_Type(buffer, T_STRING);

            ret = gvl_PQputCopyData(this->pgconn, RSTRING_PTR(buffer), RSTRING_LENINT(buffer));
            if(ret == -1)
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(this->pgconn));

            RB_GC_GUARD(buffer);

            return (ret) ? Qtrue : Qfalse;
    }

sync_put_copy_end(p1 = v1) click to toggle source

    static VALUE
    pgconn_sync_put_copy_end(int argc, VALUE *argv, VALUE self)
    {
            VALUE str;
            int ret;
            const char *error_message = NULL;
            t_pg_connection *this = pg_get_connection_safe( self );

            if (rb_scan_args(argc, argv, "01", &str) == 0)
                    error_message = NULL;
            else
                    error_message = pg_cstr_enc(str, this->enc_idx);

            ret = gvl_PQputCopyEnd(this->pgconn, error_message);
            if(ret == -1)
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(this->pgconn));

            return (ret) ? Qtrue : Qfalse;
    }

sync_reset() click to toggle source

    static VALUE
    pgconn_sync_reset( VALUE self )
    {
            pgconn_close_socket_io( self );
            gvl_PQreset( pg_get_pgconn(self) );
            return self;
    }

sync_set_client_encoding( encoding ) click to toggle source

This function has the same behavior as `async_set_client_encoding`, but is implemented using the synchronous command processing API of libpq. See `async_exec` for the differences between the two API variants. It’s not recommended to use explicit sync or async variants but `set_client_encoding` instead, unless you have a good reason to do so.

    static VALUE
    pgconn_sync_set_client_encoding(VALUE self, VALUE str)
    {
            PGconn *conn = pg_get_pgconn( self );

            rb_check_frozen(self);
            Check_Type(str, T_STRING);

            if ( (gvl_PQsetClientEncoding(conn, StringValueCStr(str))) == -1 )
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(conn));

            pgconn_set_internal_encoding_index( self );

            return Qnil;
    }

sync_setnonblocking(p1) click to toggle source

    static VALUE
    pgconn_sync_setnonblocking(VALUE self, VALUE state)
    {
            int arg;
            PGconn *conn = pg_get_pgconn(self);
            rb_check_frozen(self);
            if(state == Qtrue)
                    arg = 1;
            else if (state == Qfalse)
                    arg = 0;
            else
                    rb_raise(rb_eArgError, "Boolean value expected");

            if(PQsetnonblocking(conn, arg) == -1)
                    pg_raise_conn_error( rb_ePGerror, self, "%s", PQerrorMessage(conn));

            return Qnil;
    }

trace( stream ) → nil click to toggle source

Enables tracing message passing between backend. The trace message will be written to the stream stream, which must implement a method `fileno` that returns a writable file descriptor.

    static VALUE
    pgconn_trace(VALUE self, VALUE stream)
    {
            VALUE fileno;
            FILE *new_fp;
            int old_fd, new_fd;
            VALUE new_file;
            t_pg_connection *this = pg_get_connection_safe( self );

            rb_check_frozen(self);
            if(!rb_respond_to(stream,rb_intern("fileno")))
                    rb_raise(rb_eArgError, "stream does not respond to method: fileno");

            fileno = rb_funcall(stream, rb_intern("fileno"), 0);
            if(fileno == Qnil)
                    rb_raise(rb_eArgError, "can't get file descriptor from stream");

            /* Duplicate the file descriptor and re-open
             * it. Then, make it into a ruby File object
             * and assign it to an instance variable.
             * This prevents a problem when the File
             * object passed to this function is closed
             * before the connection object is. */
            old_fd = NUM2INT(fileno);
            new_fd = dup(old_fd);
            new_fp = fdopen(new_fd, "w");

            if(new_fp == NULL)
                    rb_raise(rb_eArgError, "stream is not writable");

            new_file = rb_funcall(rb_cIO, rb_intern("new"), 1, INT2NUM(new_fd));
            RB_OBJ_WRITE(self, &this->trace_stream, new_file);

            PQtrace(this->pgconn, new_fp);
            return Qnil;
    }

transaction { |conn| ... } → result of the block click to toggle source

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

    # File lib/pg/connection.rb, line 307
    def transaction
            rollback = false
            exec "BEGIN"
            yield(self)
    rescue PG::RollbackTransaction
            rollback = true
            cancel if transaction_status == PG::PQTRANS_ACTIVE
            block
            exec "ROLLBACK"
    rescue Exception
            rollback = true
            cancel if transaction_status == PG::PQTRANS_ACTIVE
            block
            exec "ROLLBACK"
            raise
    ensure
            exec "COMMIT" unless rollback
    end

transaction_status() click to toggle source

returns one of the following statuses:

    PQTRANS_IDLE    = 0 (connection idle)
    PQTRANS_ACTIVE  = 1 (command in progress)
    PQTRANS_INTRANS = 2 (idle, within transaction block)
    PQTRANS_INERROR = 3 (idle, within failed transaction)
    PQTRANS_UNKNOWN = 4 (cannot determine status)

    static VALUE
    pgconn_transaction_status(VALUE self)
    {
            return INT2NUM(PQtransactionStatus(pg_get_pgconn(self)));
    }

tty() click to toggle source

Obsolete function.

    static VALUE
    pgconn_tty(VALUE self)
    {
            return rb_str_new2("");
    }

type_map_for_queries → TypeMap click to toggle source

Returns the default TypeMap that is currently set for type casts of query bind parameters.

Default is `PG::TypeMapAllStrings` .

See also `type_map_for_queries=`

    static VALUE
    pgconn_type_map_for_queries_get(VALUE self)
    {
            t_pg_connection *this = pg_get_connection( self );

            return this->type_map_for_queries;
    }

type_map_for_queries = typemap click to toggle source

Set the default TypeMap that is used for type casts of query bind parameters. It can be overwritten per `type_map` parameter of `exec_params` and siblings.

`typemap` must be a kind of `PG::TypeMap` .

See also `type_map_for_queries`

    static VALUE
    pgconn_type_map_for_queries_set(VALUE self, VALUE typemap)
    {
            t_pg_connection *this = pg_get_connection( self );
            t_typemap *tm;
            UNUSED(tm);

            rb_check_frozen(self);
            /* Check type of method param */
            TypedData_Get_Struct(typemap, t_typemap, &pg_typemap_type, tm);

            RB_OBJ_WRITE(self, &this->type_map_for_queries, typemap);

            return typemap;
    }

type_map_for_results → TypeMap click to toggle source

Returns the default TypeMap that is currently set for type casts of result values.

Default is `PG::TypeMapAllStrings` .

See also `type_map_for_results=`

    static VALUE
    pgconn_type_map_for_results_get(VALUE self)
    {
            t_pg_connection *this = pg_get_connection( self );

            return this->type_map_for_results;
    }

type_map_for_results = typemap click to toggle source

Set the default TypeMap that is used for type casts of result values. It can be overwritten per `PG::Result#type_map=` .

`typemap` must be a kind of `PG::TypeMap` .

See also `type_map_for_results`

    static VALUE
    pgconn_type_map_for_results_set(VALUE self, VALUE typemap)
    {
            t_pg_connection *this = pg_get_connection( self );
            t_typemap *tm;
            UNUSED(tm);

            rb_check_frozen(self);
            TypedData_Get_Struct(typemap, t_typemap, &pg_typemap_type, tm);
            RB_OBJ_WRITE(self, &this->type_map_for_results, typemap);

            return typemap;
    }

PG::Connection.unescape_bytea( string ) click to toggle source

Converts an escaped string representation of binary data into binary data — the reverse of `escape_bytea`. This is needed when retrieving `bytea` data in text format, but not when retrieving it in binary format.

    static VALUE
    pgconn_s_unescape_bytea(VALUE self, VALUE str)
    {
            unsigned char *from, *to;
            size_t to_len;
            VALUE ret;

            UNUSED( self );

            Check_Type(str, T_STRING);
            from = (unsigned char*)StringValueCStr(str);

            to = PQunescapeBytea(from, &to_len);

            ret = rb_str_new((char*)to, to_len);
            PQfreemem(to);
            return ret;
    }

Also aliased as: unescape_bytea
untrace() → nil click to toggle source

Disables the message tracing.

    static VALUE
    pgconn_untrace(VALUE self)
    {
            t_pg_connection *this = pg_get_connection_safe( self );

            PQuntrace(this->pgconn);
            rb_funcall(this->trace_stream, rb_intern("close"), 0);
            RB_OBJ_WRITE(self, &this->trace_stream, Qnil);
            return Qnil;
    }

user() click to toggle source

Returns the authenticated user name.

    static VALUE
    pgconn_user(VALUE self)
    {
            char *user = PQuser(pg_get_pgconn(self));
            if (!user) return Qnil;
            return rb_str_new2(user);
    }

wait_for_notify( [ timeout ] ) { |event, pid, payload| block } → String click to toggle source

Blocks while waiting for notification(s), or until the optional timeout is reached, whichever comes first. timeout is measured in seconds and can be fractional.

Returns `nil` if timeout is reached, the name of the NOTIFY event otherwise. If used in block form, passes the name of the NOTIFY `event`, the generating `pid` and the optional `payload` string into the block.

    static VALUE
    pgconn_wait_for_notify(int argc, VALUE *argv, VALUE self)
    {
            t_pg_connection *this = pg_get_connection_safe( self );
            PGnotify *pnotification;
            struct timeval timeout;
            struct timeval *ptimeout = NULL;
            VALUE timeout_in = Qnil, relname = Qnil, be_pid = Qnil, extra = Qnil;
            double timeout_sec;

            rb_scan_args( argc, argv, "01", &timeout_in );

            if ( RTEST(timeout_in) ) {
                    timeout_sec = NUM2DBL( timeout_in );
                    timeout.tv_sec = (time_t)timeout_sec;
                    timeout.tv_usec = (suseconds_t)( (timeout_sec - (long)timeout_sec) * 1e6 );
                    ptimeout = &timeout;
            }

            pnotification = (PGnotify*) wait_socket_readable( self, ptimeout, notify_readable);

            /* Return nil if the select timed out */
            if ( !pnotification ) return Qnil;

            relname = rb_str_new2( pnotification->relname );
            PG_ENCODING_SET_NOCHECK( relname, this->enc_idx );
            be_pid = INT2NUM( pnotification->be_pid );
            if ( *pnotification->extra ) {
                    extra = rb_str_new2( pnotification->extra );
                    PG_ENCODING_SET_NOCHECK( extra, this->enc_idx );
            }
            PQfreemem( pnotification );

            if ( rb_block_given_p() )
                    rb_yield_values( 3, relname, be_pid, extra );

            return relname;
    }

Also aliased as: notifies_wait