AdminNeonApiService

NeonApiService

Typed wrapper around the Neon REST API v2 for admin reporting, monitoring, and branch management.

NeonApiService

Typed wrapper around the Neon REST API v2 for admin reporting, monitoring, and branch management.

Architecture

Configuration

The service is created via a factory function that validates configuration with Zod:

import { createNeonApiService } from '@/services/neonApiService.ts';

const neon = createNeonApiService({
  apiKey: env.NEON_API_KEY,       // Required — Neon API key
  baseUrl: 'https://...',         // Optional — defaults to https://console.neon.tech/api/v2
});
ParameterTypeRequiredDefaultDescription
apiKeystring✅—Neon API key
baseUrlstring❌https://console.neon.tech/api/v2Neon REST API base URL

An optional IBasicLogger can be passed as the second argument to enable request logging:

const neon = createNeonApiService({ apiKey }, consoleLogger);

API Reference

getProject(projectId: string): Promise<NeonProject>

Fetch details of a single Neon project.

const project = await neon.getProject('steep-rice-35228530');
// → { id, name, region_id, created_at, updated_at, pg_version? }

listBranches(projectId: string): Promise<NeonBranch[]>

List all branches for a project.

const branches = await neon.listBranches('steep-rice-35228530');

getBranch(projectId: string, branchId: string): Promise<NeonBranch>

Get details of a specific branch.

const branch = await neon.getBranch('steep-rice-35228530', 'br-cool-night-abc123');
// → { id, name, project_id, parent_id, current_state, created_at, updated_at }

createBranch(projectId: string, opts?: CreateBranchOptions): Promise<{ branch, operations }>

Create a new branch. Optionally specify a name and parent branch.

const result = await neon.createBranch('steep-rice-35228530', {
  name: 'feature/admin-dashboard',
  parent_id: 'br-cool-night-abc123',
});
console.log(result.branch.id);           // new branch ID
console.log(result.operations[0].status); // 'finished' | 'running'

deleteBranch(projectId: string, branchId: string): Promise<{ branch, operations }>

Delete a branch. Returns the deleted branch metadata and any triggered operations.

const result = await neon.deleteBranch('steep-rice-35228530', 'br-old-branch');

listEndpoints(projectId: string): Promise<NeonEndpoint[]>

List compute endpoints for a project.

const endpoints = await neon.listEndpoints('steep-rice-35228530');
// → [{ id, host, branch_id, type: 'read_write' | 'read_only', current_state, ... }]

listDatabases(projectId: string, branchId: string): Promise<NeonDatabase[]>

List databases within a specific branch.

const dbs = await neon.listDatabases('steep-rice-35228530', 'br-cool-night-abc123');
// → [{ id, name: 'neondb', branch_id, owner_name, ... }]

getConnectionUri(projectId: string, branchId: string, opts?): Promise<string>

Retrieve a connection URI for a branch. Useful for generating one-off connection strings.

const uri = await neon.getConnectionUri('steep-rice-35228530', 'br-cool-night-abc123', {
  database_name: 'neondb',
  role_name: 'neondb_owner',
});
// → 'postgres://neondb_owner:***@ep-xxx.c-13.us-east-1.aws.neon.tech/neondb'

querySQL<T>(connectionString: string, sql: string, params?): Promise<T[]>

Execute a SQL query via the @neondatabase/serverless driver. Accepts a full postgres:// connection string.

const rows = await neon.querySQL<{ count: number }>(
  'postgres://user:pass@host/db',
  'SELECT COUNT(*) as count FROM users WHERE created_at > $1',
  ['2025-01-01'],
);
console.log(rows[0].count);

Error Handling

All REST API errors throw a NeonApiError with:

PropertyTypeDescription
messagestringHuman-readable description
statusnumberHTTP status code (e.g. 404, 403, 500)
bodyunknownParsed JSON body from Neon (if available)
import { NeonApiError } from '@/services/neonApiService.ts';

try {
  await neon.getProject('nonexistent');
} catch (err) {
  if (err instanceof NeonApiError) {
    console.error(`Neon API error ${err.status}:`, err.body);
  }
}

Zod Schemas

All API responses are validated at runtime using Zod schemas:

SchemaValidates
NeonApiServiceConfigSchemaService config
NeonProjectSchemaProject objects
NeonBranchSchemaBranch objects
NeonEndpointSchemaEndpoint objects
NeonDatabaseSchemaDatabase objects
NeonOperationSchemaOperation objects
NeonConnectionUriSchemaConnection URI

Sequence: Admin Branch Management

Was this page helpful?