Generate TypeScript types from your database schema

The Neon SDK offers a CLI tool that introspects your database schema to generate a TypeScript definition file. This promotes type safety and enhances the developer experience when interacting with your database via the Data API, particularly with PostgREST clients like @neondatabase/postgrest-js and @neondatabase/neon-js. Key benefits include:

• Autocomplete for table names and columns.
• Type inference for query results.
• Compile-time error checking for invalid queries.

Generate types

Use npx to run the type generator. You must provide your Direct Connection String (Postgres URL) so the tool can connect to and inspect your database.

npx @neondatabase/neon-js gen-types \
  --db-url "postgresql://user:pass@ep-id.region.neon.tech/neondb" \
  --output src/types/database.ts

Options

Use generated types

Once generated, import the Database interface and pass it as a generic argument to createClient.

// Import the generated type
import type { Database } from '@/types/database';
import { createClient } from '@neondatabase/neon-js';

// Pass the generic to the client
const client = createClient<Database>(process.env.NEON_DATABASE_URL!);

// 3. Enjoy full type safety
const { data, error } = await client
  .from('posts') // Autocomplete: only 'posts' or existing tables
  .select('id, content') // Autocomplete: only columns in 'posts'
  .eq('is_published', true); // Type check: ensures 'is_published' expects a boolean

Use the HTTPS Neon database URL without credentials or query parameters for NEON_DATABASE_URL, for example https://ep-example.c-2.us-east-1.aws.neon.tech/neondb. You can find the matching Data API URL on the Data API page in the Neon Console or with neon data-api get; to get the single database URL, remove the .apirest hostname label and trailing /rest/v1 path. If you start from a Neon Auth URL instead, remove the .neonauth hostname label and trailing /auth path. The cell label (if present), region, and database path stay the same. Prefer the older two-URL setup? See the object-form alternative in the JavaScript SDK reference.

Response types

The client automatically infers the return type based on your query.

// 'data' is automatically typed as: { id: number; content: string }[] | null
const { data } = await client.from('posts').select('id, content');

// 'data' is automatically typed as: { id: number; content: string } | null
const { data } = await client.from('posts').select('id, content').single();

Helper types

The generated file also exports utility types for working with your tables outside of queries:

import type { Tables, TablesInsert, TablesUpdate } from '@/types/database';

// Tables<> gives you the row type (what you get back from queries)
type Note = Tables<'notes'>;

// TablesInsert<> gives you the insert type (for creating new rows)
type NewNote = TablesInsert<'notes'>;

// TablesUpdate<> gives you the update type (for partial updates)
type NoteUpdate = TablesUpdate<'notes'>;

These are useful when you need to type function parameters, state variables, or props separately from your queries.

Automate with package.json

To keep your types in sync with your database schema, we recommend adding a script to your package.json.

{
  "scripts": {
    "generate-types": "npx @neondatabase/neon-js gen-types --db-url \"$DATABASE_URL\" --output src/types/database.ts"
  }
}

You can now run npm run generate-types whenever you make schema changes (like adding a new table or column).

Using with the Neon PostgREST Client

If you are using @neondatabase/postgrest-js (without Managed Better Auth), the types work exactly the same way:

import type { Database } from '@/types/database';
import { NeonPostgrestClient } from '@neondatabase/postgrest-js';

const client = new NeonPostgrestClient<Database>({
  dataApiUrl: process.env.NEON_DATA_API_URL,
});