Connect an Encore application to Neon

Install the Encore CLI.

brew install encoredev/tap/encore

curl -L https://encore.dev/install.sh | bash

iwr https://encore.dev/install.ps1 | iex

Create a new Encore application using the CLI.

encore app create my-neon-app

Select TypeScript as the language and choose the template that fits your needs (for example, URL Shortener or Empty app).

Navigate to your app directory.

cd my-neon-app

If you started with an empty app, set up your database.

1. Create a service directory and service definition (hello/encore.service.ts).

   import { Service } from 'encore.dev/service';
   
   export default new Service('hello');

2. Create a database configuration file (hello/db.ts).

   import { SQLDatabase } from 'encore.dev/storage/sqldb';
   
   export const db = new SQLDatabase('hello', {
     migrations: './migrations',
   });

3. Create a migration file (hello/migrations/1_create_table.up.sql).

   CREATE TABLE messages (
     id BIGSERIAL PRIMARY KEY,
     text TEXT NOT NULL,
     created_at TIMESTAMP NOT NULL DEFAULT NOW()
   );

4. Create API endpoints (hello/hello.ts).

   import { api } from 'encore.dev/api';
   import { db } from './db';
   
   interface Message {
     id: number;
     text: string;
     created_at: Date;
   }
   
   export const create = api(
     { expose: true, method: 'POST', path: '/messages' },
     async (req: { text: string }): Promise<Message> => {
       const row = await db.queryRow<Message>`
         INSERT INTO messages (text)
         VALUES (${req.text})
         RETURNING id, text, created_at
       `;
       if (!row) throw new Error('Failed to create message');
       return row;
     }
   );
   
   export const list = api(
     { expose: true, method: 'GET', path: '/messages' },
     async (): Promise<{ messages: Message[] }> => {
       const rows = await db.query<Message>`
         SELECT id, text, created_at FROM messages
         ORDER BY created_at DESC
       `;
       const messages: Message[] = [];
       for await (const row of rows) {
         messages.push(row);
       }
       return { messages };
     }
   );

Start your Encore application.

encore run

Encore automatically provisions a local PostgreSQL database for development. Your API will be available at http://localhost:4000 and the development dashboard at http://localhost:9400.

Test your endpoints using the API Explorer in the dashboard, or by running this command.

curl -X POST http://localhost:4000/messages \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from Encore!"}'

Push your code to deploy to Encore's staging environment.

git add -A
git commit -m "Initial commit"
git push encore

This creates a staging environment with an Encore-managed database.

To use your Neon account for production databases.

1. Create a Neon API Key.
   • Go to your Neon Console.
   • Create a new API key and copy it. See Manage API keys for more information.
2. Add the API key to Encore.
   • Open your app in the Encore Cloud Dashboard.
   • Navigate to Settings → Integrations → Neon.
   • Paste your Neon API key and click Save.
3. Create a production environment.
   • In the Encore dashboard, click Create Environment.
   • Name it production.
   • For the database provider, select Neon.
   • Choose your preferred region.
   • Click Create.

Deploy your application to the production environment.

git push encore

Encore will do the following.

• Create a Neon database in your account
• Run your migrations automatically
• Deploy your application
• Configure all connections

You can verify the database was created by checking your Neon Console; you'll see a new database created by Encore with your migrations applied.

Preview Environments with Neon Branching

When you connect your Encore app to GitHub and enable preview environments, Encore automatically creates a new Neon database branch for each pull request. This gives each PR its own isolated database with a copy of your production data, allowing you to test database migrations and schema changes safely before merging to production.