Connect from Phoenix to Neon

This guide describes how to connect Neon in a Phoenix application. Ecto provides an API and abstractions for interacting databases, enabling Elixir developers to query any database using similar constructs.

It is assumed that you have a working installation of Elixir.

1. Create a Neon project

   If you do not have one already, create a Neon project. Save your connection details including your password. They are required when defining connection settings.

   1. Navigate to the Projects page in the Neon Console.
   2. Click New Project.
   3. Specify your project settings and click Create Project.

2. Store your Neon credentials

   Add a .env file to your project directory and add your Neon connection string to it. You can find your connection string by clicking the Connect button on your Project Dashboard to open the Connect to your database modal. For more information, see Connect from any application.

   DATABASE_URL="postgresql://<user>:<password>@<endpoint_hostname>.neon.tech:<port>/<dbname>?sslmode=require&channel_binding=require"

   You will need the connection string details later in the setup.

3. Create a Phoenix project

   Create a Phoenix project if you do not have one:

   # install phx.new if you haven't already
   # mix archive.install hex phx_new
   mix phx.new hello

   When prompted, choose to not install the dependencies yet.

4. Configure database connections

   Update the following configuration files with your Neon database connection details from the connection string you copied earlier.

   1. Update config/dev.exs:

      config :hello, Hello.Repo,
         username: "neondb_owner",
         password: "JngqXejzvb93",
         hostname: "ep-rough-snowflake-a5j76tr5.us-east-2.aws.neon.tech",
         database: "neondb",
         stacktrace: true,
         show_sensitive_data_on_connection_error: true,
         pool_size: 10,
         ssl: [cacerts: :public_key.cacerts_get()]

      note

      The :ssl option is required to connect to Neon. Postgrex, since v0.18, verifies the server SSL certificate and you need to select CA trust store using :cacerts or :cacertfile options. You can use the OS-provided CA store by setting cacerts: :public_key.cacerts_get(). While not recommended, you can disable certificate verification by setting ssl: [verify: :verify_none].

   2. Update config/runtime.exs:

      config :hello, Hello.Repo,
         ssl: [cacerts: :public_key.cacerts_get()],
         url: database_url,
         pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10"),
         socket_options: maybe_ipv6

   3. Update config/test.exs:

      config :hello, Hello.Repo,
         username: "neondb_owner",
         password: "JngqXejzvb93",
         hostname: "ep-rough-snowflake-a5j76tr5.us-east-2.aws.neon.tech",
         database: "with_phoenix_test#{System.get_env("MIX_TEST_PARTITION")}",
         pool: Ecto.Adapters.SQL.Sandbox,
         pool_size: System.schedulers_online() * 2,
         ssl: [cacerts: :public_key.cacerts_get()]

      tip

      This guide configures the test environment for completeness but doesn't cover running tests. For production workflows, consider using Neon branches instead of a separate test database. Branches provide isolated, cost-effective copies of your database that are ideal for testing and CI/CD pipelines.

5. Install dependencies and create databases

   1. Install the dependencies:

      mix deps.get

   2. Create the development and test databases:

      mix ecto.create
      MIX_ENV=test mix ecto.create

      The first command creates the development database (neondb). The second creates the test database (with_phoenix_test).

6. Build and run the Phoenix application

   To compile the app in production mode, run the following command:

   MIX_ENV=prod mix compile

   To compile assets for the production mode, run the following command:

   MIX_ENV=prod mix assets.deploy

   For each deployment, a secret key is required for encrypting and signing data. Run the following command to generate the key:

   mix phx.gen.secret

   When you run the following command, you can expect to see the Phoenix application at http://localhost:4001:

   PORT=4001 \
   MIX_ENV=prod \
   PHX_HOST=localhost \
   DATABASE_URL="postgresql://...:...@...aws.neon.tech/neondb?sslmode=require&channel_binding=require" \
   SECRET_KEY_BASE=".../..." \
   mix phx.server

Source code

You can find the source code for the application described in this guide on GitHub.

• Get started with Phoenix and Neon

  Get started with Phoenix and Neon