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_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.
  • :allow_concurrency - If true, use async query methods so Ruby threads don‘t deadlock; otherwise, use blocking query methods.
Methods
Public Class methods
new(connection, logger, connection_parameters, config)

Initializes and connects a PostgreSQL adapter.

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 255
255:       def initialize(connection, logger, connection_parameters, config)
256:         super(connection, logger)
257:         @connection_parameters, @config = connection_parameters, config
258: 
259:         connect
260:       end
Public Instance methods
active?()

Is this connection alive and ready for queries?

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 263
263:       def active?
264:         if @connection.respond_to?(:status)
265:           @connection.status == PGconn::CONNECTION_OK
266:         else
267:           # We're asking the driver, not ActiveRecord, so use @connection.query instead of #query
268:           @connection.query 'SELECT 1'
269:           true
270:         end
271:       # postgres-pr raises a NoMethodError when querying if no connection is available.
272:       rescue PGError, NoMethodError
273:         false
274:       end
adapter_name()

Returns ‘PostgreSQL’ as adapter name for identification purposes.

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 250
250:       def adapter_name
251:         'PostgreSQL'
252:       end
add_column(table_name, column_name, type, options = {})

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

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 735
735:       def add_column(table_name, column_name, type, options = {})
736:         default = options[:default]
737:         notnull = options[:null] == false
738: 
739:         # Add the column.
740:         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])}")
741: 
742:         change_column_default(table_name, column_name, default) if options_include_default?(options)
743:         change_column_null(table_name, column_name, false, default) if notnull
744:       end
begin_db_transaction()

Begins a transaction.

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

Changes the column of a table.

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 747
747:       def change_column(table_name, column_name, type, options = {})
748:         quoted_table_name = quote_table_name(table_name)
749: 
750:         begin
751:           execute "ALTER TABLE #{quoted_table_name} ALTER COLUMN #{quote_column_name(column_name)} TYPE #{type_to_sql(type, options[:limit], options[:precision], options[:scale])}"
752:         rescue ActiveRecord::StatementInvalid => e
753:           raise e if postgresql_version > 80000
754:           # This is PostgreSQL 7.x, so we have to use a more arcane way of doing it.
755:           begin
756:             begin_db_transaction
757:             tmp_column_name = "#{column_name}_ar_tmp"
758:             add_column(table_name, tmp_column_name, type, options)
759:             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])})"
760:             remove_column(table_name, column_name)
761:             rename_column(table_name, tmp_column_name, column_name)
762:             commit_db_transaction
763:           rescue
764:             rollback_db_transaction
765:           end
766:         end
767: 
768:         change_column_default(table_name, column_name, options[:default]) if options_include_default?(options)
769:         change_column_null(table_name, column_name, options[:null], options[:default]) if options.key?(:null)
770:       end
change_column_default(table_name, column_name, default)

Changes the default value of a table column.

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 773
773:       def change_column_default(table_name, column_name, default)
774:         execute "ALTER TABLE #{quote_table_name(table_name)} ALTER COLUMN #{quote_column_name(column_name)} SET DEFAULT #{quote(default)}"
775:       end
change_column_null(table_name, column_name, null, default = nil)
     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 777
777:       def change_column_null(table_name, column_name, null, default = nil)
778:         unless null || default.nil?
779:           execute("UPDATE #{quote_table_name(table_name)} SET #{quote_column_name(column_name)}=#{quote(default)} WHERE #{quote_column_name(column_name)} IS NULL")
780:         end
781:         execute("ALTER TABLE #{quote_table_name(table_name)} ALTER #{quote_column_name(column_name)} #{null ? 'DROP' : 'SET'} NOT NULL")
782:       end
client_min_messages()

Returns the current client message level.

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 641
641:       def client_min_messages
642:         query('SHOW client_min_messages')[0][0]
643:       end
client_min_messages=(level)

Set the client message level.

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

Returns the list of all column definitions for a table.

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

Commits a transaction.

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 504
504:       def commit_db_transaction
505:         execute "COMMIT"
506:       end
create_database(name, options = {})

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

Example:

  create_database config[:database], config
  create_database 'foo_development', :encoding => 'unicode'
     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 527
527:       def create_database(name, options = {})
528:         options = options.reverse_merge(:encoding => "utf8")
529: 
530:         option_string = options.symbolize_keys.sum do |key, value|
531:           case key
532:           when :owner
533:             " OWNER = \"#{value}\""
534:           when :template
535:             " TEMPLATE = \"#{value}\""
536:           when :encoding
537:             " ENCODING = '#{value}'"
538:           when :tablespace
539:             " TABLESPACE = \"#{value}\""
540:           when :connection_limit
541:             " CONNECTION LIMIT = #{value}"
542:           else
543:             ""
544:           end
545:         end
546: 
547:         execute "CREATE DATABASE #{quote_table_name(name)}#{option_string}"
548:       end
disconnect!()

Close the connection.

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 288
288:       def disconnect!
289:         @connection.close rescue nil
290:       end
execute(sql, name = nil)

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

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 483
483:       def execute(sql, name = nil)
484:         log(sql, name) do
485:           if @async
486:             @connection.async_exec(sql)
487:           else
488:             @connection.exec(sql)
489:           end
490:         end
491:       end
indexes(table_name, name = nil)

Returns the list of all indexes for a table.

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 579
579:       def indexes(table_name, name = nil)
580:          schemas = schema_search_path.split(/,/).map { |p| quote(p) }.join(',')
581:          result = query("SELECT distinct i.relname, d.indisunique, a.attname\nFROM pg_class t, pg_class i, pg_index d, pg_attribute a\nWHERE i.relkind = 'i'\nAND d.indexrelid = i.oid\nAND d.indisprimary = 'f'\nAND t.oid = d.indrelid\nAND t.relname = '\#{table_name}'\nAND i.relnamespace IN (SELECT oid FROM pg_namespace WHERE nspname IN (\#{schemas}) )\nAND a.attrelid = t.oid\nAND ( d.indkey[0]=a.attnum OR d.indkey[1]=a.attnum\nOR d.indkey[2]=a.attnum OR d.indkey[3]=a.attnum\nOR d.indkey[4]=a.attnum OR d.indkey[5]=a.attnum\nOR d.indkey[6]=a.attnum OR d.indkey[7]=a.attnum\nOR d.indkey[8]=a.attnum OR d.indkey[9]=a.attnum )\nORDER BY i.relname\n", name)
582: 
583:         current_index = nil
584:         indexes = []
585: 
586:         result.each do |row|
587:           if current_index != row[0]
588:             indexes << IndexDefinition.new(table_name, row[0], row[1] == "t", [])
589:             current_index = row[0]
590:           end
591: 
592:           indexes.last.columns << row[2]
593:         end
594: 
595:         indexes
596:       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 vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 425
425:       def insert(sql, name = nil, pk = nil, id_value = nil, sequence_name = nil)
426:         # Extract the table from the insert sql. Yuck.
427:         table = sql.split(" ", 4)[2].gsub('"', '')
428: 
429:         # Try an insert with 'returning id' if available (PG >= 8.2)
430:         if supports_insert_with_returning?
431:           pk, sequence_name = *pk_and_sequence_for(table) unless pk
432:           if pk
433:             id = select_value("#{sql} RETURNING #{quote_column_name(pk)}")
434:             clear_query_cache
435:             return id
436:           end
437:         end
438: 
439:         # Otherwise, insert then grab last_insert_id.
440:         if insert_id = super
441:           insert_id
442:         else
443:           # If neither pk nor sequence name is given, look them up.
444:           unless pk || sequence_name
445:             pk, sequence_name = *pk_and_sequence_for(table)
446:           end
447: 
448:           # If a pk is given, fallback to default sequence name.
449:           # Don't fetch last insert id for a table without a pk.
450:           if pk && sequence_name ||= default_sequence_name(table, pk)
451:             last_insert_id(table, sequence_name)
452:           end
453:         end
454:       end
reconnect!()

Close then reopen the connection.

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 277
277:       def reconnect!
278:         if @connection.respond_to?(:reset)
279:           @connection.reset
280:           configure_connection
281:         else
282:           disconnect!
283:           connect
284:         end
285:       end
remove_index(table_name, options = {})

Drops an index from a table.

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 790
790:       def remove_index(table_name, options = {})
791:         execute "DROP INDEX #{index_name(table_name, options)}"
792:       end
rename_column(table_name, column_name, new_column_name)

Renames a column in a table.

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

Renames a table.

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

Aborts a transaction.

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 509
509:       def rollback_db_transaction
510:         execute "ROLLBACK"
511:       end
schema_search_path()

Returns the active schema search path.

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 636
636:       def schema_search_path
637:         @schema_search_path ||= query('SHOW search_path')[0][0]
638:       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 vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 628
628:       def schema_search_path=(schema_csv)
629:         if schema_csv
630:           execute "SET search_path TO #{schema_csv}"
631:           @schema_search_path = schema_csv
632:         end
633:       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 vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 420
420:       def select_rows(sql, name = nil)
421:         select_raw(sql, name).last
422:       end
supports_insert_with_returning?()
     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 330
330:       def supports_insert_with_returning?
331:         postgresql_version >= 80200
332:       end
supports_migrations?()

Does PostgreSQL support migrations?

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 310
310:       def supports_migrations?
311:         true
312:       end
supports_standard_conforming_strings?()

Does PostgreSQL support standard conforming strings?

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 315
315:       def supports_standard_conforming_strings?
316:         # Temporarily set the client message level above error to prevent unintentional
317:         # error messages in the logs when working on a PostgreSQL database server that
318:         # does not support standard conforming strings.
319:         client_min_messages_old = client_min_messages
320:         self.client_min_messages = 'panic'
321: 
322:         # postgres-pr does not raise an exception when client_min_messages is set higher
323:         # than error and "SHOW standard_conforming_strings" fails, but returns an empty
324:         # PGresult instead.
325:         has_support = query('SHOW standard_conforming_strings')[0][0] rescue false
326:         self.client_min_messages = client_min_messages_old
327:         has_support
328:       end
table_alias_length()

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

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

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

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 568
568:       def tables(name = nil)
569:         schemas = schema_search_path.split(/,/).map { |p| quote(p) }.join(',')
570:         query("SELECT tablename\nFROM pg_tables\nWHERE schemaname IN (\#{schemas})\n", name).map { |row| row[0] }
571:       end
type_to_sql(type, limit = nil, precision = nil, scale = nil)

Maps logical Rails types to PostgreSQL-specific data types.

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 795
795:       def type_to_sql(type, limit = nil, precision = nil, scale = nil)
796:         return super unless type.to_s == 'integer'
797: 
798:         case limit
799:           when 1..2;      'smallint'
800:           when 3..4, nil; 'integer'
801:           when 5..8;      'bigint'
802:           else raise(ActiveRecordError, "No integer type has byte size #{limit}. Use a numeric with precision 0 instead.")
803:         end
804:       end
update_sql(sql, name = nil)

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

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 494
494:       def update_sql(sql, name = nil)
495:         super.cmd_tuples
496:       end
Protected Instance methods
postgresql_version()

Returns the version of the connected PostgreSQL version.

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 843
843:         def postgresql_version
844:           @postgresql_version ||=
845:             if @connection.respond_to?(:server_version)
846:               @connection.server_version
847:             else
848:               # Mimic PGconn.server_version behavior
849:               begin
850:                 query('SELECT version()')[0][0] =~ /PostgreSQL (\d+)\.(\d+)\.(\d+)/
851:                 ($1.to_i * 10000) + ($2.to_i * 100) + $3.to_i
852:               rescue
853:                 0
854:               end
855:             end
856:         end