Examples

This section provides hands-on examples demonstrating NpgsqlRest features. Each example builds on the previous one, progressively introducing more advanced concepts.

All examples are available in the examples repository on GitHub.

Prerequisites

Before running the examples, ensure you have:

• PostgreSQL running locally (port 5432)
• Bun runtime installed (bun.sh)
• A database named example_db with default credentials (postgres/postgres)

Getting Started

1. Clone the repository:

git clone https://github.com/NpgsqlRest/npgsqlrest-docs.git
cd npgsqlrest-docs/examples

2. Install dependencies (downloads the NpgsqlRest binary and sets up required tools):

bun install

3. Navigate to any example directory and run it:

cd 1_my_first_function

# Apply database migrations
bun run db:up

# Start the server (also rebuilds TypeScript and HTTP files)
bun run dev

4. Visit http://127.0.0.1:8080 to see the result.

Available Examples

Example	Description	Related Blog Post
1_my_first_function	The basics: creating a PostgreSQL function and exposing it as an HTTP endpoint with automatic TypeScript client generation	End-to-End Type Checking
2_static_type_checking	How NpgsqlRest's autogenerated client code provides static type safety, catching breaking changes at build time	End-to-End Type Checking
3_security_and_auth	Database-level security with cookie-based authentication and the principle of least privilege	Database-Level Security
4_passwords_tokens_roles	Password verification, JWT/Bearer tokens, role-based access control (RBAC), and external OAuth providers	Multiple Auth Schemes & RBAC
5_csv_basic_auth	CSV exports with HTTP Basic Auth, Excel integration, and type composition for BI use cases	PostgreSQL BI Server
6_image_uploads	Secure image uploads with file system storage, PostgreSQL Large Objects, and progress tracking	Secure Image Uploads
7_csv_excel_uploads	CSV and Excel file ingestion with row-by-row processing and automatic TypeScript clients	CSV & Excel Ingestion
8_simple_chat_client	Real-time chat application using Server-Sent Events (SSE) and PostgreSQL RAISE statements	Real-Time Chat with SSE
9_http_calls	External API calls from PostgreSQL using HTTP custom types defined in type comments	External API Calls
10_proxy_ai_service	Reverse proxy with transform mode for caching AI responses and external service integration	Reverse Proxy & AI Service
11_crud_auto_api	Auto-generate REST CRUD endpoints from PostgreSQL tables with whitelist patterns	Zero to CRUD API

Available Commands

Each example provides these scripts:

Command	Description
bun run dev	Start NpgsqlRest server (rebuilds TypeScript and HTTP files)
bun run build	Compile TypeScript to JavaScript
bun run watch	Watch mode for TypeScript changes
bun run db:up	Apply database migrations
bun run db:list	List pending migrations

Next Steps

After completing these examples, explore:

• Configuration Reference - All available configuration options
• Annotations Reference - SQL comment annotations for endpoint customization
• Code Generation - Client code generation options