Connect a Bun application to Neon

This guide describes how to create a Neon project and connect to it from a Bun application. Examples are provided for using Bun's built-in SQL client and the @neondatabase/serverless driver. Use the client you prefer.

1. Create a Neon project

   If you do not have one already, create a Neon project.

   1. Navigate to the Projects page in the Neon Console.
   2. Click New Project.
   3. Specify your project settings and click Create Project.

2. Create a Bun project and add dependencies

   Create a Bun project and change to the newly created directory:

   mkdir bun-neon-example
   cd bun-neon-example
   bun init -y

   Next, add project dependencies if you intend to use the Neon serverless driver. Otherwise, Bun's built-in sql client is readily available.

   Bun.sql

   Neon serverless driver

   # No dependencies needed for Bun's built-in SQL client

3. Store your Neon credentials

   Add a .env.local file to your project directory and add your Neon connection details to it. Bun automatically loads variables from .env, .env.local, and other .env.* files. You can find the connection details for your database by clicking the Connect button on your Project Dashboard to open the Connect to your database modal. Select Bun from the Connection string dropdown. For more information, see Connect from any application.

   POSTGRES_URL='postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require'

   note

   Bun.sql uses POSTGRES_URL as the default environment variable for the Primary connection URL for Postgres

   important

   To ensure the security of your data, never expose your Neon credentials directly in your code or commit them to version control.

4. Configure the Postgres client

   Add an index.ts file (or index.js) to your project directory and add the following code snippet to connect to your Neon database. Choose the configuration that matches your preferred client.

   Bun.sql

   Neon serverless driver

   import { sql } from 'bun';
   
   async function getPgVersion() {
     const result = await sql`SELECT version()`;
     console.log(result[0]);
   }
   
   getPgVersion();

5. Run index.ts

   Run bun run index.ts (or bun index.js) to view the result.

   $ bun run index.ts
   {
     version: "PostgreSQL 17.2 on x86_64-pc-linux-gnu, compiled by gcc (Debian 12.2.0-14) 12.2.0, 64-bit",
   }

Source code

You can find the source code for the application described in this guide on GitHub.

• Get started with Bun and Neon

  Get started with Bun and Neon

References

• Bun SQL client
• @neondatabase/serverless driver