The PostgreSQL adapter works both with the native C (ruby.scripting.ca/postgres/) and the pure Ruby (available both as gem and from rubyforge.org/frs/?group_id=234&release_id=1944) drivers.

Options:

  • :host- Defaults to “localhost”.

  • :port- Defaults to 5432.

  • :username- Defaults to nothing.

  • :password- Defaults to nothing.

  • :database- The name of the database. No default, must be provided.

  • :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_orderoption.

  • :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.

  • :allow_concurrency- If true, use async query methods so Ruby threads don't deadlock; otherwise, use blocking query methods.

Methods
A
B
C
D
E
I
N
O
P
Q
R
S
T
U
Constants
ADAPTER_NAME = 'PostgreSQL'.freeze
 
NATIVE_DATABASE_TYPES = { :primary_key => "serial primary key".freeze, :string => { :name => "character varying", :limit => 255 }, :text => { :name => "text" }, :integer => { :name => "integer" }, :float => { :name => "float" }, :decimal => { :name => "decimal" }, :datetime => { :name => "timestamp" }, :timestamp => { :name => "timestamp" }, :time => { :name => "time" }, :date => { :name => "date" }, :binary => { :name => "bytea" }, :boolean => { :name => "boolean" }, :xml => { :name => "xml" } }
 
MONEY_COLUMN_TYPE_OID = 790
 

The internal PostgreSQL identifier of the money data type.

Class Public methods
new(connection, logger, connection_parameters, config)

Initializes and connects a PostgreSQL adapter.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 213
def initialize(connection, logger, connection_parameters, config)
  super(connection, logger)
  @connection_parameters, @config = connection_parameters, config
  connect
end
Instance Public methods
active?()

Is this connection alive and ready for queries?

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 221
def active?
  if @connection.respond_to?(:status)
    @connection.status == PGconn::CONNECTION_OK
  else
    # We're asking the driver, not ActiveRecord, so use @connection.query instead of #query
    @connection.query 'SELECT 1'
    true
  end
# postgres-pr raises a NoMethodError when querying if no connection is available.
rescue PGError, NoMethodError
  false
end
adapter_name()

Returns 'PostgreSQL' as adapter name for identification purposes.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 208
def adapter_name
  ADAPTER_NAME
end
add_column(table_name, column_name, type, options = {})

Adds a new column to the named table. See ActiveRecord::ConnectionAdapters::TableDefinition#column for details of the options you can use.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 808
def add_column(table_name, column_name, type, options = {})
  default = options[:default]
  notnull = options[:null] == false
  # Add the column.
  execute("ALTER TABLE #{quote_table_name(table_name)} ADD COLUMN #{quote_column_name(column_name)} #{type_to_sql(type, options[:limit], options[:precision], options[:scale])}")
  change_column_default(table_name, column_name, default) if options_include_default?(options)
  change_column_null(table_name, column_name, false, default) if notnull
end
begin_db_transaction()

Begins a transaction.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 535
def begin_db_transaction
  execute "BEGIN"
end
change_column(table_name, column_name, type, options = {})

Changes the column of a table.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 820
def change_column(table_name, column_name, type, options = {})
  quoted_table_name = quote_table_name(table_name)
  begin
    execute "ALTER TABLE #{quoted_table_name} ALTER COLUMN #{quote_column_name(column_name)} TYPE #{type_to_sql(type, options[:limit], options[:precision], options[:scale])}"
  rescue ActiveRecord::StatementInvalid => e
    raise e if postgresql_version > 80000
    # This is PostgreSQL 7.x, so we have to use a more arcane way of doing it.
    begin
      begin_db_transaction
      tmp_column_name = "#{column_name}_ar_tmp"
      add_column(table_name, tmp_column_name, type, options)
      execute "UPDATE #{quoted_table_name} SET #{quote_column_name(tmp_column_name)} = CAST(#{quote_column_name(column_name)} AS #{type_to_sql(type, options[:limit], options[:precision], options[:scale])})"
      remove_column(table_name, column_name)
      rename_column(table_name, tmp_column_name, column_name)
      commit_db_transaction
    rescue
      rollback_db_transaction
    end
  end
  change_column_default(table_name, column_name, options[:default]) if options_include_default?(options)
  change_column_null(table_name, column_name, options[:null], options[:default]) if options.key?(:null)
end
change_column_default(table_name, column_name, default)

Changes the default value of a table column.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 846
def change_column_default(table_name, column_name, default)
  execute "ALTER TABLE #{quote_table_name(table_name)} ALTER COLUMN #{quote_column_name(column_name)} SET DEFAULT #{quote(default)}"
end
change_column_null(table_name, column_name, null, default = nil)
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 850
def change_column_null(table_name, column_name, null, default = nil)
  unless null || default.nil?
    execute("UPDATE #{quote_table_name(table_name)} SET #{quote_column_name(column_name)}=#{quote(default)} WHERE #{quote_column_name(column_name)} IS NULL")
  end
  execute("ALTER TABLE #{quote_table_name(table_name)} ALTER #{quote_column_name(column_name)} #{null ? 'DROP' : 'SET'} NOT NULL")
end
client_min_messages()

Returns the current client message level.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 711
def client_min_messages
  query('SHOW client_min_messages')[0][0]
end
client_min_messages=(level)

Set the client message level.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 716
def client_min_messages=(level)
  execute("SET client_min_messages TO '#{level}'")
end
columns(table_name, name = nil)

Returns the list of all column definitions for a table.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 673
def columns(table_name, name = nil)
  # Limit, precision, and scale are all handled by the superclass.
  column_definitions(table_name).collect do |name, type, default, notnull|
    PostgreSQLColumn.new(name, default, type, notnull == 'f')
  end
end
commit_db_transaction()

Commits a transaction.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 540
def commit_db_transaction
  execute "COMMIT"
end
create_database(name, options = {})

Create a new PostgreSQL database. Options include :owner, :template, :encoding, :tablespace, and :connection_limit(note that MySQL uses :charsetwhile PostgreSQL uses :encoding).

Example:

create_database config[:database], config
create_database 'foo_development', :encoding => 'unicode'
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 583
def create_database(name, options = {})
  options = options.reverse_merge(:encoding => "utf8")
  option_string = options.symbolize_keys.sum do |key, value|
    case key
    when :owner
      " OWNER = \"#{value}\""
    when :template
      " TEMPLATE = \"#{value}\""
    when :encoding
      " ENCODING = '#{value}'"
    when :tablespace
      " TABLESPACE = \"#{value}\""
    when :connection_limit
      " CONNECTION LIMIT = #{value}"
    else
      ""
    end
  end
  execute "CREATE DATABASE #{quote_table_name(name)}#{option_string}"
end
create_savepoint()
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 557
def create_savepoint
  execute("SAVEPOINT #{current_savepoint_name}")
end
current_database()

Returns the current database name.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 681
def current_database
  query('select current_database()')[0][0]
end
disconnect!()

Close the connection.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 246
def disconnect!
  @connection.close rescue nil
end
encoding()

Returns the current database encoding format.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 686
      def encoding
        query("          SELECT pg_encoding_to_char(pg_database.encoding) FROM pg_database
          WHERE pg_database.datname LIKE '#{current_database}'
")[0][0]
      end
escape_bytea(original_value)

Escapes binary strings for bytea input to the database.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 293
def escape_bytea(original_value)
  if @connection.respond_to?(:escape_bytea)
    self.class.instance_eval do
      define_method(:escape_bytea) do |value|
        @connection.escape_bytea(value) if value
      end
    end
  elsif PGconn.respond_to?(:escape_bytea)
    self.class.instance_eval do
      define_method(:escape_bytea) do |value|
        PGconn.escape_bytea(value) if value
      end
    end
  else
    self.class.instance_eval do
      define_method(:escape_bytea) do |value|
        if value
          result = ''
          value.each_byte { |c| result << sprintf('\\%03o', c) }
          result
        end
      end
    end
  end
  escape_bytea(original_value)
end
execute(sql, name = nil)

Executes an SQL statement, returning a PGresult object on success or raising a PGError exception otherwise.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 519
def execute(sql, name = nil)
  log(sql, name) do
    if @async
      @connection.async_exec(sql)
    else
      @connection.exec(sql)
    end
  end
end
index_name_length()
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 866
def index_name_length
  63
end
indexes(table_name, name = nil)

Returns the list of all indexes for a table.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 634
      def indexes(table_name, name = nil)
         schemas = schema_search_path.split(/,/).map { |p| quote(p) }.join(',')
         result = query("           SELECT distinct i.relname, d.indisunique, d.indkey, t.oid
             FROM pg_class t, pg_class i, pg_index d
           WHERE i.relkind = 'i'
             AND d.indexrelid = i.oid
             AND d.indisprimary = 'f'
             AND t.oid = d.indrelid
             AND t.relname = '#{table_name}'
             AND i.relnamespace IN (SELECT oid FROM pg_namespace WHERE nspname IN (#{schemas}) )
          ORDER BY i.relname
", name)
        indexes = []
        indexes = result.map do |row|
          index_name = row[0]
          unique = row[1] == 't'
          indkey = row[2].split(" ")
          oid = row[3]
          columns = query("          SELECT a.attname, a.attnum
          FROM pg_attribute a
          WHERE a.attrelid = #{oid}
          AND a.attnum IN (#{indkey.join(",")})
", "Columns for index #{row[0]} on #{table_name}").inject({}) {|attlist, r| attlist[r[1]] = r[0]; attlist}
          column_names = indkey.map {|attnum| columns[attnum] }
          IndexDefinition.new(table_name, index_name, unique, column_names)
        end
        indexes
      end
insert(sql, name = nil, pk = nil, id_value = nil, sequence_name = nil)

Executes an INSERT query and returns the new record's ID

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 452
def insert(sql, name = nil, pk = nil, id_value = nil, sequence_name = nil)
  # Extract the table from the insert sql. Yuck.
  table = sql.split(" ", 4)[2].gsub('"', '')
  # Try an insert with 'returning id' if available (PG >= 8.2)
  if supports_insert_with_returning?
    pk, sequence_name = *pk_and_sequence_for(table) unless pk
    if pk
      id = select_value("#{sql} RETURNING #{quote_column_name(pk)}")
      clear_query_cache
      return id
    end
  end
  # Otherwise, insert then grab last_insert_id.
  if insert_id = super
    insert_id
  else
    # If neither pk nor sequence name is given, look them up.
    unless pk || sequence_name
      pk, sequence_name = *pk_and_sequence_for(table)
    end
    # If a pk is given, fallback to default sequence name.
    # Don't fetch last insert id for a table without a pk.
    if pk && sequence_name ||= default_sequence_name(table, pk)
      last_insert_id(table, sequence_name)
    end
  end
end
outside_transaction?()

The ruby-pg driver supports inspecting the transaction status, while the ruby-postgres driver does not.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 552
def outside_transaction?
  @connection.transaction_status == PGconn::PQTRANS_IDLE
end
primary_key(table)

Returns just a table's primary key

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 796
def primary_key(table)
  pk_and_sequence = pk_and_sequence_for(table)
  pk_and_sequence && pk_and_sequence.first
end
quote_table_name(name)

Checks the following cases:

  • table_name

  • “table.name”

  • schema_name.table_name

  • schema_name.“table.name”

  • “schema.name”.table_name

  • “schema.name”.“table.name”

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 397
def quote_table_name(name)
  schema, name_part = extract_pg_identifier_from_name(name.to_s)
  unless name_part
    quote_column_name(schema)
  else
    table_name, name_part = extract_pg_identifier_from_name(name_part)
    "#{quote_column_name(schema)}.#{quote_column_name(table_name)}"
  end
end
reconnect!()

Close then reopen the connection.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 235
def reconnect!
  if @connection.respond_to?(:reset)
    @connection.reset
    configure_connection
  else
    disconnect!
    connect
  end
end
release_savepoint()
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 565
def release_savepoint
  execute("RELEASE SAVEPOINT #{current_savepoint_name}")
end
rename_column(table_name, column_name, new_column_name)

Renames a column in a table.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 858
def rename_column(table_name, column_name, new_column_name)
  execute "ALTER TABLE #{quote_table_name(table_name)} RENAME COLUMN #{quote_column_name(column_name)} TO #{quote_column_name(new_column_name)}"
end
rename_table(name, new_name)

Renames a table.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 802
def rename_table(name, new_name)
  execute "ALTER TABLE #{quote_table_name(name)} RENAME TO #{quote_table_name(new_name)}"
end
rollback_db_transaction()

Aborts a transaction.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 545
def rollback_db_transaction
  execute "ROLLBACK"
end
rollback_to_savepoint()
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 561
def rollback_to_savepoint
  execute("ROLLBACK TO SAVEPOINT #{current_savepoint_name}")
end
schema_search_path()

Returns the active schema search path.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 706
def schema_search_path
  @schema_search_path ||= query('SHOW search_path')[0][0]
end
schema_search_path=(schema_csv)

Sets the schema search path to a string of comma-separated schema names. Names beginning with $ have to be quoted (e.g. $user => '$user'). See: www.postgresql.org/docs/current/static/ddl-schemas.html

This should be not be called manually but set in database.yml.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 698
def schema_search_path=(schema_csv)
  if schema_csv
    execute "SET search_path TO #{schema_csv}"
    @schema_search_path = schema_csv
  end
end
select_rows(sql, name = nil)

Executes a SELECT query and returns an array of rows. Each row is an array of field values.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 447
def select_rows(sql, name = nil)
  select_raw(sql, name).last
end
set_standard_conforming_strings()

Enable standard-conforming strings if available.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 265
def set_standard_conforming_strings
  old, self.client_min_messages = client_min_messages, 'panic'
  execute('SET standard_conforming_strings = on') rescue nil
ensure
  self.client_min_messages = old
end
supports_ddl_transactions?()
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 276
def supports_ddl_transactions?
  true
end
supports_insert_with_returning?()
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 272
def supports_insert_with_returning?
  postgresql_version >= 80200
end
supports_migrations?()

Does PostgreSQL support migrations?

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 255
def supports_migrations?
  true
end
supports_savepoints?()
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 280
def supports_savepoints?
  true
end
table_alias_length()

Returns the configured supported identifier length supported by PostgreSQL, or report the default of 63 on PostgreSQL 7.x.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 286
def table_alias_length
  @table_alias_length ||= (postgresql_version >= 80000 ? query('SHOW max_identifier_length')[0][0].to_i : 63)
end
tables(name = nil)

Returns the list of all tables in the schema search path or a specified schema.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 624
      def tables(name = nil)
        schemas = schema_search_path.split(/,/).map { |p| quote(p) }.join(',')
        query("          SELECT tablename
            FROM pg_tables
           WHERE schemaname IN (#{schemas})
", name).map { |row| row[0] }
      end
type_to_sql(type, limit = nil, precision = nil, scale = nil)

Maps logical Rails types to PostgreSQL-specific data types.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 871
def type_to_sql(type, limit = nil, precision = nil, scale = nil)
  return super unless type.to_s == 'integer'
  case limit
    when 1..2;      'smallint'
    when 3..4, nil; 'integer'
    when 5..8;      'bigint'
    else raise(ActiveRecordError, "No integer type has byte size #{limit}. Use a numeric with precision 0 instead.")
  end
end
unescape_bytea(original_value)

Unescapes bytea output from a database to the binary string it represents. NOTE: This is NOT an inverse of #escape_bytea! This is only to be used

on escaped binary output from database drive.
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 323
def unescape_bytea(original_value)
  # In each case, check if the value actually is escaped PostgreSQL bytea output
  # or an unescaped Active Record attribute that was just written.
  if @connection.respond_to?(:unescape_bytea)
    self.class.instance_eval do
      define_method(:unescape_bytea) do |value|
        @connection.unescape_bytea(value) if value
      end
    end
  elsif PGconn.respond_to?(:unescape_bytea)
    self.class.instance_eval do
      define_method(:unescape_bytea) do |value|
        PGconn.unescape_bytea(value) if value
      end
    end
  else
    raise 'Your PostgreSQL connection does not support unescape_bytea. Try upgrading to pg 0.9.0 or later.'
  end
  unescape_bytea(original_value)
end
update_sql(sql, name = nil)

Executes an UPDATE query and returns the number of affected tuples.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 530
def update_sql(sql, name = nil)
  super.cmd_tuples
end
Instance Protected methods
postgresql_version()

Returns the version of the connected PostgreSQL version.

# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 919
def postgresql_version
  @postgresql_version ||=
    if @connection.respond_to?(:server_version)
      @connection.server_version
    else
      # Mimic PGconn.server_version behavior
      begin
        query('SELECT version()')[0][0] =~ /PostgreSQL (\d+)\.(\d+)\.(\d+)/
        ($1.to_i * 10000) + ($2.to_i * 100) + $3.to_i
      rescue
        0
      end
    end
end