Class: ActiveRecord::ConnectionAdapters::PostgreSQLAdapter

Overview

The PostgreSQL adapter works with the native C (github.com/ged/ruby-pg) driver.

Options:

  • :host - Defaults to a Unix-domain socket in /tmp. On machines without Unix-domain sockets, the default is to connect to localhost.

  • :port - Defaults to 5432.

  • :username - Defaults to be the same as the operating system name of the user running the application.

  • :password - Password to be used if the server demands password authentication.

  • :database - Defaults to be the same as the user name.

  • :schema_search_path - An optional schema search path for the connection given as a string of comma-separated schema names. This is backward-compatible with the :schema_order option.

  • :encoding - An optional client encoding that is used in a SET client_encoding TO <encoding> call on the connection.

  • :min_messages - An optional client min messages that is used in a SET client_min_messages TO <min_messages> call on the connection.

  • :variables - An optional hash of additional parameters that will be used in SET SESSION key = val calls on the connection.

  • :insert_returning - An optional boolean to control the use of RETURNING for INSERT statements defaults to true.

Any further options are used as connection parameters to libpq. See www.postgresql.org/docs/current/static/libpq-connect.html for the list of parameters.

In addition, default connection parameters of libpq can be set per environment variables. See www.postgresql.org/docs/current/static/libpq-envars.html .

Defined Under Namespace

Classes: MoneyDecoder, StatementPool

Constant Summary collapse

ADAPTER_NAME =
"PostgreSQL"
NATIVE_DATABASE_TYPES =
{
  primary_key: "bigserial primary key",
  string:      { name: "character varying" },
  text:        { name: "text" },
  integer:     { name: "integer", limit: 4 },
  float:       { name: "float" },
  decimal:     { name: "decimal" },
  datetime:    { name: "timestamp" },
  time:        { name: "time" },
  date:        { name: "date" },
  daterange:   { name: "daterange" },
  numrange:    { name: "numrange" },
  tsrange:     { name: "tsrange" },
  tstzrange:   { name: "tstzrange" },
  int4range:   { name: "int4range" },
  int8range:   { name: "int8range" },
  binary:      { name: "bytea" },
  boolean:     { name: "boolean" },
  xml:         { name: "xml" },
  tsvector:    { name: "tsvector" },
  hstore:      { name: "hstore" },
  inet:        { name: "inet" },
  cidr:        { name: "cidr" },
  macaddr:     { name: "macaddr" },
  uuid:        { name: "uuid" },
  json:        { name: "json" },
  jsonb:       { name: "jsonb" },
  ltree:       { name: "ltree" },
  citext:      { name: "citext" },
  point:       { name: "point" },
  line:        { name: "line" },
  lseg:        { name: "lseg" },
  box:         { name: "box" },
  path:        { name: "path" },
  polygon:     { name: "polygon" },
  circle:      { name: "circle" },
  bit:         { name: "bit" },
  bit_varying: { name: "bit varying" },
  money:       { name: "money" },
  interval:    { name: "interval" },
  oid:         { name: "oid" },
}
OID =

:nodoc:

PostgreSQL::OID

Constants inherited from AbstractAdapter

AbstractAdapter::COMMENT_REGEX, AbstractAdapter::SIMPLE_INT

Instance Attribute Summary

Attributes inherited from AbstractAdapter

#lock, #logger, #owner, #pool, #visitor

Attributes included from QueryCache

#query_cache, #query_cache_enabled

Attributes included from DatabaseStatements

#transaction_manager

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ActiveRecord::ConnectionAdapters::PostgreSQL::DatabaseStatements

#begin_db_transaction, #begin_isolated_db_transaction, #commit_db_transaction, #exec_delete, #exec_insert, #exec_query, #exec_rollback_db_transaction, #execute, #explain, #query, #write_query?

Methods included from ActiveRecord::ConnectionAdapters::PostgreSQL::SchemaStatements

#add_column, #add_index, #change_column, #change_column_comment, #change_column_default, #change_column_null, #change_table_comment, #check_constraints, #client_min_messages, #client_min_messages=, #collation, #columns_for_distinct, #create_database, #create_schema, #create_schema_dumper, #ctype, #current_database, #current_schema, #default_sequence_name, #drop_database, #drop_schema, #drop_table, #encoding, #foreign_keys, #foreign_table_exists?, #foreign_tables, #index_name_exists?, #indexes, #pk_and_sequence_for, #primary_keys, #recreate_database, #remove_index, #rename_column, #rename_index, #rename_table, #reset_pk_sequence!, #schema_exists?, #schema_names, #schema_search_path, #schema_search_path=, #serial_sequence, #set_pk_sequence!, #table_comment, #table_options, #type_to_sql, #update_table_definition, #validate_check_constraint, #validate_constraint, #validate_foreign_key

Methods included from ActiveRecord::ConnectionAdapters::PostgreSQL::ReferentialIntegrity

#disable_referential_integrity

Methods included from ActiveRecord::ConnectionAdapters::PostgreSQL::Quoting

#column_name_matcher, #column_name_with_order_matcher, #escape_bytea, #lookup_cast_type_from_column, #quote_column_name, #quote_default_expression, #quote_schema_name, #quote_string, #quote_table_name, #quote_table_name_for_assignment, #quoted_binary, #quoted_date, #unescape_bytea

Methods inherited from AbstractAdapter

#adapter_name, #advisory_locks_enabled?, build_read_query_regexp, #case_insensitive_comparison, #case_sensitive_comparison, #clear_cache!, #close, #connection_klass, #database_version, #default_uniqueness_comparison, #disable_referential_integrity, #expire, #lease, #migration_context, #migrations_paths, #prefetch_primary_key?, #prepared_statements?, #prepared_statements_disabled_cache, #preventing_writes?, quoted_column_names, quoted_table_names, #raw_connection, #replica?, #requires_reloading?, #schema_cache, #schema_cache=, #schema_migration, #seconds_idle, #steal!, #supports_comments_in_create?, #supports_indexes_in_create?, #supports_virtual_columns?, #throw_away!, type_cast_config_to_boolean, type_cast_config_to_integer, #unprepared_statement, #use_metadata_table?, #valid_type?, #verify!

Methods included from Savepoints

#create_savepoint, #current_savepoint_name, #exec_rollback_to_savepoint, #release_savepoint

Methods included from QueryCache

#cache, #clear_query_cache, dirties_query_cache, #disable_query_cache!, #enable_query_cache!, included, #select_all, #uncached

Methods included from DatabaseLimits

#allowed_index_name_length, #in_clause_length, #index_name_length, #table_alias_length

Methods included from Quoting

#column_name_matcher, #column_name_with_order_matcher, #lookup_cast_type_from_column, #quote, #quote_column_name, #quote_default_expression, #quote_string, #quote_table_name, #quote_table_name_for_assignment, #quoted_binary, #quoted_date, #quoted_false, #quoted_time, #quoted_true, #sanitize_as_sql_comment, #type_cast, #unquoted_false, #unquoted_true

Methods included from DatabaseStatements

#add_transaction_record, #begin_db_transaction, #begin_isolated_db_transaction, #cacheable_query, #commit_db_transaction, #default_sequence_name, #delete, #empty_insert_statement_value, #exec_delete, #exec_insert, #exec_insert_all, #exec_query, #exec_rollback_db_transaction, #exec_update, #execute, #explain, #insert, #insert_fixture, #insert_fixtures_set, #mark_transaction_written_if_write, #query, #query_value, #query_values, #reset_sequence!, #reset_transaction, #rollback_db_transaction, #rollback_to_savepoint, #sanitize_limit, #select_all, #select_one, #select_rows, #select_value, #select_values, #to_sql, #transaction, #transaction_isolation_levels, #transaction_open?, #truncate, #truncate_tables, #update, #with_yaml_fallback, #write_query?

Methods included from SchemaStatements

#add_check_constraint, #add_column, #add_columns, #add_foreign_key, #add_index, #add_index_options, #add_reference, #add_timestamps, #assume_migrated_upto_version, #change_column, #change_column_comment, #change_column_default, #change_column_null, #change_table, #change_table_comment, #check_constraint_options, #check_constraints, #column_exists?, #columns, #columns_for_distinct, #create_join_table, #create_schema_dumper, #create_table, #data_source_exists?, #data_sources, #drop_join_table, #drop_table, #dump_schema_information, #foreign_key_column_for, #foreign_key_exists?, #foreign_key_options, #foreign_keys, #index_algorithm, #index_exists?, #index_name, #index_name_exists?, #indexes, #internal_string_options_for_primary_key, #options_include_default?, #primary_key, #quoted_columns_for_index, #remove_check_constraint, #remove_column, #remove_columns, #remove_foreign_key, #remove_index, #remove_reference, #remove_timestamps, #rename_column, #rename_index, #rename_table, #table_alias_for, #table_comment, #table_exists?, #table_options, #tables, #type_to_sql, #update_table_definition, #view_exists?, #views

Constructor Details

#initialize(connection, logger, connection_parameters, config) ⇒ PostgreSQLAdapter

Initializes and connects a PostgreSQL adapter.



247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 247

def initialize(connection, logger, connection_parameters, config)
  super(connection, logger, config)

  @connection_parameters = connection_parameters

  # @local_tz is initialized as nil to avoid warnings when connect tries to use it
  @local_tz = nil
  @max_identifier_length = nil

  configure_connection
  add_pg_encoders
  add_pg_decoders

  @type_map = Type::HashLookupTypeMap.new
  initialize_type_map
  @local_tz = execute("SHOW TIME ZONE", "SCHEMA").first["TimeZone"]
  @use_insert_returning = @config.key?(:insert_returning) ? self.class.type_cast_config_to_boolean(@config[:insert_returning]) : true
end

Class Method Details

.database_exists?(config) ⇒ Boolean

Returns:

  • (Boolean)


266
267
268
269
270
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 266

def self.database_exists?(config)
  !!ActiveRecord::Base.postgresql_connection(config)
rescue ActiveRecord::NoDatabaseError
  false
end

.new_client(conn_params) ⇒ Object



77
78
79
80
81
82
83
84
85
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 77

def new_client(conn_params)
  PG.connect(conn_params)
rescue ::PG::Error => error
  if conn_params && conn_params[:dbname] && error.message.include?(conn_params[:dbname])
    raise ActiveRecord::NoDatabaseError
  else
    raise ActiveRecord::ConnectionNotEstablished, error.message
  end
end

Instance Method Details

#active?Boolean

Is this connection alive and ready for queries?

Returns:

  • (Boolean)


273
274
275
276
277
278
279
280
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 273

def active?
  @lock.synchronize do
    @connection.query "SELECT 1"
  end
  true
rescue PG::Error
  false
end

#build_insert_sql(insert) ⇒ Object

:nodoc:



434
435
436
437
438
439
440
441
442
443
444
445
446
447
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 434

def build_insert_sql(insert) # :nodoc:
  sql = +"INSERT #{insert.into} #{insert.values_list}"

  if insert.skip_duplicates?
    sql << " ON CONFLICT #{insert.conflict_target} DO NOTHING"
  elsif insert.update_duplicates?
    sql << " ON CONFLICT #{insert.conflict_target} DO UPDATE SET "
    sql << insert.touch_model_timestamps_unless { |column| "#{insert.model.quoted_table_name}.#{column} IS NOT DISTINCT FROM excluded.#{column}" }
    sql << insert.updatable_columns.map { |column| "#{column}=excluded.#{column}" }.join(",")
  end

  sql << " RETURNING #{insert.returning}" if insert.returning
  sql
end

#check_versionObject

:nodoc:



449
450
451
452
453
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 449

def check_version # :nodoc:
  if database_version < 90300
    raise "Your version of PostgreSQL (#{database_version}) is too old. Active Record supports PostgreSQL >= 9.3."
  end
end

#create_unlogged_tablesObject

:singleton-method: PostgreSQL allows the creation of “unlogged” tables, which do not record data in the PostgreSQL Write-Ahead Log. This can make the tables faster, but significantly increases the risk of data loss if the database crashes. As a result, this should not be used in production environments. If you would like all created tables to be unlogged in the test environment you can add the following line to your test.rb file:

ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.create_unlogged_tables = true


99
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 99

class_attribute :create_unlogged_tables, default: false

#default_index_type?(index) ⇒ Boolean

:nodoc:

Returns:

  • (Boolean)


430
431
432
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 430

def default_index_type?(index) # :nodoc:
  index.using == :btree || super
end

#disable_extension(name) ⇒ Object



391
392
393
394
395
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 391

def disable_extension(name)
  exec_query("DROP EXTENSION IF EXISTS \"#{name}\" CASCADE").tap {
    reload_type_map
  }
end

#discard!Object

:nodoc:



314
315
316
317
318
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 314

def discard! # :nodoc:
  super
  @connection.socket_io.reopen(IO::NULL) rescue nil
  @connection = nil
end

#disconnect!Object

Disconnects from the database if already connected. Otherwise, this method does nothing.



307
308
309
310
311
312
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 307

def disconnect!
  @lock.synchronize do
    super
    @connection.close rescue nil
  end
end

#enable_extension(name) ⇒ Object



385
386
387
388
389
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 385

def enable_extension(name)
  exec_query("CREATE EXTENSION IF NOT EXISTS \"#{name}\"").tap {
    reload_type_map
  }
end

#extension_available?(name) ⇒ Boolean

Returns:

  • (Boolean)


397
398
399
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 397

def extension_available?(name)
  query_value("SELECT true FROM pg_available_extensions WHERE name = #{quote(name)}", "SCHEMA")
end

#extension_enabled?(name) ⇒ Boolean

Returns:

  • (Boolean)


401
402
403
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 401

def extension_enabled?(name)
  query_value("SELECT installed_version IS NOT NULL FROM pg_available_extensions WHERE name = #{quote(name)}", "SCHEMA")
end

#extensionsObject



405
406
407
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 405

def extensions
  exec_query("SELECT extname FROM pg_extension", "SCHEMA").cast_values
end

#get_advisory_lock(lock_id) ⇒ Object

:nodoc:



371
372
373
374
375
376
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 371

def get_advisory_lock(lock_id) # :nodoc:
  unless lock_id.is_a?(Integer) && lock_id.bit_length <= 63
    raise(ArgumentError, "PostgreSQL requires advisory lock ids to be a signed 64 bit integer")
  end
  query_value("SELECT pg_try_advisory_lock(#{lock_id})")
end

#get_database_versionObject

Returns the version of the connected PostgreSQL server.



425
426
427
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 425

def get_database_version # :nodoc:
  @connection.server_version
end

#index_algorithmsObject



218
219
220
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 218

def index_algorithms
  { concurrently: "CONCURRENTLY" }
end

#max_identifier_lengthObject

Returns the configured supported identifier length supported by PostgreSQL



410
411
412
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 410

def max_identifier_length
  @max_identifier_length ||= query_value("SHOW max_identifier_length", "SCHEMA").to_i
end

#native_database_typesObject

:nodoc:



320
321
322
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 320

def native_database_types #:nodoc:
  NATIVE_DATABASE_TYPES
end

#reconnect!Object

Close then reopen the connection.



283
284
285
286
287
288
289
290
291
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 283

def reconnect!
  @lock.synchronize do
    super
    @connection.reset
    configure_connection
  rescue PG::ConnectionBad
    connect
  end
end

#release_advisory_lock(lock_id) ⇒ Object

:nodoc:



378
379
380
381
382
383
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 378

def release_advisory_lock(lock_id) # :nodoc:
  unless lock_id.is_a?(Integer) && lock_id.bit_length <= 63
    raise(ArgumentError, "PostgreSQL requires advisory lock ids to be a signed 64 bit integer")
  end
  query_value("SELECT pg_advisory_unlock(#{lock_id})")
end

#reset!Object



293
294
295
296
297
298
299
300
301
302
303
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 293

def reset!
  @lock.synchronize do
    clear_cache!
    reset_transaction
    unless @connection.transaction_status == ::PG::PQTRANS_IDLE
      @connection.query "ROLLBACK"
    end
    @connection.query "DISCARD ALL"
    configure_connection
  end
end

#session_auth=(user) ⇒ Object

Set the authorized user for this session



415
416
417
418
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 415

def session_auth=(user)
  clear_cache!
  execute("SET SESSION AUTHORIZATION #{user}")
end

#set_standard_conforming_stringsObject



324
325
326
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 324

def set_standard_conforming_strings
  execute("SET standard_conforming_strings = on", "SCHEMA")
end

#supports_advisory_locks?Boolean

Returns:

  • (Boolean)


332
333
334
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 332

def supports_advisory_locks?
  true
end

#supports_bulk_alter?Boolean

Returns:

  • (Boolean)


151
152
153
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 151

def supports_bulk_alter?
  true
end

#supports_check_constraints?Boolean

Returns:

  • (Boolean)


179
180
181
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 179

def supports_check_constraints?
  true
end

#supports_comments?Boolean

Returns:

  • (Boolean)


199
200
201
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 199

def supports_comments?
  true
end

#supports_common_table_expressions?Boolean

Returns:

  • (Boolean)


363
364
365
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 363

def supports_common_table_expressions?
  true
end

#supports_datetime_with_precision?Boolean

Returns:

  • (Boolean)


191
192
193
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 191

def supports_datetime_with_precision?
  true
end

#supports_ddl_transactions?Boolean

Returns:

  • (Boolean)


328
329
330
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 328

def supports_ddl_transactions?
  true
end

#supports_explain?Boolean

Returns:

  • (Boolean)


336
337
338
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 336

def supports_explain?
  true
end

#supports_expression_index?Boolean

Returns:

  • (Boolean)


167
168
169
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 167

def supports_expression_index?
  true
end

#supports_extensions?Boolean

Returns:

  • (Boolean)


340
341
342
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 340

def supports_extensions?
  true
end

#supports_foreign_keys?Boolean

Returns:

  • (Boolean)


175
176
177
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 175

def supports_foreign_keys?
  true
end

#supports_foreign_tables?Boolean

Returns:

  • (Boolean)


348
349
350
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 348

def supports_foreign_tables?
  true
end

#supports_index_sort_order?Boolean

Returns:

  • (Boolean)


155
156
157
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 155

def supports_index_sort_order?
  true
end

#supports_insert_on_conflict?Boolean Also known as: supports_insert_on_duplicate_skip?, supports_insert_on_duplicate_update?, supports_insert_conflict_target?

Returns:

  • (Boolean)


211
212
213
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 211

def supports_insert_on_conflict?
  database_version >= 90500
end

#supports_insert_returning?Boolean

Returns:

  • (Boolean)


207
208
209
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 207

def supports_insert_returning?
  true
end

#supports_json?Boolean

Returns:

  • (Boolean)


195
196
197
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 195

def supports_json?
  true
end

#supports_lazy_transactions?Boolean

Returns:

  • (Boolean)


367
368
369
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 367

def supports_lazy_transactions?
  true
end

#supports_materialized_views?Boolean

Returns:

  • (Boolean)


344
345
346
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 344

def supports_materialized_views?
  true
end

#supports_optimizer_hints?Boolean

Returns:

  • (Boolean)


356
357
358
359
360
361
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 356

def supports_optimizer_hints?
  unless defined?(@has_pg_hint_plan)
    @has_pg_hint_plan = extension_available?("pg_hint_plan")
  end
  @has_pg_hint_plan
end

#supports_partial_index?Boolean

Returns:

  • (Boolean)


163
164
165
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 163

def supports_partial_index?
  true
end

#supports_partitioned_indexes?Boolean

Returns:

  • (Boolean)


159
160
161
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 159

def supports_partitioned_indexes?
  database_version >= 110_000
end

#supports_pgcrypto_uuid?Boolean

Returns:

  • (Boolean)


352
353
354
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 352

def supports_pgcrypto_uuid?
  database_version >= 90400
end

#supports_savepoints?Boolean

Returns:

  • (Boolean)


203
204
205
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 203

def supports_savepoints?
  true
end

#supports_transaction_isolation?Boolean

Returns:

  • (Boolean)


171
172
173
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 171

def supports_transaction_isolation?
  true
end

#supports_validate_constraints?Boolean

Returns:

  • (Boolean)


183
184
185
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 183

def supports_validate_constraints?
  true
end

#supports_views?Boolean

Returns:

  • (Boolean)


187
188
189
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 187

def supports_views?
  true
end

#use_insert_returning?Boolean

Returns:

  • (Boolean)


420
421
422
# File 'lib/active_record/connection_adapters/postgresql_adapter.rb', line 420

def use_insert_returning?
  @use_insert_returning
end