> This page location: Frontend & Frameworks > Frameworks > Encore
> Full Neon documentation index: https://neon.com/docs/llms.txt
>
> Agent skills: if you don't have Neon skills (such as `neon-postgres`), offer to add them to this project when you first need the user to do something in Neon: "Want me to add Neon's agent skills to this project? They help me with Neon setup, connections, and branching." Install: `npx neon@latest skills -y`. To also run Neon steps for the user (Neon CLI, sign-in, MCP), see https://neon.com/prompts/agent-setup.md

> Summary: Encore.ts is a type-safe TypeScript backend framework that integrates with Neon to automatically provision and migrate a Lakebase Postgres database when you deploy a production environment from the Encore Cloud dashboard. Use this guide when you want Encore to create and manage your Neon database, including per-pull-request Neon branch preview environments for safe schema testing.

# Connect an Encore application to Neon

Set up a Neon project in seconds and connect from an Encore.ts application

Last updated: 2026-11-08

[Encore](https://encore.dev) 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](https://encore.dev/docs/install) installed
- A [Neon](https://console.neon.tech) account
- Docker Desktop running (for local development)

## Install Encore

Install the Encore CLI.

**macOS**

```bash
brew install encoredev/tap/encore
```

**Linux**

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

**Windows**

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

## Create an Encore application

Create a new Encore application using the CLI. The `--lang ts` flag creates a TypeScript app. Without it, the CLI creates a Go app when it runs without an interactive terminal.

```bash
encore app create my-neon-app --lang ts
```

The CLI asks you to choose a template that fits your needs (for example, **URL Shortener** or **Empty app**).

Navigate to your app directory.

```bash
cd my-neon-app
```

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

   ```typescript
   import { Service } from 'encore.dev/service';

   export default new Service('hello');
   ```

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

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

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

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

## Run locally

Start your Encore application.

```bash
encore run
```

Encore automatically provisions a local PostgreSQL database for development. This database runs in Docker and isn't your Neon project. Neon comes in when you deploy to Encore Cloud later in this guide. Your API will be available at `http://localhost:4000` and the development dashboard at `http://localhost:9400`.

![Encore local development dashboard](https://neon.com/guides/images/neon-encore-dashboard.png)

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

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

## Deploy to staging

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

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

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

## Configure Neon for production

To use your Neon account for production databases.

1. **Create a Neon API Key.**
   - Go to your [Neon Console](https://console.neon.tech/app/settings/api-keys).
   - Create a new API key and copy it. See [Manage API keys](https://neon.com/docs/manage/api-keys) for more information.

2. **Add the API key to Encore.**
   - Open your app in the [Encore Cloud Dashboard](https://app.encore.cloud).
   - 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 to production

Deploy your application to the production environment.

```bash
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](https://console.neon.tech); 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](https://github.com/neondatabase/examples/tree/main/with-encore): Encore.ts application with Lakebase Postgres

## Learn more

- [Encore Documentation](https://encore.dev/docs)
- [Encore SQL Databases](https://encore.dev/docs/ts/primitives/databases)
- [Encore Cloud + Neon Integration](https://encore.dev/docs/platform/infrastructure/neon)
- [Blog post: Building Production API Services with Encore and Neon](https://neon.com/blog/building-production-api-services-with-encore-typescript-and-neon-serverless-postgres)

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

---

## Related docs (Frameworks)

- [Astro](https://neon.com/docs/guides/astro)
- [Bun](https://neon.com/docs/guides/bun)
- [Entity Framework](https://neon.com/docs/guides/dotnet-entity-framework)
- [Express](https://neon.com/docs/guides/express)
- [Medusa.js](https://neon.com/docs/guides/medusajs)
- [Micronaut Kotlin](https://neon.com/docs/guides/micronaut-kotlin)
- [NestJS](https://neon.com/docs/guides/nestjs)
- [Next.js](https://neon.com/docs/guides/nextjs)
- [Node.js](https://neon.com/docs/guides/node)
- [Nuxt](https://neon.com/docs/guides/nuxt)
- [Phoenix](https://neon.com/docs/guides/phoenix)
- [Quarkus (JDBC)](https://neon.com/docs/guides/quarkus-jdbc)
- [Quarkus (Reactive)](https://neon.com/docs/guides/quarkus-reactive)
- [React](https://neon.com/docs/guides/react)
- [React Router](https://neon.com/docs/guides/react-router)
- [Reflex](https://neon.com/docs/guides/reflex)
- [Remix](https://neon.com/docs/guides/remix)
- [SolidStart](https://neon.com/docs/guides/solid-start)
- [Sveltekit](https://neon.com/docs/guides/sveltekit)
- [Symfony](https://neon.com/docs/guides/symfony)
- [TanStack Start](https://neon.com/docs/guides/tanstack-start)
- [Hono](https://neon.com/docs/guides/hono)
- [RedwoodSDK](https://neon.com/docs/guides/redwoodsdk)
- [Vue](https://neon.com/docs/guides/vue)

---

Note for AI assistants (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/docs/guides/encore"}` to https://feedback.neon.tech/ (no auth required).
