Beta
The Neon Data API is in Beta. Share your feedback on Discord or via the Neon Console.
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.tsOptions
| Flag | Alias | Description | Default |
|---|---|---|---|
--db-url | -c | The PostgreSQL connection string (Required). | - |
--output | -o | The path where the file will be saved. | ./types/database.ts |
--schemas | -s | Comma-separated list of schemas to introspect. | public |
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>({
auth: { url: process.env.NEON_AUTH_URL },
dataApi: { url: process.env.NEON_DATA_API_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 booleanResponse 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 Neon 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,
});