Connect from Elixir with Ecto to Neon
Set up a Neon project in seconds and connect from Elixir with Ecto
This guide describes how to connect from an Elixir application with Ecto, which is a database wrapper and query generator for Elixir. Ecto provides an API and abstractions for interacting databases, enabling Elixir developers to query any database using similar constructs.
The instructions in this guide follow the steps outlined in the Ecto Getting Started guide, modified to demonstrate connecting to a Neon Serverless Postgres database. It is assumed that you have a working installation of Elixir.
To connect to Neon from Elixir with Ecto:
- Create a database in Neon and copy the connection string
- Create an Elixir project
- Add Ecto and Postgrex to the application
- Configure Ecto
- Create a migration and add a table
- Next steps
Create a database in Neon and copy the connection string
The instructions in this configuration use a database named
To create the database:
- Navigate to the Neon Console.
- Select a project.
- Select Databases.
- Select the branch where you want to create the database.
- Click New Database.
- Enter a database name (
friends), and select a database owner.
- Click Create.
You can obtain the connection string for the database from the Connection Details widget on the Neon Dashboard. Select a branch, a role, and the database you want to connect to. A connection string is constructed for you. Your connection string should look something like this:
You will need the connection string details later in the setup.
Create an Elixir project
Create an Elixir application called
--sup option ensures that the application has a supervision tree, which is required by Ecto.
Add Ecto and Postgrex to the application
Add the Ecto and the Postgrex driver dependencies to the
mix.exsfile by updating the
depsdefinition in the file to include those items. For example:
Ecto provides the common querying API. The Postgrex driver acts as a bridge between Ecto and Postgres. Ecto interfaces with its own
Ecto.Adapters.Postgresmodule, which communicates to Postgres through the Postgrex driver.
Install the Ecto and the Postgrex driver dependencies by running the following command in your application directory:
Run the following command in your application directory to generate the configuration required to connect from Ecto to your Neon database.
Follow these steps to complete the configuration:
The first part of the configuration generated by the
mix ecto.gen.repocommand is found in the
config/config.exsfile. Update this configuration with your Neon database connection details. Use the connection details from the Neon connection string you copied in the first part of the guide. Your
hostnamewill differ from the example below.
ssl_optssettings are required to connect to Neon. Neon uses domain names provided via the Server Name Indication (SNI) extension of the TLS protocol to route incoming connections. Enabling
server_name_indicationoption set to your Neon hostname ensures that this information is passed to Neon when making a connection. The
verify: :verify_nonesetting tells Ecto to ignore SSL certificate verification when connecting to your database, but keep in mind that it is better to use SSL with proper certificate verification. That
ssl_optsconfiguration is as follows:
The second part of the configuration generated by the
mix ecto.gen.repocommand is the
Ecto.Repomodule, found in
lib/friends/repo.ex. You shouldn't have to make any changes here, but verify that the following configuration is present:
Ecto uses the module definition to query the database. The
otp_appsetting tells Ecto where to find the database configuration. In this case, the
:friendsapplication is specified, so Ecto will use the configuration defined in the that application's
:adapteroption defines the Postgres adapter.
Friends.Repomust be defined as a supervisor within the application's supervision tree. In
lib/friends/application.ex, make sure
Friends.Repois specified in the
startfunction, as shown:
This configuration starts the Ecto process, enabling it to receive and execute the application's queries.
The final part of the configuration is to add the following line under the configuration in the
config/config.exsfile that you updated in the first step:
This line tells the application about the new repo, allowing you to run commands such as
mix ecto.migrate, which you will use in a later step to create a table in your database.
Create a migration and add a table
friends database is currently empty. It has no tables or data. In this step, you will add a table. To do so, you will create a "migration" by running the following command in your application directory:
The command generates an empty migration file in
priv/repo/migrations, which looks like this:
Add code to the migration file to create a table called
people. For example:
To run the migration and create the
people table in your database, which also verifies your connection to Neon, run the following command from your application directory:
The output of this command should appear similar to the following:
You can use the Tables feature in the Neon Console to view the table that was created:
- Navigate to the Neon Console.
- Select a project.
- Select Tables from the sidebar.
- Select the Branch, Database (
friends), and the schema (
public). You should see the
peopletable along with a
schema_migrationtable that was created by the migration.
You can find the application code for the example above on GitHub.
The Ecto Getting Started Guide provides additional steps that you can follow to create a schema, insert data, and run queries. See Creating the schema in the Ecto Getting Started Guide to pick up where the steps in this guide leave off.
- Suppose you have
PGHOSTenvironment variable on your system set to something other than your Neon hostname. In that case, this hostname will be used instead of the Neon
hostnamedefined in your Ecto Repo configuration when running
mix ectocommands. To avoid this issue, you can either set the
PGHOSTenvironment variable to your Neon hostname or specify
mix ectocommands; for example:
PGHOST="" mix ecto.migrate.
- By default, Neon's Auto-suspend feature scales computes to zero after 300 seconds (5 minutes) of inactivity, which can result in a
connection not availableerror when running
mix ectocommands. Typically, a Neon compute takes a few seconds to transition from
Active. Wait a few seconds and try running the command again. Alternatively, consider the strategies outlined in Connection latency and timeouts to manage connection issues resulting from compute suspension.
Last updated on