Connect from Phoenix to Neon

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.

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 in the Console nav to open the Connect to your branch 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.

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.

Update the following configuration files with your 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 the database. 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.

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).

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