Class: PG::Connection
- Inherits:
-
Object
- Object
- PG::Connection
- Includes:
- Constants
- Defined in:
- lib/pg/connection.rb,
ext/pg_connection.c
Overview
The PostgreSQL connection class. The interface for this class is based on libpq, the C application programmer’s interface to PostgreSQL. Some familiarity with libpq is recommended, but not necessary.
For example, to send query to the database on the localhost:
require 'pg'
conn = PG::Connection.open(:dbname => 'test')
res = conn.exec_params('SELECT $1 AS a, $2 AS b, $3 AS c', [1, 2, nil])
# Equivalent to:
# res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
See the PG::Result class for information on working with the results of a query.
Constant Summary collapse
- CONNECT_ARGUMENT_ORDER =
The order the options are passed to the ::connect method.
%w[host port options tty dbname user password]
- REDIRECT_METHODS =
{ :exec => [:async_exec, :sync_exec], :query => [:async_exec, :sync_exec], :exec_params => [:async_exec_params, :sync_exec_params], :prepare => [:async_prepare, :sync_prepare], :exec_prepared => [:async_exec_prepared, :sync_exec_prepared], :describe_portal => [:async_describe_portal, :sync_describe_portal], :describe_prepared => [:async_describe_prepared, :sync_describe_prepared], }
Constants included from Constants
PG::Constants::CONNECTION_AUTH_OK, PG::Constants::CONNECTION_AWAITING_RESPONSE, PG::Constants::CONNECTION_BAD, PG::Constants::CONNECTION_MADE, PG::Constants::CONNECTION_NEEDED, PG::Constants::CONNECTION_OK, PG::Constants::CONNECTION_SETENV, PG::Constants::CONNECTION_SSL_STARTUP, PG::Constants::CONNECTION_STARTED, PG::Constants::INVALID_OID, PG::Constants::INV_READ, PG::Constants::INV_WRITE, PG::Constants::InvalidOid, PG::Constants::PGRES_BAD_RESPONSE, PG::Constants::PGRES_COMMAND_OK, PG::Constants::PGRES_COPY_BOTH, PG::Constants::PGRES_COPY_IN, PG::Constants::PGRES_COPY_OUT, PG::Constants::PGRES_EMPTY_QUERY, PG::Constants::PGRES_FATAL_ERROR, PG::Constants::PGRES_NONFATAL_ERROR, PG::Constants::PGRES_POLLING_FAILED, PG::Constants::PGRES_POLLING_OK, PG::Constants::PGRES_POLLING_READING, PG::Constants::PGRES_POLLING_WRITING, PG::Constants::PGRES_SINGLE_TUPLE, PG::Constants::PGRES_TUPLES_OK, PG::Constants::PG_DIAG_COLUMN_NAME, PG::Constants::PG_DIAG_CONSTRAINT_NAME, PG::Constants::PG_DIAG_CONTEXT, PG::Constants::PG_DIAG_DATATYPE_NAME, PG::Constants::PG_DIAG_INTERNAL_POSITION, PG::Constants::PG_DIAG_INTERNAL_QUERY, PG::Constants::PG_DIAG_MESSAGE_DETAIL, PG::Constants::PG_DIAG_MESSAGE_HINT, PG::Constants::PG_DIAG_MESSAGE_PRIMARY, PG::Constants::PG_DIAG_SCHEMA_NAME, PG::Constants::PG_DIAG_SEVERITY, PG::Constants::PG_DIAG_SEVERITY_NONLOCALIZED, PG::Constants::PG_DIAG_SOURCE_FILE, PG::Constants::PG_DIAG_SOURCE_FUNCTION, PG::Constants::PG_DIAG_SOURCE_LINE, PG::Constants::PG_DIAG_SQLSTATE, PG::Constants::PG_DIAG_STATEMENT_POSITION, PG::Constants::PG_DIAG_TABLE_NAME, PG::Constants::PQERRORS_DEFAULT, PG::Constants::PQERRORS_SQLSTATE, PG::Constants::PQERRORS_TERSE, PG::Constants::PQERRORS_VERBOSE, PG::Constants::PQPING_NO_ATTEMPT, PG::Constants::PQPING_NO_RESPONSE, PG::Constants::PQPING_OK, PG::Constants::PQPING_REJECT, PG::Constants::PQSHOW_CONTEXT_ALWAYS, PG::Constants::PQSHOW_CONTEXT_ERRORS, PG::Constants::PQSHOW_CONTEXT_NEVER, PG::Constants::PQTRANS_ACTIVE, PG::Constants::PQTRANS_IDLE, PG::Constants::PQTRANS_INERROR, PG::Constants::PQTRANS_INTRANS, PG::Constants::PQTRANS_UNKNOWN, PG::Constants::SEEK_CUR, PG::Constants::SEEK_END, PG::Constants::SEEK_SET
Class Method Summary collapse
- .async_api=(enable) ⇒ Object
-
.conndefaults ⇒ Object
call-seq: PG::Connection.conndefaults() -> Array.
-
.conndefaults_hash ⇒ Object
Return the Postgres connection defaults structure as a Hash keyed by option keyword (as a Symbol).
-
.connect_start(*args) ⇒ Object
This is an asynchronous version of PG::Connection.new.
-
.PG::Connection.encrypt_password(password, username) ⇒ String
This is an older, deprecated version of #encrypt_password.
-
.escape_bytea(string) ⇒ String
Escapes binary data for use within an SQL command with the type
bytea
. -
.escape_string(str) ⇒ String
Returns a SQL-safe version of the String str.
-
.parse_connect_args(*args) ⇒ Object
Parse the connection
args
into a connection-parameter string. -
.ping(*args) ⇒ Object
Check server status.
-
.quote_connstr(value) ⇒ Object
Quote the given
value
for use in a connection-parameter string. -
.quote_ident(str_or_array) ⇒ Object
Returns a string that is safe for inclusion in a SQL query as an identifier.
-
.PG::Connection.unescape_bytea(string) ⇒ Object
Converts an escaped string representation of binary data into binary data — the reverse of #escape_bytea.
Instance Method Summary collapse
-
#backend_pid ⇒ Integer
Returns the process ID of the backend server process for this connection.
-
#block([ timeout ]) ⇒ Boolean
Blocks until the server is no longer busy, or until the optional timeout is reached, whichever comes first.
-
#cancel ⇒ String
Requests cancellation of the command currently being processed.
-
#conndefaults ⇒ Object
Returns an array of Hashes with connection defaults.
-
#conndefaults_hash ⇒ Object
Returns a Hash with connection defaults.
-
#connect_poll ⇒ Integer
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. -
#connection_needs_password ⇒ Boolean
Returns
true
if the authentication method required a password, but none was available. -
#connection_used_password ⇒ Boolean
Returns
true
if the authentication method used a caller-supplied password,false
otherwise. -
#conninfo ⇒ Hash
Returns the connection options used by a live connection.
-
#conninfo_hash ⇒ Object
Return the Postgres connection info structure as a Hash keyed by option keyword (as a Symbol).
-
#consume_input ⇒ Object
If input is available from the server, consume it.
-
#copy_data(sql, coder = nil) ⇒ Object
call-seq: conn.copy_data( sql [, coder] ) {|sql_result| … } -> PG::Result.
-
#db ⇒ Object
Returns the connected database name.
-
#decoder_for_get_copy_data ⇒ PG::Coder
Returns the default coder object that is currently set for type casting of received data by #get_copy_data .
-
#decoder_for_get_copy_data=(decoder) ⇒ Object
Set the default coder that is used for type casting of received data by #get_copy_data .
-
#describe_portal(portal_name) ⇒ PG::Result
(also: #async_describe_portal)
Retrieve information about the portal portal_name.
-
#describe_prepared(statement_name) ⇒ PG::Result
(also: #async_describe_prepared)
Retrieve information about the prepared statement statement_name.
-
#discard_results ⇒ Object
Silently discard any prior query result that application didn’t eat.
-
#encoder_for_put_copy_data ⇒ PG::Coder
Returns the default coder object that is currently set for type casting of parameters to #put_copy_data .
-
#encoder_for_put_copy_data=(encoder) ⇒ Object
Set the default coder that is used for type casting of parameters to #put_copy_data .
-
#encrypt_password(password, username, algorithm = nil) ⇒ String
This function is intended to be used by client applications that wish to send commands like
ALTER USER joe PASSWORD 'pwd'
. -
#error_message ⇒ String
Returns the error message about connection.
-
#escape_bytea(string) ⇒ String
Escapes binary data for use within an SQL command with the type
bytea
. -
#escape_identifier(str) ⇒ String
Escape an arbitrary String
str
as an identifier. -
#escape_literal(str) ⇒ String
Escape an arbitrary String
str
as a literal. -
#escape_string(str) ⇒ String
(also: #escape)
Returns a SQL-safe version of the String str.
-
#exec(*args) ⇒ Object
(also: #async_exec)
Sends SQL query request specified by sql to PostgreSQL.
-
#exec_params(*args) ⇒ Object
(also: #async_exec_params)
Sends SQL query request specified by
sql
to PostgreSQL using placeholders for parameters. -
#exec_prepared(*args) ⇒ Object
(also: #async_exec_prepared)
Execute prepared named statement specified by statement_name.
-
#external_encoding ⇒ Encoding
Return the
server_encoding
of the connected database as a Ruby Encoding object. -
#field_name_type ⇒ Symbol
Get type of field names.
-
#field_name_type=(Symbol) ⇒ Object
Set default type of field names of results retrieved by this connection.
-
#finish ⇒ Object
(also: #close)
Closes the backend connection.
-
#finished? ⇒ Boolean
Returns
true
if the backend connection has been closed. -
#flush ⇒ Boolean
Attempts to flush any queued output data to the server.
-
#get_client_encoding ⇒ String
Returns the client encoding as a String.
-
#get_copy_data([ async = false [, decoder = nil ]]) ⇒ Object
Return one row of data,
nil
if the copy is done, orfalse
if the call would block (only possible if async is true). -
#get_last_result ⇒ PG::Result
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. -
#get_result ⇒ Object
Blocks waiting for the next result from a call to #send_query (or another asynchronous command), and returns it.
-
#host ⇒ Object
Returns the connected server name.
-
#initialize(*args) ⇒ Object
constructor
call-seq: PG::Connection.new -> conn PG::Connection.new(connection_hash) -> conn PG::Connection.new(connection_string) -> conn PG::Connection.new(host, port, options, tty, dbname, user, password) -> conn.
-
#internal_encoding ⇒ Encoding
defined in Ruby 1.9 or later.
-
#internal_encoding=(value) ⇒ Object
A wrapper of #set_client_encoding.
-
#is_busy ⇒ Boolean
Returns
true
if a command is busy, that is, if PQgetResult would block. -
#isnonblocking ⇒ Boolean
(also: #nonblocking?)
Returns
true
if a command is busy, that is, if PQgetResult would block. -
#lo_close(lo_desc) ⇒ nil
(also: #loclose)
Closes the postgres large object of lo_desc.
-
#lo_creat([mode]) ⇒ Integer
(also: #locreat)
Creates a large object with mode mode.
-
#lo_create(oid) ⇒ Integer
(also: #locreate)
Creates a large object with oid oid.
-
#lo_export(oid, file) ⇒ nil
(also: #loexport)
Saves a large object of oid to a file.
-
#lo_import(file) ⇒ Integer
(also: #loimport)
Import a file to a large object.
-
#lo_lseek(lo_desc, offset, whence) ⇒ Integer
(also: #lolseek, #lo_seek, #loseek)
Move the large object pointer lo_desc to offset offset.
-
#lo_open(oid, [mode]) ⇒ Integer
(also: #loopen)
Open a large object of oid.
-
#lo_read(lo_desc, len) ⇒ String
(also: #loread)
Attempts to read len bytes from large object lo_desc, returns resulting data.
-
#lo_tell(lo_desc) ⇒ Integer
(also: #lotell)
Returns the current position of the large object lo_desc.
-
#lo_truncate(lo_desc, len) ⇒ nil
(also: #lotruncate)
Truncates the large object lo_desc to size len.
-
#lo_unlink(oid) ⇒ nil
(also: #lounlink)
Unlinks (deletes) the postgres large object of oid.
-
#lo_write(lo_desc, buffer) ⇒ Integer
(also: #lowrite)
Writes the string buffer to the large object lo_desc.
-
#make_empty_pgresult(status) ⇒ PG::Result
Constructs and empty PG::Result with status status.
-
#notifies ⇒ Object
Returns a hash of the unprocessed notifications.
-
#options ⇒ Object
Returns backend option string.
-
#parameter_status(param_name) ⇒ String
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
. -
#pass ⇒ Object
Returns the authenticated password.
-
#port ⇒ Object
Returns the connected server port number.
-
#prepare(stmt_name, sql[, param_types ]) ⇒ PG::Result
(also: #async_prepare)
Prepares statement sql with name name to be executed later.
-
#protocol_version ⇒ Integer
The 3.0 protocol will normally be used when communicating with PostgreSQL 7.4 or later servers; pre-7.4 servers support only protocol 2.0.
-
#put_copy_data(buffer[, encoder]) ⇒ Boolean
Transmits buffer as copy data to the server.
-
#put_copy_end([ error_message ]) ⇒ Boolean
Sends end-of-data indication to the server.
-
#quote_ident(str_or_array) ⇒ Object
Returns a string that is safe for inclusion in a SQL query as an identifier.
-
#reset ⇒ Object
Resets the backend connection.
-
#reset_poll ⇒ Integer
Checks the status of a connection reset operation.
-
#reset_start ⇒ nil
Initiate a connection reset in a nonblocking manner.
-
#send_describe_portal(portal_name) ⇒ nil
Asynchronously send command to the server.
-
#send_describe_prepared(statement_name) ⇒ nil
Asynchronously send command to the server.
-
#send_prepare(stmt_name, sql[, param_types ]) ⇒ nil
Prepares statement sql with name name to be executed later.
-
#send_query(sql) ⇒ nil
Sends SQL query request specified by sql to PostgreSQL for asynchronous processing, and immediately returns.
-
#send_query_params(sql, params[, result_format [, type_map ]]) ⇒ nil
Sends SQL query request specified by sql to PostgreSQL for asynchronous processing, and immediately returns.
-
#send_query_prepared(*args) ⇒ Object
Execute prepared named statement specified by statement_name asynchronously, and returns immediately.
-
#server_version ⇒ Integer
The number is formed by converting the major, minor, and revision numbers into two-decimal-digit numbers and appending them together.
-
#set_client_encoding(encoding) ⇒ Object
(also: #client_encoding=)
Sets the client encoding to the encoding String.
-
#set_default_encoding ⇒ Encoding
If Ruby has its Encoding.default_internal set, set PostgreSQL’s client_encoding to match.
-
#set_error_context_visibility(context_visibility) ⇒ Integer
Sets connection’s context display mode to context_visibility and returns the previous setting.
-
#set_error_verbosity(verbosity) ⇒ Integer
Sets connection’s verbosity to verbosity and returns the previous setting.
-
#set_notice_processor {|message| ... } ⇒ Proc
See #set_notice_receiver for the desription of what this and the notice_processor methods do.
-
#set_notice_receiver {|result| ... } ⇒ Proc
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.
-
#set_single_row_mode ⇒ self
To enter single-row mode, call this method immediately after a successful call of send_query (or a sibling function).
-
#setnonblocking(Boolean) ⇒ nil
Sets the nonblocking status of the connection.
-
#socket ⇒ Integer
This method is deprecated.
-
#socket_io ⇒ Object
Fetch a memorized IO object created from the Connection’s underlying socket.
-
#ssl_attribute(attribute_name) ⇒ String
Returns SSL-related information about the connection.
-
#ssl_attribute_names ⇒ Array<String>
Return an array of SSL attribute names available.
-
#ssl_attributes ⇒ Object
call-seq: conn.ssl_attributes -> Hash<String,String>.
-
#ssl_in_use? ⇒ Boolean
Returns
true
if the connection uses SSL/TLS,false
if not. -
#status ⇒ Object
Returns status of connection : CONNECTION_OK or CONNECTION_BAD.
-
#sync_describe_portal(portal_name) ⇒ PG::Result
This function has the same behavior as #async_describe_portal, but is implemented using the synchronous command processing API of libpq.
-
#sync_describe_prepared(statement_name) ⇒ PG::Result
This function has the same behavior as #async_describe_prepared, but is implemented using the synchronous command processing API of libpq.
-
#sync_exec(*args) ⇒ Object
This function has the same behavior as #async_exec, but is implemented using the synchronous command processing API of libpq.
-
#sync_exec_params(*args) ⇒ Object
This function has the same behavior as #async_exec_params, but is implemented using the synchronous command processing API of libpq.
-
#sync_exec_prepared(*args) ⇒ Object
This function has the same behavior as #async_exec_prepared, but is implemented using the synchronous command processing API of libpq.
-
#sync_prepare(stmt_name, sql[, param_types ]) ⇒ PG::Result
This function has the same behavior as #async_prepare, but is implemented using the synchronous command processing API of libpq.
-
#trace(stream) ⇒ nil
Enables tracing message passing between backend.
-
#transaction {|conn| ... } ⇒ Object
Executes a
BEGIN
at the start of the block, and aCOMMIT
at the end of the block, orROLLBACK
if any exception occurs. -
#transaction_status ⇒ Object
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).
-
#tty ⇒ Object
Returns the connected pgtty.
-
#type_map_for_queries ⇒ TypeMap
Returns the default TypeMap that is currently set for type casts of query bind parameters.
-
#type_map_for_queries=(typemap) ⇒ Object
Set the default TypeMap that is used for type casts of query bind parameters.
-
#type_map_for_results ⇒ TypeMap
Returns the default TypeMap that is currently set for type casts of result values.
-
#type_map_for_results=(typemap) ⇒ Object
Set the default TypeMap that is used for type casts of result values.
-
#PG::Connection.unescape_bytea(string) ⇒ Object
Converts an escaped string representation of binary data into binary data — the reverse of #escape_bytea.
-
#untrace ⇒ nil
Disables the message tracing.
-
#user ⇒ Object
Returns the authenticated user name.
-
#wait_for_notify([ timeout ]) {|event, pid, payload| ... } ⇒ String
(also: #notifies_wait)
Blocks while waiting for notification(s), or until the optional timeout is reached, whichever comes first.
Constructor Details
#initialize(*args) ⇒ Object
call-seq:
PG::Connection.new -> conn
PG::Connection.new(connection_hash) -> conn
PG::Connection.new(connection_string) -> conn
PG::Connection.new(host, port, options, tty, dbname, user, password) -> conn
Create a connection to the specified server.
connection_hash
must be a ruby Hash with connection parameters. See the list of valid parameters in the PostgreSQL documentation.
There are two accepted formats for connection_string
: plain keyword = value
strings and URIs. See the documentation of connection strings.
The positional parameter form has the same functionality except that the missing parameters will always take on default values. The parameters are:
host
-
server hostname
port
-
server port number
options
-
backend options
tty
-
(ignored in newer versions of PostgreSQL)
dbname
-
connecting database name
user
-
login user name
password
-
login password
Examples:
# Connect using all defaults
PG::Connection.new
# As a Hash
PG::Connection.new( :dbname => 'test', :port => 5432 )
# As a String
PG::Connection.new( "dbname=test port=5432" )
# As an Array
PG::Connection.new( nil, 5432, nil, nil, 'test', nil, nil )
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.
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 |
# File 'ext/pg_connection.c', line 260
static VALUE
pgconn_init(int argc, VALUE *argv, VALUE self)
{
t_pg_connection *this;
VALUE conninfo;
VALUE error;
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 structure");
if (PQstatus(this->pgconn) == CONNECTION_BAD) {
error = rb_exc_new2(rb_eConnectionBad, PQerrorMessage(this->pgconn));
rb_iv_set(error, "@connection", self);
rb_exc_raise(error);
}
pgconn_set_default_encoding( self );
if (rb_block_given_p()) {
return rb_ensure(rb_yield, self, pgconn_finish, self);
}
return self;
}
|
Class Method Details
.async_api=(enable) ⇒ Object
282 283 284 285 286 287 |
# File 'lib/pg/connection.rb', line 282 def self.async_api=(enable) REDIRECT_METHODS.each do |ali, (async, sync)| remove_method(ali) if method_defined?(ali) alias_method( ali, enable ? async : sync ) end end |
.conndefaults ⇒ Object
call-seq:
PG::Connection.conndefaults() -> Array
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
393 394 395 396 397 398 399 400 401 402 403 404 |
# File 'ext/pg_connection.c', line 393
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 ⇒ Object
Return the Postgres connection defaults structure as a Hash keyed by option keyword (as a Symbol).
See also #conndefaults
228 229 230 231 232 |
# File 'lib/pg/connection.rb', line 228 def self.conndefaults_hash return self.conndefaults.each_with_object({}) do |info, hash| hash[ info[:keyword].to_sym ] = info[:val] end end |
.PG::Connection.connect_start(connection_hash) ⇒ Object .PG::Connection.connect_start(connection_string) ⇒ Object .PG::Connection.connect_start(host, port, options, tty, dbname, login, password) ⇒ Object
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.
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 |
# File 'ext/pg_connection.c', line 306
static VALUE
pgconn_s_connect_start( int argc, VALUE *argv, VALUE klass )
{
VALUE rb_conn;
VALUE conninfo;
VALUE error;
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 structure");
if ( PQstatus(this->pgconn) == CONNECTION_BAD ) {
error = rb_exc_new2(rb_eConnectionBad, PQerrorMessage(this->pgconn));
rb_iv_set(error, "@connection", rb_conn);
rb_exc_raise(error);
}
if ( rb_block_given_p() ) {
return rb_ensure( rb_yield, rb_conn, pgconn_finish, rb_conn );
}
return rb_conn;
}
|
.PG::Connection.encrypt_password(password, username) ⇒ String
This is an older, deprecated version of #encrypt_password. The difference is that this function always uses md5
as the encryption algorithm.
464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 |
# File 'ext/pg_connection.c', line 464
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
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.
1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 |
# File 'ext/pg_connection.c', line 1546
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
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.
1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 |
# File 'ext/pg_connection.c', line 1492
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) {
rb_raise(rb_ePGerror, "%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;
}
|
.parse_connect_args(*args) ⇒ Object
Parse the connection args
into a connection-parameter string. See PG::Connection.new for valid arguments.
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 |
# File 'lib/pg/connection.rb', line 36 def self::parse_connect_args( *args ) return '' if args.empty? hash_arg = args.last.is_a?( Hash ) ? args.pop : {} option_string = '' = {} # Parameter 'fallback_application_name' was introduced in PostgreSQL 9.0 # together with PQescapeLiteral(). if PG::Connection.instance_methods.find {|m| m.to_sym == :escape_literal } [:fallback_application_name] = $0.sub( /^(.{30}).{4,}(.{30})$/ ){ $1+"..."+$2 } end if args.length == 1 case args.first when URI, /\A#{URI::ABS_URI_REF}\z/ uri = URI(args.first) .merge!( Hash[URI.decode_www_form( uri.query )] ) if uri.query when /=/ # Option string style option_string = args.first.to_s else # Positional parameters [CONNECT_ARGUMENT_ORDER.first.to_sym] = args.first end else 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)| [ k.to_sym ] = v if v end end .merge!( hash_arg ) if uri uri.host = nil if [:host] uri.port = nil if [:port] uri.user = nil if [:user] uri.password = nil if [:password] uri.path = '' if [:dbname] uri.query = URI.encode_www_form( ) return uri.to_s.sub( /^#{uri.scheme}:(?!\/\/)/, "#{uri.scheme}://" ) else option_string += ' ' unless option_string.empty? && .empty? return option_string + .map { |k,v| "#{k}=#{quote_connstr(v)}" }.join( ' ' ) end end |
.PG::Connection.ping(connection_hash) ⇒ Integer .PG::Connection.ping(connection_string) ⇒ Integer .PG::Connection.ping(host, port, options, tty, dbname, login, password) ⇒ Integer
Check server status.
See PG::Connection.new for a description of the parameters.
Returns one of:
PQPING_OK
-
server is accepting connections
PQPING_REJECT
-
server is alive but rejecting connections
PQPING_NO_RESPONSE
-
could not establish connection
PQPING_NO_ATTEMPT
-
connection not attempted (bad params)
358 359 360 361 362 363 364 365 366 367 368 |
# File 'ext/pg_connection.c', line 358
static VALUE
pgconn_s_ping( int argc, VALUE *argv, VALUE klass )
{
PGPing ping;
VALUE conninfo;
conninfo = rb_funcall2( klass, rb_intern("parse_connect_args"), argc, argv );
ping = PQping( StringValueCStr(conninfo) );
return INT2FIX((int)ping);
}
|
.quote_connstr(value) ⇒ Object
Quote the given value
for use in a connection-parameter string.
29 30 31 |
# File 'lib/pg/connection.rb', line 29 def self::quote_connstr( value ) return "'" + value.to_s.gsub( /[\\']/ ) {|m| '\\' + m } + "'" end |
.quote_ident(str) ⇒ String .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.
2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 |
# File 'ext/pg_connection.c', line 2986
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.unescape_bytea(string) ⇒ Object
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.
1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 |
# File 'ext/pg_connection.c', line 1578
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;
}
|
Instance Method Details
#backend_pid ⇒ Integer
Returns the process ID of the backend server process for this connection. Note that this is a PID on database server host.
915 916 917 918 919 |
# File 'ext/pg_connection.c', line 915
static VALUE
pgconn_backend_pid(VALUE self)
{
return INT2NUM(PQbackendPID(pg_get_pgconn(self)));
}
|
#block([ timeout ]) ⇒ Boolean
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.
3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 |
# File 'ext/pg_connection.c', line 3023
static VALUE
pgconn_block( int argc, VALUE *argv, VALUE self ) {
PGconn *conn = pg_get_pgconn( 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( conn, ptimeout, get_result_readable);
if( !ret )
return Qfalse;
return Qtrue;
}
|
#cancel ⇒ String
Requests cancellation of the command currently being processed. (Only implemented in PostgreSQL >= 8.0)
Returns nil
on success, or a string containing the error message if a failure occurs.
2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 |
# File 'ext/pg_connection.c', line 2169
static VALUE
pgconn_cancel(VALUE self)
{
char errbuf[256];
PGcancel *cancel;
VALUE retval;
int ret;
cancel = PQgetCancel(pg_get_pgconn(self));
if(cancel == NULL)
rb_raise(rb_ePGerror,"Invalid connection!");
ret = gvl_PQcancel(cancel, errbuf, 256);
if(ret == 1)
retval = Qnil;
else
retval = rb_str_new2(errbuf);
PQfreeCancel(cancel);
return retval;
}
|
#conndefaults ⇒ Object
Returns an array of Hashes with connection defaults. See ::conndefaults for details.
220 221 222 |
# File 'lib/pg/connection.rb', line 220 def conndefaults return self.class.conndefaults end |
#conndefaults_hash ⇒ Object
Returns a Hash with connection defaults. See ::conndefaults_hash for details.
236 237 238 |
# File 'lib/pg/connection.rb', line 236 def conndefaults_hash return self.class.conndefaults_hash end |
#connect_poll ⇒ Integer
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:
conn = PG::Connection.connect_start("dbname=mydatabase")
socket = conn.socket_io
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)
if(not select([socket], [], [], 10.0))
raise "Asynchronous connection timed out!"
end
elsif(status == PG::PGRES_POLLING_WRITING)
if(not select([], [socket], [], 10.0))
raise "Asynchronous connection timed out!"
end
end
status = conn.connect_poll
end
# now conn.status == CONNECTION_OK, and connection
# is ready.
521 522 523 524 525 526 527 |
# File 'ext/pg_connection.c', line 521
static VALUE
pgconn_connect_poll(VALUE self)
{
PostgresPollingStatusType status;
status = gvl_PQconnectPoll(pg_get_pgconn(self));
return INT2FIX((int)status);
}
|
#connection_needs_password ⇒ Boolean
Returns true
if the authentication method required a password, but none was available. false
otherwise.
928 929 930 931 932 |
# File 'ext/pg_connection.c', line 928
static VALUE
pgconn_connection_needs_password(VALUE self)
{
return PQconnectionNeedsPassword(pg_get_pgconn(self)) ? Qtrue : Qfalse;
}
|
#connection_used_password ⇒ Boolean
Returns true
if the authentication method used a caller-supplied password, false
otherwise.
941 942 943 944 945 |
# File 'ext/pg_connection.c', line 941
static VALUE
pgconn_connection_used_password(VALUE self)
{
return PQconnectionUsedPassword(pg_get_pgconn(self)) ? Qtrue : Qfalse;
}
|
#conninfo ⇒ Hash
Returns the connection options used by a live connection.
Available since PostgreSQL-9.3
720 721 722 723 724 725 726 727 728 729 730 |
# File 'ext/pg_connection.c', line 720
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 ⇒ Object
Return the Postgres connection info structure as a Hash keyed by option keyword (as a Symbol).
See also #conninfo
247 248 249 250 251 |
# File 'lib/pg/connection.rb', line 247 def conninfo_hash return self.conninfo.each_with_object({}) do |info, hash| hash[ info[:keyword].to_sym ] = info[:val] end end |
#consume_input ⇒ Object
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.
2051 2052 2053 |
# File 'ext/pg_connection.c', line 2051 static VALUE pgconn_consume_input(self) VALUE self; |
#copy_data(sql, coder = nil) ⇒ Object
call-seq:
conn.copy_data( sql [, coder] ) {|sql_result| ... } -> PG::Result
Execute a copy process for transfering data to or from the server.
This issues the SQL COPY command via #exec. The response to this (if there is no error in the command) is a PG::Result object that is passed to the block, bearing a status code of PGRES_COPY_OUT or PGRES_COPY_IN (depending on the specified copy direction). The application should then use #put_copy_data or #get_copy_data to receive or transmit data rows and should return from the block when finished.
#copy_data returns another PG::Result object when the data transfer is complete. An exception is raised if some problem was encountered, so it isn’t required to make use of any of them. At this point further SQL commands can be issued via #exec. (It is not possible to execute other SQL commands using the same connection while the COPY operation is in progress.)
This method ensures, that the copy process is properly terminated in case of client side or server side failures. Therefore, in case of blocking mode of operation, #copy_data is preferred to raw calls of #put_copy_data, #get_copy_data and #put_copy_end.
coder can be a PG::Coder derivation (typically PG::TextEncoder::CopyRow or PG::TextDecoder::CopyRow). This enables encoding of data fields given to #put_copy_data or decoding of fields received by #get_copy_data.
Example with CSV input format:
conn.exec "create table my_table (a text,b text,c text,d text)"
conn.copy_data "COPY my_table FROM STDIN CSV" do
conn.put_copy_data "some,data,to,copy\n"
conn.put_copy_data "more,data,to,copy\n"
end
This creates my_table
and inserts two CSV rows.
The same with text format encoder PG::TextEncoder::CopyRow and Array input:
enco = PG::TextEncoder::CopyRow.new
conn.copy_data "COPY my_table FROM STDIN", enco do
conn.put_copy_data ['some', 'data', 'to', 'copy']
conn.put_copy_data ['more', 'data', 'to', 'copy']
end
Example with CSV output format:
conn.copy_data "COPY my_table TO STDOUT CSV" do
while row=conn.get_copy_data
p row
end
end
This prints all rows of my_table
to stdout:
"some,data,to,copy\n"
"more,data,to,copy\n"
The same with text format decoder PG::TextDecoder::CopyRow and Array output:
deco = PG::TextDecoder::CopyRow.new
conn.copy_data "COPY my_table TO STDOUT", deco do
while row=conn.get_copy_data
p row
end
end
This receives all rows of my_table
as ruby array:
["some", "data", "to", "copy"]
["more", "data", "to", "copy"]
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 |
# File 'lib/pg/connection.rb', line 156 def copy_data( sql, coder=nil ) res = exec( sql ) case res.result_status when PGRES_COPY_IN begin if coder old_coder = self.encoder_for_put_copy_data self.encoder_for_put_copy_data = coder end yield res rescue Exception => err errmsg = "%s while copy data: %s" % [ err.class.name, err. ] put_copy_end( errmsg ) get_result raise else put_copy_end get_last_result ensure self.encoder_for_put_copy_data = old_coder if coder end when PGRES_COPY_OUT begin if coder old_coder = self.decoder_for_get_copy_data self.decoder_for_get_copy_data = coder end yield res rescue Exception => err cancel while get_copy_data end while get_result end raise else res = get_last_result if !res || res.result_status != PGRES_COMMAND_OK while get_copy_data end while get_result end raise PG::NotAllCopyDataRetrieved, "Not all COPY data retrieved" 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 ⇒ Object
Returns the connected database name.
619 620 621 622 623 624 625 |
# File 'ext/pg_connection.c', line 619
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
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.
4076 4077 4078 4079 4080 4081 4082 |
# File 'ext/pg_connection.c', line 4076
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) ⇒ Object
Set the default coder that is used for type casting of received data by #get_copy_data .
decoder
can be:
-
a kind of PG::Coder
-
nil
- disable type decoding, returned data will be a String.
4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 |
# File 'ext/pg_connection.c', line 4047
static VALUE
pgconn_decoder_for_get_copy_data_set(VALUE self, VALUE typemap)
{
t_pg_connection *this = pg_get_connection( self );
if( typemap != Qnil ){
if ( !rb_obj_is_kind_of(typemap, rb_cPG_Coder) ) {
rb_raise( rb_eTypeError, "wrong argument type %s (expected kind of PG::Coder)",
rb_obj_classname( typemap ) );
}
Check_Type(typemap, T_DATA);
}
this->decoder_for_get_copy_data = typemap;
return typemap;
}
|
#describe_portal(portal_name) ⇒ PG::Result Also known as: async_describe_portal
Retrieve information about the portal portal_name.
See also corresponding libpq function.
3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 |
# File 'ext/pg_connection.c', line 3339
static VALUE
pgconn_async_describe_portal(VALUE self, VALUE portal)
{
VALUE rb_pgresult = Qnil;
pgconn_discard_results( self );
pgconn_send_describe_portal( self, portal );
pgconn_block( 0, NULL, self ); /* wait for input (without blocking) before reading the last result */
rb_pgresult = pgconn_get_last_result( self );
if ( rb_block_given_p() ) {
return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
}
return rb_pgresult;
}
|
#describe_prepared(statement_name) ⇒ PG::Result Also known as: async_describe_prepared
Retrieve information about the prepared statement statement_name.
See also corresponding libpq function.
3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 |
# File 'ext/pg_connection.c', line 3364
static VALUE
pgconn_async_describe_prepared(VALUE self, VALUE stmt_name)
{
VALUE rb_pgresult = Qnil;
pgconn_discard_results( self );
pgconn_send_describe_prepared( self, stmt_name );
pgconn_block( 0, NULL, self ); /* wait for input (without blocking) before reading the last result */
rb_pgresult = pgconn_get_last_result( self );
if ( rb_block_given_p() ) {
return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
}
return rb_pgresult;
}
|
#discard_results ⇒ Object
Silently discard any prior query result that application didn’t eat. This is done prior of Connection#exec and sibling methods and can be called explicitly when using the async API.
3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 |
# File 'ext/pg_connection.c', line 3099
static VALUE
pgconn_discard_results(VALUE self)
{
PGconn *conn = pg_get_pgconn(self);
PGresult *cur;
while ((cur = gvl_PQgetResult(conn)) != NULL) {
int status = PQresultStatus(cur);
PQclear(cur);
if (status == PGRES_COPY_IN){
gvl_PQputCopyEnd(conn, "COPY terminated by new PQexec");
}
if (status == PGRES_COPY_OUT){
char *buffer = NULL;
while( gvl_PQgetCopyData(conn, &buffer, 0) > 0)
PQfreemem(buffer);
}
}
return Qnil;
}
|
#encoder_for_put_copy_data ⇒ PG::Coder
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.
4027 4028 4029 4030 4031 4032 4033 |
# File 'ext/pg_connection.c', line 4027
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) ⇒ Object
Set the default coder that is used for type casting of parameters to #put_copy_data .
encoder
can be:
-
a kind of PG::Coder
-
nil
- disable type encoding, data must be a String.
3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 |
# File 'ext/pg_connection.c', line 3998
static VALUE
pgconn_encoder_for_put_copy_data_set(VALUE self, VALUE typemap)
{
t_pg_connection *this = pg_get_connection( self );
if( typemap != Qnil ){
if ( !rb_obj_is_kind_of(typemap, rb_cPG_Coder) ) {
rb_raise( rb_eTypeError, "wrong argument type %s (expected kind of PG::Coder)",
rb_obj_classname( typemap ) );
}
Check_Type(typemap, T_DATA);
}
this->encoder_for_put_copy_data = typemap;
return typemap;
}
|
#encrypt_password(password, username, algorithm = nil) ⇒ String
This function is intended to be used by client applications that wish to send commands like ALTER USER joe PASSWORD 'pwd'
. It is good practice not to send the original cleartext password in such a command, because it might be exposed in command logs, activity displays, and so on. Instead, use this function to convert the password to encrypted form before it is sent.
The password
and username
arguments are the cleartext password, and the SQL name of the user it is for. algorithm
specifies the encryption algorithm to use to encrypt the password. Currently supported algorithms are md5
and scram-sha-256
(on
and off
are also accepted as aliases for md5
, for compatibility with older server versions). Note that support for scram-sha-256
was introduced in PostgreSQL version 10, and will not work correctly with older server versions. If algorithm is omitted or nil
, this function will query the server for the current value of the password_encryption
setting. That can block, and will fail if the current transaction is aborted, or if the connection is busy executing another query. If you wish to use the default algorithm for the server but want to avoid blocking, query password_encryption
yourself before calling #encrypt_password, and pass that value as the algorithm.
Return value is the encrypted password. The caller can assume the string doesn’t contain any special characters that would require escaping.
Available since PostgreSQL-10. See also corresponding libpq function.
430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 |
# File 'ext/pg_connection.c', line 430
static VALUE
pgconn_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 {
rb_raise(rb_ePGerror, "%s", PQerrorMessage(conn));
}
return rval;
}
|
#error_message ⇒ String
Returns the error message about connection.
828 829 830 831 832 833 834 |
# File 'ext/pg_connection.c', line 828
static VALUE
pgconn_error_message(VALUE self)
{
char *error = PQerrorMessage(pg_get_pgconn(self));
if (!error) return Qnil;
return rb_str_new2(error);
}
|
#escape_bytea(string) ⇒ String
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.
1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 |
# File 'ext/pg_connection.c', line 1546
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_identifier(str) ⇒ String
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.
1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 |
# File 'ext/pg_connection.c', line 1644
static VALUE
pgconn_escape_identifier(VALUE self, VALUE string)
{
t_pg_connection *this = pg_get_connection_safe( self );
char *escaped = NULL;
VALUE error;
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)
{
error = rb_exc_new2(rb_ePGerror, PQerrorMessage(this->pgconn));
rb_iv_set(error, "@connection", self);
rb_exc_raise(error);
return Qnil;
}
result = rb_str_new2(escaped);
PQfreemem(escaped);
PG_ENCODING_SET_NOCHECK(result, enc_idx);
return result;
}
|
#escape_literal(str) ⇒ String
Escape an arbitrary String str
as a literal.
See also PG::TextEncoder::QuotedLiteral for a type cast integrated version of this function.
1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 |
# File 'ext/pg_connection.c', line 1605
static VALUE
pgconn_escape_literal(VALUE self, VALUE string)
{
t_pg_connection *this = pg_get_connection_safe( self );
char *escaped = NULL;
VALUE error;
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)
{
error = rb_exc_new2(rb_ePGerror, PQerrorMessage(this->pgconn));
rb_iv_set(error, "@connection", self);
rb_exc_raise(error);
return Qnil;
}
result = rb_str_new2(escaped);
PQfreemem(escaped);
PG_ENCODING_SET_NOCHECK(result, enc_idx);
return result;
}
|
#escape_string(str) ⇒ String Also known as: escape
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.
1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 |
# File 'ext/pg_connection.c', line 1492
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) {
rb_raise(rb_ePGerror, "%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;
}
|
#exec(sql) ⇒ PG::Result #exec(sql) {|pg_result| ... } ⇒ Object Also known as: async_exec
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. 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.
3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 |
# File 'ext/pg_connection.c', line 3148
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 );
pgconn_block( 0, NULL, self ); /* wait for input (without blocking) before reading the last result */
rb_pgresult = pgconn_get_last_result( self );
if ( rb_block_given_p() ) {
return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
}
return rb_pgresult;
}
|
#exec_params(sql, params[, result_format [, type_map ]]) ⇒ nil #exec_params(sql, params[, result_format [, type_map ]]) {|pg_result| ... } ⇒ Object Also known as: async_exec_params
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, $1, $2, 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.
3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 |
# File 'ext/pg_connection.c', line 3215
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 );
}
pgconn_block( 0, NULL, self ); /* wait for input (without blocking) before reading the last result */
rb_pgresult = pgconn_get_last_result( self );
if ( rb_block_given_p() ) {
return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
}
return rb_pgresult;
}
|
#exec_prepared(statement_name[, params, result_format[, type_map]]) ⇒ PG::Result #exec_prepared(statement_name[, params, result_format[, type_map]]) {|pg_result| ... } ⇒ Object Also known as: async_exec_prepared
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, $1, $2, 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.
3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 |
# File 'ext/pg_connection.c', line 3314
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 );
pgconn_block( 0, NULL, self ); /* wait for input (without blocking) before reading the last result */
rb_pgresult = pgconn_get_last_result( self );
if ( rb_block_given_p() ) {
return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
}
return rb_pgresult;
}
|
#external_encoding ⇒ Encoding
Return the server_encoding
of the connected database as a Ruby Encoding object. The SQL_ASCII
encoding is mapped to to ASCII_8BIT
.
3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 |
# File 'ext/pg_connection.c', line 3834
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
Get type of field names.
See description at #field_name_type=
4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 |
# File 'ext/pg_connection.c', line 4122
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) ⇒ Object
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=
4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 4111 4112 |
# File 'ext/pg_connection.c', line 4100
static VALUE
pgconn_field_name_type_set(VALUE self, VALUE sym)
{
t_pg_connection *this = pg_get_connection( 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 ⇒ Object Also known as: close
Closes the backend connection.
535 536 537 538 539 540 541 542 543 544 |
# File 'ext/pg_connection.c', line 535
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;
}
|
#finished? ⇒ Boolean
Returns true
if the backend connection has been closed.
553 554 555 556 557 558 559 |
# File 'ext/pg_connection.c', line 553
static VALUE
pgconn_finished_p( VALUE self )
{
t_pg_connection *this = pg_get_connection( self );
if ( this->pgconn ) return Qfalse;
return Qtrue;
}
|
#flush ⇒ Boolean
Attempts to flush any queued output data to the server. Returns true
if data is successfully flushed, false
if not (can only return false
if connection is nonblocking. Raises PG::Error if some other failure occurred.
2143 2144 2145 |
# File 'ext/pg_connection.c', line 2143 static VALUE pgconn_flush(self) VALUE self; |
#get_client_encoding ⇒ String
Returns the client encoding as a String.
2877 2878 2879 2880 2881 2882 |
# File 'ext/pg_connection.c', line 2877
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([ async = false [, decoder = nil ]]) ⇒ Object
Return one row of data, nil
if the copy is done, or false
if the call would block (only possible if async 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.
2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 |
# File 'ext/pg_connection.c', line 2566
static VALUE
pgconn_get_copy_data(int argc, VALUE *argv, VALUE self )
{
VALUE async_in;
VALUE error;
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 = DATA_PTR( this->decoder_for_get_copy_data );
}
} else if( rb_obj_is_kind_of(decoder, rb_cPG_Coder) ) {
Data_Get_Struct( decoder, t_pg_coder, p_coder );
} else {
rb_raise( rb_eTypeError, "wrong decoder type %s (expected some kind of PG::Coder)",
rb_obj_classname( decoder ) );
}
ret = gvl_PQgetCopyData(this->pgconn, &buffer, RTEST(async_in));
if(ret == -2) { /* error */
error = rb_exc_new2(rb_ePGerror, PQerrorMessage(this->pgconn));
rb_iv_set(error, "@connection", self);
rb_exc_raise(error);
}
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;
}
|
#get_last_result ⇒ PG::Result
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.
This function is similar to #get_result except that it is designed to get one and only one result.
3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 |
# File 'ext/pg_connection.c', line 3063
static VALUE
pgconn_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)
break;
}
if (prev) {
rb_pgresult = pg_new_result( prev, self );
pg_result_check(rb_pgresult);
}
return rb_pgresult;
}
|
#get_result ⇒ PG::Result #get_result {|pg_result| ... } ⇒ Object
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.
2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 |
# File 'ext/pg_connection.c', line 2025
static VALUE
pgconn_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;
}
|
#host ⇒ Object
Returns the connected server name.
661 662 663 664 665 666 667 |
# File 'ext/pg_connection.c', line 661
static VALUE
pgconn_host(VALUE self)
{
char *host = PQhost(pg_get_pgconn(self));
if (!host) return Qnil;
return rb_str_new2(host);
}
|
#internal_encoding ⇒ Encoding
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’
3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 |
# File 'ext/pg_connection.c', line 3773
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) ⇒ Object
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.
3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 |
# File 'ext/pg_connection.c', line 3800
static VALUE
pgconn_internal_encoding_set(VALUE self, VALUE enc)
{
if (NIL_P(enc)) {
pgconn_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_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
Returns true
if a command is busy, that is, if PQgetResult would block. Otherwise returns false
.
2073 2074 2075 |
# File 'ext/pg_connection.c', line 2073 static VALUE pgconn_is_busy(self) VALUE self; |
#isnonblocking ⇒ Boolean Also known as: nonblocking?
Returns true
if a command is busy, that is, if PQgetResult would block. Otherwise returns false
.
2126 2127 2128 |
# File 'ext/pg_connection.c', line 2126 static VALUE pgconn_isnonblocking(self) VALUE self; |
#lo_close(lo_desc) ⇒ nil Also known as: loclose
Closes the postgres large object of lo_desc.
3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 |
# File 'ext/pg_connection.c', line 3721
static VALUE
pgconn_loclose(VALUE self, VALUE in_lo_desc)
{
PGconn *conn = pg_get_pgconn(self);
int lo_desc = NUM2INT(in_lo_desc);
if(lo_close(conn,lo_desc) < 0)
rb_raise(rb_ePGerror,"lo_close failed");
return Qnil;
}
|
#lo_creat([mode]) ⇒ Integer Also known as: locreat
Creates a large object with mode mode. Returns a large object Oid. On failure, it raises PG::Error.
3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 |
# File 'ext/pg_connection.c', line 3471
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);
lo_oid = lo_creat(conn, mode);
if (lo_oid == 0)
rb_raise(rb_ePGerror, "lo_creat failed");
return UINT2NUM(lo_oid);
}
|
#lo_create(oid) ⇒ Integer Also known as: locreate
Creates a large object with oid oid. Returns the large object Oid. On failure, it raises PG::Error.
3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 |
# File 'ext/pg_connection.c', line 3498
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)
rb_raise(rb_ePGerror, "lo_create failed");
return UINT2NUM(ret);
}
|
#lo_export(oid, file) ⇒ nil Also known as: loexport
Saves a large object of oid to a file.
3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 |
# File 'ext/pg_connection.c', line 3542
static VALUE
pgconn_loexport(VALUE self, VALUE lo_oid, VALUE filename)
{
PGconn *conn = pg_get_pgconn(self);
Oid oid;
Check_Type(filename, T_STRING);
oid = NUM2UINT(lo_oid);
if (lo_export(conn, oid, StringValueCStr(filename)) < 0) {
rb_raise(rb_ePGerror, "%s", PQerrorMessage(conn));
}
return Qnil;
}
|
#lo_import(file) ⇒ Integer Also known as: loimport
Import a file to a large object. Returns a large object Oid.
On failure, it raises a PG::Error.
3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 |
# File 'ext/pg_connection.c', line 3520
static VALUE
pgconn_loimport(VALUE self, VALUE filename)
{
Oid lo_oid;
PGconn *conn = pg_get_pgconn(self);
Check_Type(filename, T_STRING);
lo_oid = lo_import(conn, StringValueCStr(filename));
if (lo_oid == 0) {
rb_raise(rb_ePGerror, "%s", PQerrorMessage(conn));
}
return UINT2NUM(lo_oid);
}
|
#lo_lseek(lo_desc, offset, whence) ⇒ Integer Also known as: lolseek, lo_seek, loseek
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.)
3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 |
# File 'ext/pg_connection.c', line 3663
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;
if((ret = lo_lseek(conn, lo_desc, NUM2INT(offset), NUM2INT(whence))) < 0) {
rb_raise(rb_ePGerror, "lo_lseek failed");
}
return INT2FIX(ret);
}
|
#lo_open(oid, [mode]) ⇒ Integer Also known as: loopen
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
.
3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 |
# File 'ext/pg_connection.c', line 3567
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);
if((fd = lo_open(conn, lo_oid, mode)) < 0) {
rb_raise(rb_ePGerror, "can't open large object: %s", PQerrorMessage(conn));
}
return INT2FIX(fd);
}
|
#lo_read(lo_desc, len) ⇒ String Also known as: loread
Attempts to read len bytes from large object lo_desc, returns resulting data.
3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 |
# File 'ext/pg_connection.c', line 3622
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;
buffer = ALLOC_N(char, len);
if(buffer == NULL)
rb_raise(rb_eNoMemError, "ALLOC failed!");
if (len < 0){
rb_raise(rb_ePGerror,"nagative length %d given", len);
}
if((ret = lo_read(conn, lo_desc, buffer, len)) < 0)
rb_raise(rb_ePGerror, "lo_read failed");
if(ret == 0) {
xfree(buffer);
return Qnil;
}
str = rb_str_new(buffer, ret);
xfree(buffer);
return str;
}
|
#lo_tell(lo_desc) ⇒ Integer Also known as: lotell
Returns the current position of the large object lo_desc.
3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 |
# File 'ext/pg_connection.c', line 3683
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);
if((position = lo_tell(conn, lo_desc)) < 0)
rb_raise(rb_ePGerror,"lo_tell failed");
return INT2FIX(position);
}
|
#lo_truncate(lo_desc, len) ⇒ nil Also known as: lotruncate
Truncates the large object lo_desc to size len.
3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 |
# File 'ext/pg_connection.c', line 3702
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);
if(lo_truncate(conn,lo_desc,len) < 0)
rb_raise(rb_ePGerror,"lo_truncate failed");
return Qnil;
}
|
#lo_unlink(oid) ⇒ nil Also known as: lounlink
Unlinks (deletes) the postgres large object of oid.
3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 |
# File 'ext/pg_connection.c', line 3739
static VALUE
pgconn_lounlink(VALUE self, VALUE in_oid)
{
PGconn *conn = pg_get_pgconn(self);
Oid oid = NUM2UINT(in_oid);
if(lo_unlink(conn,oid) < 0)
rb_raise(rb_ePGerror,"lo_unlink failed");
return Qnil;
}
|
#lo_write(lo_desc, buffer) ⇒ Integer Also known as: lowrite
Writes the string buffer to the large object lo_desc. Returns the number of bytes written.
3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 |
# File 'ext/pg_connection.c', line 3595
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) {
rb_raise(rb_ePGerror, "write buffer zero string");
}
if((n = lo_write(conn, fd, StringValuePtr(buffer),
RSTRING_LEN(buffer))) < 0) {
rb_raise(rb_ePGerror, "lo_write failed: %s", PQerrorMessage(conn));
}
return INT2FIX(n);
}
|
#make_empty_pgresult(status) ⇒ PG::Result
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
1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 |
# File 'ext/pg_connection.c', line 1458
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;
}
|
#notifies ⇒ Object
Returns a hash of the unprocessed notifications. If there is no unprocessed notifier, it returns nil
.
2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 |
# File 'ext/pg_connection.c', line 2199
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();
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;
}
|
#options ⇒ Object
Returns backend option string.
702 703 704 705 706 707 708 |
# File 'ext/pg_connection.c', line 702
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
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.
781 782 783 784 785 786 787 788 789 |
# File 'ext/pg_connection.c', line 781
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 ⇒ Object
Returns the authenticated password.
647 648 649 650 651 652 653 |
# File 'ext/pg_connection.c', line 647
static VALUE
pgconn_pass(VALUE self)
{
char *user = PQpass(pg_get_pgconn(self));
if (!user) return Qnil;
return rb_str_new2(user);
}
|
#port ⇒ Object
Returns the connected server port number.
675 676 677 678 679 680 |
# File 'ext/pg_connection.c', line 675
static VALUE
pgconn_port(VALUE self)
{
char* port = PQport(pg_get_pgconn(self));
return INT2NUM(atol(port));
}
|
#prepare(stmt_name, sql[, param_types ]) ⇒ PG::Result Also known as: async_prepare
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, $1, $2, etc., inside the SQL query.
See also corresponding libpq function.
3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 |
# File 'ext/pg_connection.c', line 3260
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 );
pgconn_block( 0, NULL, self ); /* wait for input (without blocking) before reading the last result */
rb_pgresult = pgconn_get_last_result( self );
if ( rb_block_given_p() ) {
return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
}
return rb_pgresult;
}
|
#protocol_version ⇒ Integer
The 3.0 protocol will normally be used when communicating with PostgreSQL 7.4 or later servers; pre-7.4 servers support only protocol 2.0. (Protocol 1.0 is obsolete and not supported by libpq.)
799 800 801 802 803 |
# File 'ext/pg_connection.c', line 799
static VALUE
pgconn_protocol_version(VALUE self)
{
return INT2NUM(PQprotocolVersion(pg_get_pgconn(self)));
}
|
#put_copy_data(buffer[, encoder]) ⇒ Boolean
Transmits buffer as copy data to the server. Returns true if the data was sent, false if it was not sent (false is only possible if the connection is in nonblocking mode, and this command would block).
encoder can be a PG::Coder derivation (typically PG::TextEncoder::CopyRow). This encodes the data fields given as buffer from an Array of Strings to PostgreSQL’s COPY text format inclusive proper escaping. Optionally the encoder can type cast the fields from various Ruby types in one step, if PG::TextEncoder::CopyRow#type_map is set accordingly.
Raises an exception if an error occurs.
See also #copy_data.
2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 |
# File 'ext/pg_connection.c', line 2452
static VALUE
pgconn_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;
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 = DATA_PTR( this->encoder_for_put_copy_data );
}
} else if( rb_obj_is_kind_of(encoder, rb_cPG_Coder) ) {
Data_Get_Struct( encoder, t_pg_coder, p_coder );
} else {
rb_raise( rb_eTypeError, "wrong encoder type %s (expected some kind of PG::Coder)",
rb_obj_classname( encoder ) );
}
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) {
VALUE error = rb_exc_new2(rb_ePGerror, PQerrorMessage(this->pgconn));
rb_iv_set(error, "@connection", self);
rb_exc_raise(error);
}
RB_GC_GUARD(intermediate);
RB_GC_GUARD(buffer);
return (ret) ? Qtrue : Qfalse;
}
|
#put_copy_end([ error_message ]) ⇒ Boolean
Sends end-of-data indication to the server.
error_message is an optional parameter, and if set, forces the COPY command to fail with the string error_message.
Returns true if the end-of-data was sent, false if it was not sent (false is only possible if the connection is in nonblocking mode, and this command would block).
2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 |
# File 'ext/pg_connection.c', line 2524
static VALUE
pgconn_put_copy_end(int argc, VALUE *argv, VALUE self)
{
VALUE str;
VALUE error;
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) {
error = rb_exc_new2(rb_ePGerror, PQerrorMessage(this->pgconn));
rb_iv_set(error, "@connection", self);
rb_exc_raise(error);
}
return (ret) ? Qtrue : Qfalse;
}
|
#quote_ident(str) ⇒ String #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.
2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 |
# File 'ext/pg_connection.c', line 2986
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;
}
|
#reset ⇒ Object
Resets the backend connection. This method closes the backend connection and tries to re-connect.
569 570 571 572 573 574 575 |
# File 'ext/pg_connection.c', line 569
static VALUE
pgconn_reset( VALUE self )
{
pgconn_close_socket_io( self );
gvl_PQreset( pg_get_pgconn(self) );
return self;
}
|
#reset_poll ⇒ Integer
Checks the status of a connection reset operation. See #connect_start and #connect_poll for usage information and return values.
604 605 606 607 608 609 610 |
# File 'ext/pg_connection.c', line 604
static VALUE
pgconn_reset_poll(VALUE self)
{
PostgresPollingStatusType status;
status = gvl_PQresetPoll(pg_get_pgconn(self));
return INT2FIX((int)status);
}
|
#reset_start ⇒ nil
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.
587 588 589 590 591 592 593 594 |
# File 'ext/pg_connection.c', line 587
static VALUE
pgconn_reset_start(VALUE self)
{
pgconn_close_socket_io( self );
if(gvl_PQresetStart(pg_get_pgconn(self)) == 0)
rb_raise(rb_eUnableToSend, "reset has failed");
return Qnil;
}
|
#send_describe_portal(portal_name) ⇒ nil
Asynchronously send command to the server. Does not block. Use in combination with conn.get_result
.
1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 |
# File 'ext/pg_connection.c', line 1994
static VALUE
pgconn_send_describe_portal(VALUE self, VALUE portal)
{
VALUE error;
t_pg_connection *this = pg_get_connection_safe( self );
/* returns 0 on failure */
if(gvl_PQsendDescribePortal(this->pgconn, pg_cstr_enc(portal, this->enc_idx)) == 0) {
error = rb_exc_new2(rb_eUnableToSend, PQerrorMessage(this->pgconn));
rb_iv_set(error, "@connection", self);
rb_exc_raise(error);
}
return Qnil;
}
|
#send_describe_prepared(statement_name) ⇒ nil
Asynchronously send command to the server. Does not block. Use in combination with conn.get_result
.
1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 |
# File 'ext/pg_connection.c', line 1972
static VALUE
pgconn_send_describe_prepared(VALUE self, VALUE stmt_name)
{
VALUE error;
t_pg_connection *this = pg_get_connection_safe( self );
/* returns 0 on failure */
if(gvl_PQsendDescribePrepared(this->pgconn, pg_cstr_enc(stmt_name, this->enc_idx)) == 0) {
error = rb_exc_new2(rb_eUnableToSend, PQerrorMessage(this->pgconn));
rb_iv_set(error, "@connection", self);
rb_exc_raise(error);
}
return Qnil;
}
|
#send_prepare(stmt_name, sql[, param_types ]) ⇒ nil
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, $1, $2, etc., inside the SQL query.
1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 |
# File 'ext/pg_connection.c', line 1853
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;
VALUE error;
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) {
error = rb_exc_new2(rb_eUnableToSend, PQerrorMessage(this->pgconn));
rb_iv_set(error, "@connection", self);
rb_exc_raise(error);
}
return Qnil;
}
|
#send_query(sql) ⇒ nil
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.
1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 |
# File 'ext/pg_connection.c', line 1740
static VALUE
pgconn_send_query(int argc, VALUE *argv, VALUE self)
{
t_pg_connection *this = pg_get_connection_safe( self );
VALUE error;
/* 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) {
error = rb_exc_new2(rb_eUnableToSend, PQerrorMessage(this->pgconn));
rb_iv_set(error, "@connection", self);
rb_exc_raise(error);
}
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
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, $1, $2, 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.
1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 |
# File 'ext/pg_connection.c', line 1802
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;
VALUE error;
int nParams;
int resultFormat;
struct query_params_data paramsData = { this->enc_idx };
rb_scan_args(argc, argv, "22", &command, ¶msData.params, &in_res_fmt, ¶msData.typemap);
paramsData.with_types = 1;
pgconn_query_assign_typemap( self, ¶msData );
resultFormat = NIL_P(in_res_fmt) ? 0 : NUM2INT(in_res_fmt);
nParams = alloc_query_params( ¶msData );
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( ¶msData );
if(result == 0) {
error = rb_exc_new2(rb_eUnableToSend, PQerrorMessage(this->pgconn));
rb_iv_set(error, "@connection", self);
rb_exc_raise(error);
}
return Qnil;
}
|
#send_query_prepared(statement_name[, params, result_format[, type_map ]]) ⇒ Object #- ⇒ Object
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, $1, $2, 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.
1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 |
# File 'ext/pg_connection.c', line 1928
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;
VALUE error;
int nParams;
int resultFormat;
struct query_params_data paramsData = { this->enc_idx };
rb_scan_args(argc, argv, "13", &name, ¶msData.params, &in_res_fmt, ¶msData.typemap);
paramsData.with_types = 0;
if(NIL_P(paramsData.params)) {
paramsData.params = rb_ary_new2(0);
resultFormat = 0;
}
pgconn_query_assign_typemap( self, ¶msData );
resultFormat = NIL_P(in_res_fmt) ? 0 : NUM2INT(in_res_fmt);
nParams = alloc_query_params( ¶msData );
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( ¶msData );
if(result == 0) {
error = rb_exc_new2(rb_eUnableToSend, PQerrorMessage(this->pgconn));
rb_iv_set(error, "@connection", self);
rb_exc_raise(error);
}
return Qnil;
}
|
#server_version ⇒ Integer
The number is formed by converting the major, minor, and revision numbers into two-decimal-digit numbers and appending them together. For example, version 7.4.2 will be returned as 70402, and version 8.1 will be returned as 80100 (leading zeroes are not shown). Zero is returned if the connection is bad.
816 817 818 819 820 |
# File 'ext/pg_connection.c', line 816
static VALUE
pgconn_server_version(VALUE self)
{
return INT2NUM(PQserverVersion(pg_get_pgconn(self)));
}
|
#set_client_encoding(encoding) ⇒ Object Also known as: client_encoding=
Sets the client encoding to the encoding String.
2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 |
# File 'ext/pg_connection.c', line 2891
static VALUE
pgconn_set_client_encoding(VALUE self, VALUE str)
{
PGconn *conn = pg_get_pgconn( self );
Check_Type(str, T_STRING);
if ( (gvl_PQsetClientEncoding(conn, StringValueCStr(str))) == -1 ) {
rb_raise(rb_ePGerror, "%s", PQerrorMessage(conn));
}
pgconn_set_internal_encoding_index( self );
return Qnil;
}
|
#set_default_encoding ⇒ Encoding
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.
3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 |
# File 'ext/pg_connection.c', line 3885
static VALUE
pgconn_set_default_encoding( VALUE self )
{
PGconn *conn = pg_get_pgconn( self );
rb_encoding *enc;
const char *encname;
if (( enc = rb_default_internal_encoding() )) {
encname = pg_get_rb_encoding_as_pg_encoding( enc );
if ( pgconn_set_client_encoding_async(self, 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( enc );
} else {
pgconn_set_internal_encoding_index( self );
return Qnil;
}
}
|
#set_error_context_visibility(context_visibility) ⇒ Integer
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.
Available since PostgreSQL-9.6
2662 2663 2664 2665 2666 2667 2668 |
# File 'ext/pg_connection.c', line 2662
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
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.
2632 2633 2634 2635 2636 2637 2638 |
# File 'ext/pg_connection.c', line 2632
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
See #set_notice_receiver for the desription 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.
2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 |
# File 'ext/pg_connection.c', line 2842
static VALUE
pgconn_set_notice_processor(VALUE self)
{
VALUE proc, old_proc;
t_pg_connection *this = pg_get_connection_safe( 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(default_notice_processor == NULL)
default_notice_processor = PQsetNoticeProcessor(this->pgconn, NULL, NULL);
old_proc = this->notice_receiver;
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, default_notice_processor, NULL);
}
this->notice_receiver = proc;
return old_proc;
}
|
#set_notice_receiver {|result| ... } ⇒ Proc
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.
2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 |
# File 'ext/pg_connection.c', line 2782
static VALUE
pgconn_set_notice_receiver(VALUE self)
{
VALUE proc, old_proc;
t_pg_connection *this = pg_get_connection_safe( 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(default_notice_receiver == NULL)
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, default_notice_receiver, NULL);
}
this->notice_receiver = proc;
return old_proc;
}
|
#set_single_row_mode ⇒ self
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 mode, those rows will have already been returned to the application. Hence, the application will see some Result objects followed by an 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
1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 |
# File 'ext/pg_connection.c', line 1709
static VALUE
pgconn_set_single_row_mode(VALUE self)
{
PGconn *conn = pg_get_pgconn(self);
VALUE error;
if( PQsetSingleRowMode(conn) == 0 )
{
error = rb_exc_new2(rb_ePGerror, PQerrorMessage(conn));
rb_iv_set(error, "@connection", self);
rb_exc_raise(error);
}
return self;
}
|
#setnonblocking(Boolean) ⇒ nil
Sets the nonblocking status of the connection. In the blocking state, calls to #send_query will block until the message is sent to the server, but will not wait for the query results. In the nonblocking state, calls to #send_query will return an error if the socket is not ready for writing. Note: This function does not affect #exec, because that function doesn’t return until the server has processed the query and returned the results. Returns nil
.
2096 2097 2098 |
# File 'ext/pg_connection.c', line 2096 static VALUE pgconn_setnonblocking(self, state) VALUE self, state; |
#socket ⇒ Integer
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.
853 854 855 856 857 858 859 860 861 862 |
# File 'ext/pg_connection.c', line 853
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)
rb_raise(rb_eConnectionBad, "PQsocket() can't get socket descriptor");
return INT2NUM(sd);
}
|
#socket_io ⇒ Object
Fetch a memorized IO object created from the Connection’s underlying socket. This object can be used for IO.select to wait for events while running asynchronous API calls.
Using this instead of #socket 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. In contrast to #socket, it also works on Windows.
876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 |
# File 'ext/pg_connection.c', line 876
static VALUE
pgconn_socket_io(VALUE self)
{
int sd;
int ruby_sd;
ID id_autoclose = rb_intern("autoclose=");
t_pg_connection *this = pg_get_connection_safe( self );
VALUE socket_io = this->socket_io;
if ( !RTEST(socket_io) ) {
if( (sd = PQsocket(this->pgconn)) < 0)
rb_raise(rb_eConnectionBad, "PQsocket() can't get socket descriptor");
#ifdef _WIN32
ruby_sd = rb_w32_wrap_io_handle((HANDLE)(intptr_t)sd, O_RDWR|O_BINARY|O_NOINHERIT);
this->ruby_sd = ruby_sd;
#else
ruby_sd = sd;
#endif
socket_io = rb_funcall( rb_cIO, rb_intern("for_fd"), 1, INT2NUM(ruby_sd) );
/* Disable autoclose feature */
rb_funcall( socket_io, id_autoclose, 1, Qfalse );
this->socket_io = socket_io;
}
return socket_io;
}
|
#ssl_attribute(attribute_name) ⇒ String
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.
Available since PostgreSQL-9.5
3424 3425 3426 3427 3428 3429 3430 3431 |
# File 'ext/pg_connection.c', line 3424
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>
Return an array of SSL attribute names available.
See also #ssl_attribute
Available since PostgreSQL-9.5
3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 |
# File 'ext/pg_connection.c', line 3443
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 ⇒ Object
call-seq:
conn.ssl_attributes -> Hash<String,String>
Returns SSL-related information about the connection as key/value pairs
The available attributes varies depending on the SSL library being used, and the type of connection.
See also #ssl_attribute
265 266 267 268 269 |
# File 'lib/pg/connection.rb', line 265 def ssl_attributes ssl_attribute_names.each.with_object({}) do |n,h| h[n] = ssl_attribute(n) end end |
#ssl_in_use? ⇒ Boolean
Returns true
if the connection uses SSL/TLS, false
if not.
Available since PostgreSQL-9.5
3390 3391 3392 3393 3394 |
# File 'ext/pg_connection.c', line 3390
static VALUE
pgconn_ssl_in_use(VALUE self)
{
return PQsslInUse(pg_get_pgconn(self)) ? Qtrue : Qfalse;
}
|
#status ⇒ Object
Returns status of connection : CONNECTION_OK or CONNECTION_BAD
740 741 742 743 744 |
# File 'ext/pg_connection.c', line 740
static VALUE
pgconn_status(VALUE self)
{
return INT2NUM(PQstatus(pg_get_pgconn(self)));
}
|
#sync_describe_portal(portal_name) ⇒ PG::Result
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.
1421 1422 1423 |
# File 'ext/pg_connection.c', line 1421 static VALUE pgconn_describe_portal(self, stmt_name) VALUE self, stmt_name; |
#sync_describe_prepared(statement_name) ⇒ PG::Result
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.
1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 |
# File 'ext/pg_connection.c', line 1393
static VALUE
pgconn_describe_prepared(VALUE self, VALUE stmt_name)
{
PGresult *result;
VALUE rb_pgresult;
t_pg_connection *this = pg_get_connection_safe( self );
const char *stmt;
if(NIL_P(stmt_name)) {
stmt = NULL;
}
else {
stmt = pg_cstr_enc(stmt_name, this->enc_idx);
}
result = gvl_PQdescribePrepared(this->pgconn, stmt);
rb_pgresult = pg_new_result(result, self);
pg_result_check(rb_pgresult);
return rb_pgresult;
}
|
#sync_exec(sql) ⇒ PG::Result #sync_exec(sql) {|pg_result| ... } ⇒ Object
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:
-
#async_exec can be aborted by signals (like Ctrl-C), while #exec blocks signal processing until the query is answered.
-
Ruby VM gets notified about IO blocked operations. It can therefore schedule things like garbage collection, while queries are running like in this proposal: bugs.ruby-lang.org/issues/14723
968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 |
# File 'ext/pg_connection.c', line 968
static VALUE
pgconn_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_exec_params( argc, argv, self );
}
|
#sync_exec_params(sql, params[, result_format[, type_map]]) ⇒ PG::Result #sync_exec_params(sql, params[, result_format[, type_map]]) {|pg_result| ... } ⇒ Object
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.
1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 |
# File 'ext/pg_connection.c', line 1248
static VALUE
pgconn_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, ¶msData.params, &in_res_fmt, ¶msData.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_exec( 1, argv, self );
}
pgconn_query_assign_typemap( self, ¶msData );
resultFormat = NIL_P(in_res_fmt) ? 0 : NUM2INT(in_res_fmt);
nParams = alloc_query_params( ¶msData );
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( ¶msData );
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 #sync_exec_prepared(statement_name[, params, result_format[, type_map]]) {|pg_result| ... } ⇒ Object
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.
1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 |
# File 'ext/pg_connection.c', line 1348
static VALUE
pgconn_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, ¶msData.params, &in_res_fmt, ¶msData.typemap);
paramsData.with_types = 0;
if(NIL_P(paramsData.params)) {
paramsData.params = rb_ary_new2(0);
}
pgconn_query_assign_typemap( self, ¶msData );
resultFormat = NIL_P(in_res_fmt) ? 0 : NUM2INT(in_res_fmt);
nParams = alloc_query_params( ¶msData );
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( ¶msData );
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_prepare(stmt_name, sql[, param_types ]) ⇒ PG::Result
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.
1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 |
# File 'ext/pg_connection.c', line 1299
static VALUE
pgconn_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;
}
|
#trace(stream) ⇒ nil
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.
2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 |
# File 'ext/pg_connection.c', line 2680
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 );
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));
this->trace_stream = new_file;
PQtrace(this->pgconn, new_fp);
return Qnil;
}
|
#transaction {|conn| ... } ⇒ Object
Executes a BEGIN
at the start of the block, and a COMMIT
at the end of the block, or ROLLBACK
if any exception occurs.
2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 |
# File 'ext/pg_connection.c', line 2914
static VALUE
pgconn_transaction(VALUE self)
{
PGconn *conn = pg_get_pgconn(self);
PGresult *result;
VALUE rb_pgresult;
VALUE block_result = Qnil;
int status;
if (rb_block_given_p()) {
result = gvl_PQexec(conn, "BEGIN");
rb_pgresult = pg_new_result(result, self);
pg_result_check(rb_pgresult);
block_result = rb_protect(rb_yield, self, &status);
if(status == 0) {
result = gvl_PQexec(conn, "COMMIT");
rb_pgresult = pg_new_result(result, self);
pg_result_check(rb_pgresult);
}
else {
/* exception occurred, ROLLBACK and re-raise */
result = gvl_PQexec(conn, "ROLLBACK");
rb_pgresult = pg_new_result(result, self);
pg_result_check(rb_pgresult);
rb_jump_tag(status);
}
}
else {
/* no block supplied? */
rb_raise(rb_eArgError, "Must supply block for PG::Connection#transaction");
}
return block_result;
}
|
#transaction_status ⇒ Object
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)
757 758 759 760 761 |
# File 'ext/pg_connection.c', line 757
static VALUE
pgconn_transaction_status(VALUE self)
{
return INT2NUM(PQtransactionStatus(pg_get_pgconn(self)));
}
|
#tty ⇒ Object
Returns the connected pgtty. (Obsolete)
688 689 690 691 692 693 694 |
# File 'ext/pg_connection.c', line 688
static VALUE
pgconn_tty(VALUE self)
{
char *tty = PQtty(pg_get_pgconn(self));
if (!tty) return Qnil;
return rb_str_new2(tty);
}
|
#type_map_for_queries ⇒ TypeMap
Returns the default TypeMap that is currently set for type casts of query bind parameters.
3938 3939 3940 3941 3942 3943 3944 |
# File 'ext/pg_connection.c', line 3938
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) ⇒ Object
Set the default TypeMap that is used for type casts of query bind parameters.
typemap
must be a kind of PG::TypeMap .
3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 |
# File 'ext/pg_connection.c', line 3915
static VALUE
pgconn_type_map_for_queries_set(VALUE self, VALUE typemap)
{
t_pg_connection *this = pg_get_connection( self );
if ( !rb_obj_is_kind_of(typemap, rb_cTypeMap) ) {
rb_raise( rb_eTypeError, "wrong argument type %s (expected kind of PG::TypeMap)",
rb_obj_classname( typemap ) );
}
Check_Type(typemap, T_DATA);
this->type_map_for_queries = typemap;
return typemap;
}
|
#type_map_for_results ⇒ TypeMap
Returns the default TypeMap that is currently set for type casts of result values.
3977 3978 3979 3980 3981 3982 3983 |
# File 'ext/pg_connection.c', line 3977
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) ⇒ Object
Set the default TypeMap that is used for type casts of result values.
typemap
must be a kind of PG::TypeMap .
3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 |
# File 'ext/pg_connection.c', line 3955
static VALUE
pgconn_type_map_for_results_set(VALUE self, VALUE typemap)
{
t_pg_connection *this = pg_get_connection( self );
if ( !rb_obj_is_kind_of(typemap, rb_cTypeMap) ) {
rb_raise( rb_eTypeError, "wrong argument type %s (expected kind of PG::TypeMap)",
rb_obj_classname( typemap ) );
}
Check_Type(typemap, T_DATA);
this->type_map_for_results = typemap;
return typemap;
}
|
#PG::Connection.unescape_bytea(string) ⇒ Object
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.
1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 |
# File 'ext/pg_connection.c', line 1578
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;
}
|
#untrace ⇒ nil
Disables the message tracing.
2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 |
# File 'ext/pg_connection.c', line 2722
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);
this->trace_stream = Qnil;
return Qnil;
}
|
#user ⇒ Object
Returns the authenticated user name.
633 634 635 636 637 638 639 |
# File 'ext/pg_connection.c', line 633
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| ... } ⇒ String Also known as: notifies_wait
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.
2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 |
# File 'ext/pg_connection.c', line 2392
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( this->pgconn, 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;
}
|