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 username. -
: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 aSET client_encoding TO <encoding>
call on the connection. -
:min_messages
- An optional client min messages that is used in aSET client_min_messages TO <min_messages>
call on the connection. -
:variables
- An optional hash of additional parameters that will be used inSET SESSION key = val
calls on the connection. -
:insert_returning
- An optional boolean to control the use ofRETURNING
forINSERT
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 .
- A
- C
- D
- E
- I
- M
- N
- R
- S
-
- session_auth=,
- set_standard_conforming_strings,
- supports_advisory_locks?,
- supports_bulk_alter?,
- supports_check_constraints?,
- supports_comments?,
- supports_common_table_expressions?,
- supports_datetime_with_precision?,
- supports_ddl_transactions?,
- supports_deferrable_constraints?,
- supports_exclusion_constraints?,
- supports_explain?,
- supports_expression_index?,
- supports_extensions?,
- supports_foreign_keys?,
- supports_foreign_tables?,
- supports_index_include?,
- supports_index_sort_order?,
- supports_insert_conflict_target?,
- supports_insert_on_conflict?,
- supports_insert_on_duplicate_skip?,
- supports_insert_on_duplicate_update?,
- supports_insert_returning?,
- supports_json?,
- supports_lazy_transactions?,
- supports_materialized_views?,
- supports_optimizer_hints?,
- supports_partial_index?,
- supports_partitioned_indexes?,
- supports_pgcrypto_uuid?,
- supports_restart_db_transaction?,
- supports_savepoints?,
- supports_transaction_isolation?,
- supports_unique_keys?,
- supports_validate_constraints?,
- supports_views?,
- supports_virtual_columns?
- T
- U
- ActiveRecord::ConnectionAdapters::PostgreSQL::Quoting
- ActiveRecord::ConnectionAdapters::PostgreSQL::SchemaStatements
- ActiveRecord::ConnectionAdapters::PostgreSQL::DatabaseStatements
Constants
ADAPTER_NAME | = | "PostgreSQL" |
DEADLOCK_DETECTED | = | "40P01" |
DUPLICATE_DATABASE | = | "42P04" |
FOREIGN_KEY_VIOLATION | = | "23503" |
LOCK_NOT_AVAILABLE | = | "55P03" |
NATIVE_DATABASE_TYPES | = | { primary_key: "bigserial primary key", string: { name: "character varying" }, text: { name: "text" }, integer: { name: "integer", limit: 4 }, bigint: { name: "bigint" }, float: { name: "float" }, decimal: { name: "decimal" }, datetime: {}, # set dynamically based on datetime_type timestamp: { name: "timestamp" }, timestamptz: { name: "timestamptz" }, 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" }, enum: {} # special type https://www.postgresql.org/docs/current/datatype-enum.html } |
NOT_NULL_VIOLATION | = | "23502" |
NUMERIC_VALUE_OUT_OF_RANGE | = | "22003" |
QUERY_CANCELED | = | "57014" |
SERIALIZATION_FAILURE | = | "40001" |
UNIQUE_VIOLATION | = | "23505" |
VALUE_LIMIT_VIOLATION | = | "22001" |
See www.postgresql.org/docs/current/static/errcodes-appendix.html |
Class Public methods
create_unlogged_tables Link
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
datetime_type Link
PostgreSQL supports multiple types for DateTimes. By default, if you use datetime
in migrations, Rails
will translate this to a PostgreSQL “timestamp without time zone”. Change this in an initializer to use another NATIVE_DATABASE_TYPES
. For example, to store DateTimes as “timestamp with time zone”:
ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.datetime_type = :timestamptz
Or if you are adding a custom type:
ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::NATIVE_DATABASE_TYPES[:my_custom_type] = { name: "my_custom_type_name" }
ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.datetime_type = :my_custom_type
If you’re using :ruby
as your config.active_record.schema_format
and you change this setting, you should immediately run bin/rails db:migrate
to update the types in your schema.rb.
dbconsole(config, options = {}) Link
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 82 def dbconsole(config, options = {}) pg_config = config.configuration_hash ENV["PGUSER"] = pg_config[:username] if pg_config[:username] ENV["PGHOST"] = pg_config[:host] if pg_config[:host] ENV["PGPORT"] = pg_config[:port].to_s if pg_config[:port] ENV["PGPASSWORD"] = pg_config[:password].to_s if pg_config[:password] && options[:include_password] ENV["PGSSLMODE"] = pg_config[:sslmode].to_s if pg_config[:sslmode] ENV["PGSSLCERT"] = pg_config[:sslcert].to_s if pg_config[:sslcert] ENV["PGSSLKEY"] = pg_config[:sslkey].to_s if pg_config[:sslkey] ENV["PGSSLROOTCERT"] = pg_config[:sslrootcert].to_s if pg_config[:sslrootcert] if pg_config[:variables] ENV["PGOPTIONS"] = pg_config[:variables].filter_map do |name, value| "-c #{name}=#{value.to_s.gsub(/[ \\]/, '\\\\\0')}" unless value == ":default" || value == :default end.join(" ") end find_cmd_and_exec("psql", config.database) end
new(...) Link
Initializes and connects a PostgreSQL adapter.
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 307 def initialize(...) super conn_params = @config.compact # Map ActiveRecords param names to PGs. conn_params[:user] = conn_params.delete(:username) if conn_params[:username] conn_params[:dbname] = conn_params.delete(:database) if conn_params[:database] # Forward only valid config params to PG::Connection.connect. valid_conn_param_keys = PG::Connection.conndefaults_hash.keys + [:requiressl] conn_params.slice!(*valid_conn_param_keys) @connection_parameters = conn_params @max_identifier_length = nil @type_map = nil @raw_connection = nil @notice_receiver_sql_warnings = [] @use_insert_returning = @config.key?(:insert_returning) ? self.class.type_cast_config_to_boolean(@config[:insert_returning]) : true end
new_client(conn_params) Link
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 66 def new_client(conn_params) PG.connect(**conn_params) rescue ::PG::Error => error if conn_params && conn_params[:dbname] == "postgres" raise ActiveRecord::ConnectionNotEstablished, error.message elsif conn_params && conn_params[:dbname] && error.message.include?(conn_params[:dbname]) raise ActiveRecord::NoDatabaseError.db_error(conn_params[:dbname]) elsif conn_params && conn_params[:user] && error.message.include?(conn_params[:user]) raise ActiveRecord::DatabaseConnectionError.username_error(conn_params[:user]) elsif conn_params && conn_params[:host] && error.message.include?(conn_params[:host]) raise ActiveRecord::DatabaseConnectionError.hostname_error(conn_params[:host]) else raise ActiveRecord::ConnectionNotEstablished, error.message end end
Instance Public methods
active?() Link
Is this connection alive and ready for queries?
create_enum(name, values, **options) Link
Given a name and an array of values, creates an enum type.
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 509 def create_enum(name, values, **options) sql_values = values.map { |s| quote(s) }.join(", ") scope = quoted_scope(name) query = <<~SQL DO $$ BEGIN IF NOT EXISTS ( SELECT 1 FROM pg_type t JOIN pg_namespace n ON t.typnamespace = n.oid WHERE t.typname = #{scope[:name]} AND n.nspname = #{scope[:schema]} ) THEN CREATE TYPE #{quote_table_name(name)} AS ENUM (#{sql_values}); END IF; END $$; SQL exec_query(query) end
disable_extension(name, force: false) Link
Removes an extension from the database.
:force
-
Set to
:cascade
to drop dependent objects as well. Defaults to false.
disconnect!() Link
Disconnects from the database if already connected. Otherwise, this method does nothing.
drop_enum(name, values = nil, **options) Link
Drops an enum type.
If the if_exists: true
option is provided, the enum is dropped only if it exists. Otherwise, if the enum doesn’t exist, an error is raised.
The values
parameter will be ignored if present. It can be helpful to provide this in a migration’s change
method so it can be reverted. In that case, values
will be used by create_enum
.
enable_extension(name, **) Link
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 455 def enable_extension(name, **) schema, name = name.to_s.split(".").values_at(-2, -1) sql = +"CREATE EXTENSION IF NOT EXISTS \"#{name}\"" sql << " SCHEMA #{schema}" if schema exec_query(sql).tap { reload_type_map } end
enum_types() Link
Returns a list of defined enum types, and their values.
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 487 def enum_types query = <<~SQL SELECT type.typname AS name, type.OID AS oid, n.nspname AS schema, string_agg(enum.enumlabel, ',' ORDER BY enum.enumsortorder) AS value FROM pg_enum AS enum JOIN pg_type AS type ON (type.oid = enum.enumtypid) JOIN pg_namespace n ON type.typnamespace = n.oid GROUP BY type.OID, n.nspname, type.typname; SQL exec_query(query, "SCHEMA", allow_retry: true, uses_transaction: false).cast_values.each_with_object({}) do |row, memo| name, schema = row[0], row[2] schema = nil if schema == current_schema full_name = [schema, name].compact.join(".") memo[full_name] = row.last end.to_a end
extension_available?(name) Link
extension_enabled?(name) Link
extensions() Link
index_algorithms() Link
max_identifier_length() Link
Returns the configured supported identifier length supported by PostgreSQL
reset!() Link
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 353 def reset! @lock.synchronize do return connect! unless @raw_connection unless @raw_connection.transaction_status == ::PG::PQTRANS_IDLE @raw_connection.query "ROLLBACK" end @raw_connection.query "DISCARD ALL" super end end
session_auth=(user) Link
Set the authorized user for this session
set_standard_conforming_strings() Link
supports_advisory_locks?() Link
supports_bulk_alter?() Link
supports_check_constraints?() Link
supports_comments?() Link
supports_common_table_expressions?() Link
supports_datetime_with_precision?() Link
supports_ddl_transactions?() Link
supports_deferrable_constraints?() Link
supports_exclusion_constraints?() Link
supports_explain?() Link
supports_expression_index?() Link
supports_extensions?() Link
supports_foreign_keys?() Link
supports_foreign_tables?() Link
supports_index_include?() Link
supports_index_sort_order?() Link
supports_insert_on_conflict?() Link
supports_insert_returning?() Link
supports_json?() Link
supports_lazy_transactions?() Link
supports_materialized_views?() Link
supports_optimizer_hints?() Link
supports_partial_index?() Link
supports_partitioned_indexes?() Link
supports_pgcrypto_uuid?() Link
supports_restart_db_transaction?() Link
supports_savepoints?() Link
supports_transaction_isolation?() Link
supports_unique_keys?() Link
supports_validate_constraints?() Link
supports_views?() Link
supports_virtual_columns?() Link
table_name_length() Link
Returns the maximum length of a table name.
# File activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb, line 552 def table_name_length # PostgreSQL automatically creates an index for PRIMARY KEY with name consisting of # truncated table name and "_pkey" suffix fitting into max_identifier_length number of characters. # We allow smaller table names to be able to correctly rename this index when renaming the table. max_identifier_length - "_pkey".length end