0
# Client Configuration
1

2
Core client setup and configuration for connecting to PostgREST endpoints with custom headers, schema switching, and fetch customization.
3

4
## Capabilities
5

6
### PostgrestClient Constructor
7

8
Creates a new PostgREST client instance for connecting to a PostgREST endpoint.
9

10
```typescript { .api }
11
/**
12
 * Creates a PostgREST client
13
 * @param url - URL of the PostgREST endpoint
14
 * @param options - Named parameters
15
 * @param options.headers - Custom headers
16
 * @param options.schema - Postgres schema to switch to
17
 * @param options.fetch - Custom fetch implementation
18
 */
19
class PostgrestClient<
20
  Database = any,
21
  ClientOptions extends ClientServerOptions = {},
22
  SchemaName extends string = 'public',
23
  Schema extends GenericSchema = any
24
> {
25
  constructor(
26
    url: string,
27
    options?: {
28
      headers?: HeadersInit;
29
      schema?: SchemaName;
30
      fetch?: Fetch;
31
    }
32
  );
33
  
34
  // Properties
35
  url: string;
36
  headers: Headers;
37
  schemaName?: SchemaName;
38
  fetch?: Fetch;
39
}
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import { PostgrestClient } from "@supabase/postgrest-js";
46

47
// Basic client
48
const client = new PostgrestClient("https://api.example.com");
49

50
// Client with custom headers
51
const clientWithAuth = new PostgrestClient("https://api.example.com", {
52
  headers: {
53
    'Authorization': 'Bearer your-token',
54
    'X-Custom-Header': 'value'
55
  }
56
});
57

58
// Client with specific schema
59
const publicClient = new PostgrestClient("https://api.example.com", {
60
  schema: "public"
61
});
62

63
// Client with custom fetch (Node.js with specific options)
64
const nodeClient = new PostgrestClient("https://api.example.com", {
65
  fetch: (url, options) => fetch(url, {
66
    ...options,
67
    timeout: 30000,
68
    agent: myCustomAgent
69
  })
70
});
71
```
72

73
### Schema Switching
74

75
Switch to a different PostgreSQL schema for subsequent queries.
76

77
```typescript { .api }
78
/**
79
 * Select a schema to query or perform an function (rpc) call.
80
 * The schema needs to be on the list of exposed schemas inside Supabase.
81
 * @param schema - The schema to query
82
 */
83
schema<DynamicSchema extends string & keyof Database>(
84
  schema: DynamicSchema
85
): PostgrestClient<Database, ClientOptions, DynamicSchema, Database[DynamicSchema]>;
86
```
87

88
**Usage Examples:**
89

90
```typescript
91
const client = new PostgrestClient("https://api.example.com");
92

93
// Switch to private schema
94
const privateClient = client.schema("private");
95

96
// Query from private schema
97
const { data } = await privateClient
98
  .from("private_table")
99
  .select("*");
100

101
// Switch back to public schema
102
const publicClient = client.schema("public");
103
```
104

105
### Table and View Queries
106

107
Access tables and views to begin query operations.
108

109
```typescript { .api }
110
/**
111
 * Perform a query on a table or a view
112
 * @param relation - The table or view name to query
113
 */
114
from<TableName extends string & keyof Schema['Tables']>(
115
  relation: TableName
116
): PostgrestQueryBuilder<ClientOptions, Schema, Schema['Tables'][TableName], TableName>;
117

118
from<ViewName extends string & keyof Schema['Views']>(
119
  relation: ViewName
120
): PostgrestQueryBuilder<ClientOptions, Schema, Schema['Views'][ViewName], ViewName>;
121

122
from(relation: string): PostgrestQueryBuilder<ClientOptions, Schema, any, any>;
123
```
124

125
**Usage Examples:**
126

127
```typescript
128
const client = new PostgrestClient("https://api.example.com");
129

130
// Query a table
131
const usersQuery = client.from("users");
132

133
// Query a view
134
const activeUsersQuery = client.from("active_users_view");
135

136
// Chain immediately
137
const { data } = await client
138
  .from("products")
139
  .select("name, price")
140
  .eq("category", "electronics");
141
```
142

143
### Custom Headers
144

145
Set or modify HTTP headers for requests.
146

147
```typescript { .api }
148
/**
149
 * Set an HTTP header for the request
150
 * @param name - Header name
151
 * @param value - Header value
152
 */
153
setHeader(name: string, value: string): this;
154
```
155

156
Note: Headers can be set at the client level during construction or on individual query builders.
157

158
**Usage Examples:**
159

160
```typescript
161
// Set headers during client construction
162
const client = new PostgrestClient("https://api.example.com", {
163
  headers: {
164
    'Authorization': 'Bearer token',
165
    'X-API-Key': 'your-api-key'
166
  }
167
});
168

169
// Set headers on individual queries
170
const { data } = await client
171
  .from("users")
172
  .select("*")
173
  .setHeader("X-Request-ID", "unique-request-id");
174
```
175

176
### Custom Fetch Implementation
177

178
Provide a custom fetch implementation for specific environments or requirements.
179

180
```typescript { .api }
181
type Fetch = typeof fetch;
182
```
183

184
**Usage Examples:**
185

186
```typescript
187
import fetch from 'node-fetch';
188
import { PostgrestClient } from "@supabase/postgrest-js";
189

190
// Node.js with node-fetch
191
const client = new PostgrestClient("https://api.example.com", {
192
  fetch: fetch as any
193
});
194

195
// Custom fetch with timeout
196
const customFetch = (url: string, options: RequestInit) => {
197
  return fetch(url, {
198
    ...options,
199
    timeout: 10000 // 10 second timeout
200
  });
201
};
202

203
const clientWithTimeout = new PostgrestClient("https://api.example.com", {
204
  fetch: customFetch
205
});
206

207
// Fetch with custom user agent
208
const clientWithUA = new PostgrestClient("https://api.example.com", {
209
  fetch: (url, options) => fetch(url, {
210
    ...options,
211
    headers: {
212
      ...options?.headers,
213
      'User-Agent': 'MyApp/1.0.0'
214
    }
215
  })
216
});
217
```
218

219
### Environment Detection
220

221
The client automatically detects the environment and uses appropriate fetch implementation:
222

223
- **Browser**: Uses native `fetch`
224
- **Node.js**: Uses `@supabase/node-fetch` when native `fetch` is not available
225
- **Custom**: Uses provided fetch implementation
226

227
### Schema Type Safety
228

229
When using TypeScript with database type definitions, the client provides full type safety:
230

231
```typescript
232
// With typed database schema
233
interface Database {
234
  public: {
235
    Tables: {
236
      users: {
237
        Row: { id: number; name: string; email: string };
238
        Insert: { name: string; email: string };
239
        Update: { name?: string; email?: string };
240
      };
241
    };
242
    Views: {
243
      active_users: {
244
        Row: { id: number; name: string; last_active: string };
245
      };
246
    };
247
    Functions: {
248
      get_user_stats: {
249
        Args: { user_id: number };
250
        Returns: { total_posts: number; total_likes: number };
251
      };
252
    };
253
  };
254
}
255

256
const typedClient = new PostgrestClient<Database>("https://api.example.com");
257

258
// Full type safety for table queries
259
const users = await typedClient
260
  .from("users") // ✅ Type-safe table name
261
  .select("id, name, email") // ✅ Type-safe column names
262
  .eq("id", 123); // ✅ Type-safe filtering
263

264
// Type inference for results
265
// users.data will be of type: { id: number; name: string; email: string }[] | null
266
```