Connect an Encore application to Neon

Encore is a backend development framework that uses static analysis and type-safe primitives to provide automatic infrastructure provisioning, distributed tracing, and API documentation. This guide shows you how to use Neon with Encore for production deployments.

Prerequisites

• Encore CLI installed
• A Neon account
• Docker Desktop running (for local development)

1. Install Encore

   Install the Encore CLI.

   macOS

   Linux

   Windows

   brew install encoredev/tap/encore

2. Create an Encore application

   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 (e.g., URL Shortener or Empty app).

   Navigate to your app directory.

   cd my-neon-app

3. Define your database schema

   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 };
        }
      );

4. Run locally

   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!"}'

5. Deploy to staging

   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.

6. Configure Neon for production

   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.

7. Deploy to production

   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.

Source code

You can find a complete Encore + Neon example application on GitHub:

• Get started with Encore and Neon

  Encore.ts application with Neon Postgres

Learn more

• Encore Documentation
• Encore SQL Databases
• Encore Cloud + Neon Integration
• Blog post: Building Production API Services with Encore and Neon