Adapter module for PostgreSQL.

It uses Postgrex for communicating to the database.

Features

• Full query support (including joins, preloads and associations)
• Support for transactions
• Support for data migrations
• Support for ecto.create and ecto.drop operations
• Support for transactional tests via Ecto.Adapters.SQL

Options

Postgres options split in different categories described below. All options can be given via the repository configuration:

config :your_app, YourApp.Repo,
  ...

Connection options

• :hostname - Server hostname
• :socket_dir - Connect to Postgres via UNIX sockets in the given directory The socket name is derived based on the port. This is the preferred method for configuring sockets and it takes precedence over the hostname. If you are connecting to a socket outside of the Postgres convention, use :socket instead;
• :socket - Connect to Postgres via UNIX sockets in the given path. This option takes precedence over the :hostname and :socket_dir
• :username - Username
• :password - User password
• :port - Server port (default: 5432)
• :database - the database to connect to
• :maintenance_database - Specifies the name of the database to connect to when creating or dropping the database. Defaults to "postgres"
• :pool - The connection pool module, may be set to Ecto.Adapters.SQL.Sandbox
• :ssl - Set to true if ssl should be used (default: false)
• :ssl_opts - A list of ssl options, see Erlang's ssl docs
• :parameters - Keyword list of connection parameters
• :connect_timeout - The timeout for establishing new connections (default: 5000)
• :prepare - How to prepare queries, either :named to use named queries or :unnamed to force unnamed queries (default: :named)
• :socket_options - Specifies socket configuration
• :show_sensitive_data_on_connection_error - show connection data and configuration whenever there is an error attempting to connect to the database

The :socket_options are particularly useful when configuring the size of both send and receive buffers. For example, when Ecto starts with a pool of 20 connections, the memory usage may quickly grow from 20MB to 50MB based on the operating system default values for TCP buffers. It is advised to stick with the operating system defaults but they can be tweaked if desired:

socket_options: [recbuf: 8192, sndbuf: 8192]

We also recommend developers to consult the Postgrex.start_link/1 documentation for a complete listing of all supported options.

Storage options

• :encoding - the database encoding (default: "UTF8") or :unspecified to remove encoding parameter (alternative engine compatibility)
• :template - the template to create the database from
• :lc_collate - the collation order
• :lc_ctype - the character classification
• :dump_path - where to place dumped structures
• :force_drop - force the database to be dropped even if it has connections to it (requires PostgreSQL 13+)

After connect callback

If you want to execute a callback as soon as connection is established to the database, you can use the :after_connect configuration. For example, in your repository configuration you can add:

after_connect: {Postgrex, :query!, ["SET search_path TO global_prefix", []]}

You can also specify your own module that will receive the Postgrex connection as argument.

Extensions

Both PostgreSQL and its adapter for Elixir, Postgrex, support an extension system. If you want to use custom extensions for Postgrex alongside Ecto, you must define a type module with your extensions. Create a new file anywhere in your application with the following:

Postgrex.Types.define(MyApp.PostgresTypes,
                      [MyExtension.Foo, MyExtensionBar] ++ Ecto.Adapters.Postgres.extensions())

Once your type module is defined, you can configure the repository to use it:

config :my_app, MyApp.Repo, types: MyApp.PostgresTypes