Connect a Bun application to Neon

This guide describes how to create a project on Neon 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 project on Neon

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

   1. Navigate to the Projects page in the 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.sqlNeon 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 in the Console nav to open the Connect to your branch 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&channel_binding=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.sqlNeon 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",
   }

References

• Bun SQL client
• @neondatabase/serverless driver