Neon Integration Guide

Overview

Neon is a serverless PostgreSQL database with automatic scaling and free branching. It provides PostgreSQL compatibility with modern, consumption-based pricing.

Integration Type: PostgreSQL-compatible (serverless)
Authentication: Connection string with credentials OR username/password
Protocol: PostgreSQL wire protocol (over HTTPS)
Database Type: PostgreSQL (100% compatible)

Getting Started

Prerequisites:

A Neon account (free or paid)
A Neon project and database created
Access to your Neon console

Steps to Create a Neon Project:

Go to https://neon.tech
Click "Sign Up" and create an account (or sign in)
Click "Create a project"
Give your project a name
Select your region (choose closest to your location)
Select PostgreSQL version (default is fine)
Click "Create project" - your database will initialize in ~30 seconds

Obtaining Credentials

Connection String (Recommended)

Location: Neon Console > Your Project > "Connect" button
Format: postgresql://user:password@host/dbname?sslmode=require

Project ID

Found in project URL or settings. Format: unique project identifier

Branch ID

Usually "main" for the default branch

Steps to Get Connection String:
1. Go to Neon Console
2. Click on your project
3. Click "Connect" (top right)
4. Select "Connection string" tab
5. Copy the complete connection string

Configuration in Dashboard

Click "Add Project"
Select "Neon" as Database Provider
Fill in Credentials:
- Connection String: Paste your Neon connection string
- API Key: (Optional) Your Neon API key
- Project ID: (Optional) Your Neon project ID
Click "Test Connection" to verify
Click "Save Project"

Tellus Integration

Integrating Neon with Tellus allows you to leverage serverless PostgreSQL effortlessly. In your tellus.config.js or within your initialized client instance, define the connection:

import { Tellus } from '@tellus/client';

const tellus = new Tellus({
  databases: {
    inventory: {
      provider: 'neon',
      connectionString: process.env.NEON_DATABASE_URL
    }
  }
});

Connection Pooling: Neon is serverless, so connection handling is slightly different. Tellus automatically optimizes connections to Neon's pooling architecture.

Basic Operations (CRUD)

With Tellus, querying your serverless PostgreSQL database uses the standard Tellus unified API. Note how it abstracts away direct SQL execution.

1. Create (Insert)

// Insert a new product into the 'products' table
const newProduct = await tellus.db('inventory').collection('products').insert({
  name: 'Wireless Keyboard',
  price: 49.99,
  stock: 150
});

2. Read (Select)

// Fetch in-stock products, sorted by price
const availableProducts = await tellus.db('inventory').collection('products')
  .find({ stock: { $gt: 0 } })
  .orderBy('price', 'asc')
  .limit(20)
  .execute();

3. Update

// Update stock after a purchase
await tellus.db('inventory').collection('products')
  .where('id', '==', 101)
  .update({ stock: 149 });

4. Delete

// Remove discontinued products
await tellus.db('inventory').collection('products')
  .where('stock', '==', 0)
  .delete();

Using Neon in the Dashboard

Browse Database Schema - View all tables, columns, and data types
Query and Explore Data - Execute SQL queries and view results
Manage Data - Add, edit, and delete records
Create and Modify Tables - Build your database schema
Monitor Database - Check storage usage and performance

Example Setup: E-commerce Database

CREATE TABLE categories (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100) NOT NULL,
  description TEXT
);

CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  description TEXT,
  category_id INTEGER REFERENCES categories(id),
  price DECIMAL(10, 2) NOT NULL,
  stock INTEGER DEFAULT 0
);

CREATE TABLE orders (
  id SERIAL PRIMARY KEY,
  customer_email VARCHAR(255) NOT NULL,
  total_amount DECIMAL(10, 2) NOT NULL,
  status VARCHAR(20) DEFAULT 'pending'
);

Then add indexes for performance:

CREATE INDEX idx_products_category ON products(category_id);
CREATE INDEX idx_orders_customer ON orders(customer_email);

Neon-Specific Features

Branching: Create database branches for development and testing
Auto-scaling: Compute units scale automatically with usage
Read Replicas: Create read-only replicas for scaling reads
Point-in-time Recovery: Restore data from any point in time

Security Best Practices

Store connection strings securely, not in plain text
Use environment variables in production
Enable SSL/TLS connections (default in Neon)
Create separate database users for different applications
Regular backups and test recovery procedures