Postgres Meta

https://github.com/supabase/postgres-meta
Admin
A RESTful API for managing Postgres, allowing fetching of tables, adding roles, running queries, and...
Tokens:89,182
Snippets:576
Trust Score:10
License:Apache-2.0
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Create extension example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-extensions.md

Example usage of the create method to install the pgcrypto extension in the public schema. Logs any error message to the console.

```ts
const { data, error } = await pgMeta.extensions.create({
  name: 'pgcrypto',
  schema: 'public',
})
if (error) console.error(error.message)
```

--------------------------------

### retrieve example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-tables.md

Example usage of `pgMeta.tables.retrieve` with `name` and `schema`. Checks if the error message starts with 'Cannot find' to handle a 404-equivalent case.

```typescript
const { data, error } = await pgMeta.tables.retrieve({ name: 'users', schema: 'public' })
if (error?.message.startsWith('Cannot find')) {
  // 404-equivalent: table does not exist
}
```

--------------------------------

### create example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-schemas.md

Example of creating a schema named 'analytics' and logging any error.

```typescript
const { data, error } = await pgMeta.schemas.create({ name: 'analytics' })
if (error) console.error(error.message)
```

--------------------------------

### List Database Types Example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-types.md

Example showing how to initialize PostgresMeta and list types while excluding system schemas.

```ts
import PostgresMeta from '@supabase/postgres-meta'

const pgMeta = new PostgresMeta({
  connectionString: 'postgresql://postgres:postgres@localhost:5432/postgres',
})
const { data, error } = await pgMeta.types.list({ includeSystemSchemas: false })
if (error) {
  console.error(error.message)
} else {
  data.filter((t) => t.enums.length > 0).forEach((t) => console.log(t.schema, t.name, t.enums))
}
await pgMeta.end()
```

--------------------------------

### create example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-tables.md

Example usage of `pgMeta.tables.create` with a table name and comment, logging the created table's schema and name on success.

```typescript
const { data, error } = await pgMeta.tables.create({ name: 'orders', comment: 'customer orders' })
if (error) console.error(error.message)
else console.log(`created ${data.schema}.${data.name}`)
```

--------------------------------

### Create a Postgres role example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-roles.md

Example usage of the create method to add a new role with specific permissions and configuration.

```ts
const { data, error } = await pgMeta.roles.create({
  name: 'analyst',
  can_login: true,
  password: 's3cret',
  config: { search_path: 'public, extensions' },
})
```

--------------------------------

### Start Development Server

Source: https://github.com/supabase/postgres-meta/blob/master/CLAUDE.md

Start the development server. The dev server uses nodemon with ts-node/esm loader and pipes output through pino-pretty for readable logs.

```bash
npm run dev              # Start dev server with Docker DB (auto-cleans on exit)
npm run dev:code         # Start dev server without DB setup (if DB already running)
```

--------------------------------

### List Composite Types Example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-types.md

Example showing how to opt-in to see composite (table-record) types for a specific schema.

```ts
// Composite (table-record) types are hidden by default; opt in to see them
const { data, error } = await pgMeta.types.list({
  includeTableTypes: true,
  includedSchemas: ['public'],
})
if (!error) data.forEach((t) => console.log(t.name, t.format, t.attributes))
```

--------------------------------

### create function example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-functions.md

A basic example showing how to create a function named add_one using the pgMeta.functions.create method.

```ts
const { data, error } = await pgMeta.functions.create({
  name: 'add_one',
  args: ['x int4'],
  definition: 'select x + 1',
  return_type: 'int4',
})
if (error) console.error(error.message)
```

--------------------------------

### create method example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-publications.md

Example usage of `pgMeta.publications.create` to create a publication named 'orders_pub' with insert and update publishing on the 'public.orders' table.

```typescript
const { data, error } = await pgMeta.publications.create({
  name: 'orders_pub',
  publish_insert: true,
  publish_update: true,
  tables: ['public.orders'],
})
```

--------------------------------

### Update role example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-roles.md

An example of calling the update method to enable login for a role and modify its configuration settings.

```ts
const { data, error } = await pgMeta.roles.update(42, {
  can_login: true,
  config: [
    { op: 'replace', path: 'search_path', value: 'public' },
    { op: 'remove', path: 'work_mem' },
  ],
})
if (error) console.error(error.message)
```

--------------------------------

### Example: capacity check with retrieve()

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-version.md

Example of using `retrieve()` to check connection capacity before a heavy job. Throws an error if fewer than 5 connections are free.

```ts
// Capacity check before running a heavy introspection job
const { data: version } = await pgMeta.version.retrieve()
const free = version.max_connections - version.active_connections
if (free < 5) {
  throw new Error(`only ${free} connections free, aborting`)
}
```

--------------------------------

### Example: list views

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-views.md

Example usage of the list method to retrieve views from the 'public' schema and log their names, updatability, and column counts.

```ts
const { data, error } = await pgMeta.views.list({ includedSchemas: ['public'] })
if (!error) data.forEach((v) => console.log(v.name, v.is_updatable, v.columns?.length))
```

--------------------------------

### grant example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-table-privileges.md

Example of granting SELECT privilege with grant option to a reporter on a table, logging any error.

```typescript
const { data, error } = await pgMeta.tablePrivileges.grant([
  { relation_id: 16384, grantee: 'reporter', privilege_type: 'SELECT', is_grantable: true },
])
if (error) console.error(error.message)
```

--------------------------------

### Example: retrieve view

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-views.md

Example usage of the retrieve method to fetch a view by name and schema, checking for a 'Cannot find a view' error.

```ts
const { data, error } = await pgMeta.views.retrieve({ name: 'active_users', schema: 'public' })
if (error?.message.startsWith('Cannot find a view')) {
  // view does not exist
}
```

--------------------------------

### Retrieve index by ID example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-indexes.md

Example usage of the retrieve method with an index ID. Checks if the error message starts with 'Cannot find an index' to handle the case where the index does not exist.

```ts
const { data, error } = await pgMeta.indexes.retrieve({ id: 16390 })
if (error?.message.startsWith('Cannot find an index')) {
  // index does not exist
}
```

--------------------------------

### Example: retrieve version info

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-version.md

Example usage of `pgMeta.version.retrieve()`. Creates a `PostgresMeta` instance with a connection string, retrieves version info, logs the version and connection counts, and ends the client.

```ts
import PostgresMeta from '@supabase/postgres-meta'

const pgMeta = new PostgresMeta({
  connectionString: 'postgresql://postgres:postgres@localhost:5432/postgres',
})
const { data, error } = await pgMeta.version.retrieve()
if (error) {
  console.error(error.message)
} else {
  console.log(data.version)
  console.log(`connections: ${data.active_connections}/${data.max_connections}`)
}
await pgMeta.end()
```

--------------------------------

### create method example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-columns.md

Example usage of `pgMeta.columns.create` that adds a unique, non-nullable `email` column with a default expression `now()`. Logs the error message if the operation fails.

```ts
const { data, error } = await pgMeta.columns.create({
  table_id: 16384,
  name: 'email',
  type: 'text',
  is_unique: true,
  is_nullable: false,
  default_value: 'now()',
  default_value_format: 'expression',
})
if (error) console.error(error.message)
```

--------------------------------

### list example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-materialized-views.md

Example usage of the list method with includeColumns set to true, logging the name, is_populated, and columns length for each materialized view.

```ts
const { data, error } = await pgMeta.materializedViews.list({ includeColumns: true })
if (!error) data.forEach((mv) => console.log(mv.name, mv.is_populated, mv.columns?.length))
```

--------------------------------

### remove method example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-policies.md

Example usage of the `remove` method. It calls `pgMeta.policies.remove(99)` and checks if the error message starts with 'Cannot find a policy' to handle the case where the policy is already gone.

```ts
const { data, error } = await pgMeta.policies.remove(99)
if (error?.message.startsWith('Cannot find a policy')) {
  // already gone
}
```

--------------------------------

### update example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-schemas.md

Example of updating the owner of schema with id 5 to 'data_team'.

```typescript
const { data, error } = await pgMeta.schemas.update(5, { owner: 'data_team' })
```

--------------------------------

### Remove table example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-tables.md

Example of removing a table with `cascade: true`. The error message starts with 'Cannot find a table' when the table does not exist, allowing you to handle the case where there is nothing to drop.

```ts
const { data, error } = await pgMeta.tables.remove(12345, { cascade: true })
if (error?.message.startsWith('Cannot find a table')) {
  // nothing to drop
}
```

--------------------------------

### Build and start the main Fastify app

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-server.md

Creates the Fastify instance with the provided options and starts listening on port 8080. The build function registers Sentry error handling, Swagger, CORS, and routes.

```ts
import { build } from './src/server/app.js'
const app = build({ logger: false })
await app.listen({ port: 8080, host: '0.0.0.0' })
```

--------------------------------

### retrieve example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-materialized-views.md

Example usage of the retrieve method by name, logging the error message or the is_populated property of the returned materialized view.

```ts
const { data, error } = await pgMeta.materializedViews.retrieve({ name: 'daily_rollup' })
if (error) console.error(error.message)
else console.log(data.is_populated)
```

--------------------------------

### Update extension example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-extensions.md

Example usage of the update method to update the pgcrypto extension to version 3.0.

```ts
const { data, error } = await pgMeta.extensions.update('pgcrypto', {
  update: true,
  version: '3.0',
})
```

--------------------------------

### Example: list tables in public schema

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-tables.md

Example usage of pgMeta.tables.list with includedSchemas: ['public']. Logs schema, name, bytes, and size for each table; returns early on error.

```ts
const { data, error } = await pgMeta.tables.list({ includedSchemas: ['public'] })
if (error) return console.error(error.message)
data.forEach((t) => console.log(t.schema, t.name, t.bytes, t.size))
```

--------------------------------

### List configuration parameters with filtering

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-config.md

Example of using pgMeta.config.list to fetch configuration parameters. It filters for max_connections and work_mem, logs their name, setting, and unit, and handles errors. The connection string is for a local PostgreSQL instance.

```ts
import PostgresMeta from '@supabase/postgres-meta'

const pgMeta = new PostgresMeta({
  connectionString: 'postgresql://postgres:postgres@localhost:5432/postgres',
})
const { data, error } = await pgMeta.config.list({ limit: 100 })
if (error) {
  console.error(error.message)
} else {
  data
    .filter((row) => row.name === 'max_connections' || row.name === 'work_mem')
    .forEach((row) => console.log(row.name, row.setting, row.unit))
}
await pgMeta.end()
```

--------------------------------

### Remove role usage example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-roles.md

An example of how to call the remove method to drop a role with OID 42.

```ts
const { data, error } = await pgMeta.roles.remove(42)
```

--------------------------------

### Example: create policy

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-policies.md

Example usage of the create method to create a policy named 'view_own_orders' on the 'orders' table. Sets roles to ['authenticated'], definition to 'user_id = auth.uid()', and check to 'true'. Logs error message if creation fails.

```typescript
const { data, error } = await pgMeta.policies.create({
  name: 'view_own_orders',
  table: 'orders',
  roles: ['authenticated'],
  definition: 'user_id = auth.uid()',
  check: 'true',
})
if (error) console.error(error.message)
```

--------------------------------

### query method example with timeout and error handling

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta.md

Example of using the query method with a statementQueryTimeout of 5 seconds. On error, it logs the formatted error; on success, it logs the data. The connection is closed with pgMeta.end().

```ts
import PostgresMeta from '@supabase/postgres-meta'

const pgMeta = new PostgresMeta({
  connectionString: 'postgresql://postgres:postgres@localhost:5432/postgres',
})
const { data, error } = await pgMeta.query('select * from public.users limit 10', {
  statementQueryTimeout: 5,
})
if (error) {
  console.error(error.formattedError) // formatted "SEVERITY: CODE: message" block
} else {
  console.log(data)
}
await pgMeta.end()
```

--------------------------------

### retrieve example with error handling

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-functions.md

Example usage of pgMeta.functions.retrieve to look up a function by name, schema, and argument types. The error message 'Cannot find function' indicates the overload does not exist.

```ts
const { data, error } = await pgMeta.functions.retrieve({
  name: 'add_one',
  schema: 'public',
  args: ['int4'],
})
if (error?.message.startsWith('Cannot find function')) {
  // overload does not exist
}
```

--------------------------------

### list example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-columns.md

Example usage of the list method, filtering by tableId and logging each column's ordinal position, name, and data type.

```typescript
const { data, error } = await pgMeta.columns.list({ tableId: 16384 })
if (!error) data.forEach((c) => console.log(c.ordinal_position, c.name, c.data_type))
```

--------------------------------

### Example: create trigger

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-triggers.md

Example call to `pgMeta.triggers.create` that creates a `BEFORE UPDATE` row-level trigger on the `orders` table. It uses the `trigger_set_timestamp` function and logs any error to the console.

```ts
const { data, error } = await pgMeta.triggers.create({
  name: 'set_updated_at',
  table: 'orders',
  function_name: 'trigger_set_timestamp',
  activation: 'BEFORE',
  events: ['UPDATE'],
  orientation: 'ROW',
})
if (error) console.error(error.message)
```

--------------------------------

### List indexes example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-indexes.md

Example usage of the list method. Filters to the public schema with a limit of 50 and logs each index's name, access method, and uniqueness flag if no error occurs.

```ts
const { data, error } = await pgMeta.indexes.list({ includedSchemas: ['public'], limit: 50 })
if (!error) data.forEach((i) => console.log(i.name, i.access_method, i.is_unique))
```

--------------------------------

### Example: update table

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-tables.md

Example usage of `pgMeta.tables.update` to rename a table, enable RLS, and set a comment. The `id` is the existing table OID.

```ts
const { data, error } = await pgMeta.tables.update(12345, {
  name: 'customers',
  rls_enabled: true,
  comment: 'renamed with RLS',
})
```

--------------------------------

### query method example with parameters and Sentry tracking disabled

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta.md

Example of using the query method with bound parameters and trackQueryInSentry set to false to avoid sending sensitive SQL to Sentry.

```ts
const { data, error } = await pgMeta.query(
  'select * from t where id = $1',
  { parameters: [42], trackQueryInSentry: false }
)
```

--------------------------------

### update method example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-publications.md

Example usage of `pgMeta.publications.update` to update publication with OID 50, setting publish_delete to true and specifying a list of tables. Errors are logged to console.

```typescript
const { data, error } = await pgMeta.publications.update(50, {
  publish_delete: true,
  tables: ['public.orders', 'public.order_items'],
})
if (error) console.error(error.message)
```

--------------------------------

### GET /config

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/endpoints.md

Retrieves configuration settings.

```APIDOC
## GET /config

### Description
Retrieves configuration settings.

### Method
GET

### Endpoint
/config

### Parameters
#### Query Parameters
- `limit` (integer) - Optional - Maximum number of rows to return.
- `offset` (integer) - Optional - Number of rows to skip.

### Response
#### Success Response (200)
No response body documented.

```

--------------------------------

### PostgresMeta Constructor and query Method

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta.md

Documentation for the PostgresMeta class constructor and the query method, including parameters, return types, and usage examples.

```APIDOC
## Constructor

```ts
constructor(config: PoolConfig)
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `config` | `PoolConfig` | yes | — | Passed through to `pg.Pool`. See [configuration.md](../configuration.md) for every option |

`init(config)` from `src/lib/db.ts` creates the pool. If `config.connectionString` contains an `sslmode` query parameter it is extracted and mapped to `config.ssl` (`disable` → `ssl: false`; `verify-full` → `rejectUnauthorized: true`; otherwise `ssl: {}`); `sslca`/`sslkey`/`sslcert`/`sslrootcert` params are stripped from the URL.

```ts
// src/lib/PostgresMeta.ts:54-78
constructor(config: PoolConfig) {
  const { query, end } = init(config)
  this.query = query
  this.end = end
  this.columnPrivileges = new PostgresMetaColumnPrivileges(this.query)
  // ...one sub-object per domain, all sharing this.query
}
```

## `query`

```ts
query: (
  sql: string,
  opts?: { statementQueryTimeout?: number; trackQueryInSentry?: boolean; parameters?: unknown[] }
) => Promise<PostgresMetaResult<any>>
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `sql` | `string` | yes | — | SQL to execute |
| `opts.statementQueryTimeout` | `number` | no | `undefined` (no override) | Seconds; prepends `SET statement_timeout='{n}s'; SET idle_session_timeout='{n}s';` to the query (needed because poolers like pgbouncer forbid setting it on the connection) |
| `opts.trackQueryInSentry` | `boolean` | no | `true` | When `false`, the SQL is sent to Sentry as `'custom'` instead of the raw text (used for queries with sensitive info) |
| `opts.parameters` | `unknown[]` | no | `undefined` | Bound parameters passed to `pg.Pool.query` |

Return type: `Promise<PostgresMetaResult<any>>` — `{ data: rows, error: null }` on success (`data` is an array of row objects; if the statement list returns multiple results, the last non-empty result set is returned), or `{ data: null, error }` on failure. Error detail is in [errors.md](../errors.md). For multiple statements returning multiple results, results are collapsed to the final non-empty one (`res.reverse().find((x) => x.rows.length !== 0) ?? { rows: [] }`, `src/lib/db.ts`).

### Examples

```ts
import PostgresMeta from '@supabase/postgres-meta'

const pgMeta = new PostgresMeta({
  connectionString: 'postgresql://postgres:postgres@localhost:5432/postgres',
})
const { data, error } = await pgMeta.query('select * from public.users limit 10', {
  statementQueryTimeout: 5,
})
if (error) {
  console.error(error.formattedError) // formatted "SEVERITY: CODE: message" block
} else {
  console.log(data)
}
await pgMeta.end()
```

```ts
const { data, error } = await pgMeta.query(
  'select * from t where id = $1',
  { parameters: [42], trackQueryInSentry: false }
)
```
```

--------------------------------

### Example: update policy

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-policies.md

Example usage of the update method to change the roles of the policy with OID 99 to ['authenticated', 'service_role']. Logs error message if update fails.

```typescript
const { data, error } = await pgMeta.policies.update(99, { roles: ['authenticated', 'service_role'] })
```

--------------------------------

### getGeneratorMetadata usage example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-server.md

Example usage of getGeneratorMetadata with a PostgresMeta instance and filters. It logs the error message if the operation fails.

```ts
import PostgresMeta from './src/lib/index.js'
import { getGeneratorMetadata } from './src/lib/generators.js'

const pgMeta = new PostgresMeta({ connectionString: 'postgresql://...' })
const { data, error } = await getGeneratorMetadata(pgMeta, { includedSchemas: ['public'] })
if (error) console.error(error.message)
```

--------------------------------

### Run Tests

Source: https://github.com/supabase/postgres-meta/blob/master/CLAUDE.md

Run tests, run tests without DB setup, or update snapshots. Tests require Docker, run sequentially with maxConcurrency: 1, and use pool: 'forks' to avoid memory issues.

```bash
npm test                # Full test: db:clean -> db:run -> test:run -> db:clean
npm run test:run        # Run tests only (DB must be running)
npm run test:update     # Update test snapshots (runs db:clean -> db:run first)
```

--------------------------------

### update method example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-functions.md

Example usage of the `update` method, updating a function's definition. The `data` and `error` are destructured from the result.

```ts
const { data, error } = await pgMeta.functions.update(4242, {
  definition: 'select x + 2',
})
```

--------------------------------

### grant example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-column-privileges.md

Example of granting SELECT privilege on a column to a user. The grantee 'analyst' is identifier-quoted. The response contains the updated privileges for the affected columns.

```typescript
const { data, error } = await pgMeta.columnPrivileges.grant([
  { column_id: '16384.1', grantee: 'analyst', privilege_type: 'SELECT', is_grantable: true },
])
if (error) console.error(error.message)
else data.forEach((c) => console.log(c.column_name, c.privileges))
```

--------------------------------

### Using pgMeta parse, deparse, and format

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta.md

Example usage of pgMeta.parse, pgMeta.deparse, and pgMeta.format. parse returns an AST and error, deparse converts the AST back to SQL, and format returns a pretty-printed SQL string.

```typescript
const { data: ast, error } = pgMeta.parse('select * from t')
const { data: sql } = await pgMeta.deparse(ast)
const { data: pretty } = await pgMeta.format('select * from t')
```

--------------------------------

### Example: listing relationships with includedSchemas

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-relationships.md

Example usage of the list method. Calls list with includedSchemas set to ['public'], then logs the relationships in the format schema.relation → referenced_schema.referenced_relation. If an error occurs, it logs the error message.

```ts
const { data, error } = await pgMeta.relationships.list({ includedSchemas: ['public'] })
if (error) console.error(error.message)
else data.forEach((r) =>
  console.log(`${r.schema}.${r.relation} → ${r.referenced_schema}.${r.referenced_relation}`))
```

--------------------------------

### Example: retrieve column by ID

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-columns.md

Example usage of `pgMeta.columns.retrieve` with an ID. The error message 'Invalid format' indicates a client bug with a bad ID shape.

```typescript
const { data, error } = await pgMeta.columns.retrieve({ id: '16384.1' })
if (error?.message.includes('Invalid format')) {
  // client bug: bad id shape
}
```

--------------------------------

### update method example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-columns.md

Example usage of the update method. Changes the column type to int8 and sets it as not nullable, handling the case where the column does not exist.

```ts
const { data, error } = await pgMeta.columns.update('16384.1', {
  type: 'int8',
  is_nullable: false,
})
if (error?.message.startsWith('Cannot find a column')) {
  // column does not exist
}
```

--------------------------------

### GET /config/version

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/endpoints.md

Retrieves the version of the configuration.

```APIDOC
## GET /config/version

### Description
Retrieves the version of the configuration.

### Method
GET

### Endpoint
/config/version

### Response
#### Success Response (200)
No response body documented.

```

--------------------------------

### remove method usage example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-columns.md

Example call to `pgMeta.columns.remove` with column ID '16384.2' and cascade set to true. Returns the pre-drop column row on success.

```ts
const { data, error } = await pgMeta.columns.remove('16384.2', { cascade: true })
```

--------------------------------

### GET /extensions

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/endpoints.md

Retrieves a list of extensions.

```APIDOC
## GET /extensions

### Description
Retrieves a list of extensions.

### Method
GET

### Endpoint
/extensions

### Parameters
#### Query Parameters
- `limit` (integer) - Optional - Maximum number of rows to return.
- `offset` (integer) - Optional - Number of rows to skip.

### Response
#### Success Response (200)
No response body documented.

```

--------------------------------

### GET /tables

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/endpoints.md

Retrieves tables.

```APIDOC
## GET /tables

### Description
Retrieves tables.

### Method
GET

### Endpoint
/tables

### Parameters
#### Query Parameters
- `include_system_schemas` (boolean) - Optional - Include system schemas.
- `included_schemas` (string) - Optional - Comma-separated list of schemas to include.
- `excluded_schemas` (string) - Optional - Comma-separated list of schemas to exclude.
- `limit` (integer) - Optional - Maximum number of rows to return.
- `offset` (integer) - Optional - Number of rows to skip.
- `include_columns` (boolean) - Optional - Include columns.

### Response
#### Success Response (200)
No response body documented.

```

--------------------------------

### GET /policies

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/endpoints.md

Retrieves policies.

```APIDOC
## GET /policies

### Description
Retrieves policies.

### Method
GET

### Endpoint
/policies

### Parameters
#### Query Parameters
- `include_system_schemas` (boolean) - Optional - Include system schemas.
- `included_schemas` (string) - Optional - Comma-separated list of schemas to include.
- `excluded_schemas` (string) - Optional - Comma-separated list of schemas to exclude.
- `limit` (integer) - Optional - Maximum number of rows to return.
- `offset` (integer) - Optional - Number of rows to skip.

### Response
#### Success Response (200)
No response body documented.

```

--------------------------------

### Manage Test Database

Source: https://github.com/supabase/postgres-meta/blob/master/CLAUDE.md

Start the test database in Docker or stop and remove its containers. The test DB is managed via test/db/docker-compose.yml and runs on port 5432.

```bash
npm run db:run          # Start test DB in Docker (detached, with healthcheck)
npm run db:clean        # Stop and remove test DB containers
```

--------------------------------

### GET /

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/endpoints.md

Root endpoint of the API.

```APIDOC
## GET /

### Description
Returns the root endpoint of the API.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
No response body documented.

```

--------------------------------

### revoke example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-table-privileges.md

Example of revoking SELECT privilege from a reporter on a table.

```typescript
const { data, error } = await pgMeta.tablePrivileges.revoke([
  { relation_id: 16384, grantee: 'reporter', privilege_type: 'SELECT' },
])
```

--------------------------------

### remove example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-schemas.md

Example of removing schema with id 5 with cascade enabled.

```typescript
const { data, error } = await pgMeta.schemas.remove(5, { cascade: true })
```

--------------------------------

### List foreign tables example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-foreign-tables.md

Lists foreign tables in the public schema and logs each foreign table's name and columns. Uses the default includeColumns behavior.

```ts
const { data, error } = await pgMeta.foreignTables.list({ includedSchemas: ['public'] })
if (!error) data.forEach((ft) => console.log(ft.name, ft.columns))
```

--------------------------------

### GET /functions

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/endpoints.md

Retrieves functions.

```APIDOC
## GET /functions

### Description
Retrieves functions.

### Method
GET

### Endpoint
/functions

### Parameters
#### Query Parameters
- `include_system_schemas` (boolean) - Optional - Include system schemas.
- `included_schemas` (string) - Optional - Comma-separated list of schemas to include.
- `excluded_schemas` (string) - Optional - Comma-separated list of schemas to exclude.
- `limit` (integer) - Optional - Maximum number of rows to return.
- `offset` (integer) - Optional - Number of rows to skip.

### Response
#### Success Response (200)
No response body documented.

```

--------------------------------

### Paginate through all GUCs

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-config.md

Example of paginating through all GUCs using the list method with limit and offset. It continues until an error occurs or no more data is returned.

```ts
// Paginate through all GUCs
let offset = 0
const pageSize = 200
while (true) {
  const { data, error } = await pgMeta.config.list({ limit: pageSize, offset })
  if (error) break
  if (data.length === 0) break
  offset += data.length
}
```

--------------------------------

### Remove extension example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-extensions.md

Example usage of the remove method to drop the pgcrypto extension with CASCADE.

```ts
const { data, error } = await pgMeta.extensions.remove('pgcrypto', { cascade: true })
```

--------------------------------

### remove example usage

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-publications.md

Example of calling `pgMeta.publications.remove` with a publication OID of 50. The result is destructured into `data` and `error`.

```typescript
const { data, error } = await pgMeta.publications.remove(50)
```

--------------------------------

### revoke example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-column-privileges.md

Example of revoking SELECT privilege on a column from a user. The revoke never includes WITH GRANT OPTION.

```typescript
const { data, error } = await pgMeta.columnPrivileges.revoke([
  { column_id: '16384.1', grantee: 'analyst', privilege_type: 'SELECT' },
])
if (error?.message) console.error(error.message)
```

--------------------------------

### Configure server and database with required environment variables

Source: https://github.com/supabase/postgres-meta/blob/master/CLAUDE.md

Required environment variables for server operation: host, port, database connection parameters, and SSL mode. The admin server runs on PG_META_PORT + 1. Use PG_META_DB_PASSWORD or CRYPTO_KEY for secrets.

```bash
PG_META_HOST=0.0.0.0                    # Server host
PG_META_PORT=8080                       # Server port (admin runs on +1)
PG_META_DB_HOST=localhost               # PostgreSQL host
PG_META_DB_NAME=postgres                # Database name
PG_META_DB_USER=postgres                # Database user
PG_META_DB_PORT=5432                    # PostgreSQL port
PG_META_DB_PASSWORD=postgres            # Database password (or use CRYPTO_KEY for secrets)
PG_META_DB_SSL_MODE=disable             # SSL mode (disable, require, verify-full, etc.)
```

```bash
PG_META_DB_URL=postgresql://...         # Full connection string (overrides individual params)
```

```bash
PG_CONN_TIMEOUT_SECS=15                 # Connection timeout (default: 15)
PG_QUERY_TIMEOUT_SECS=55                # Query timeout (default: 55)
PG_META_MAX_RESULT_SIZE_MB=20           # Max query result size in MB (default: 2048MB)
PG_META_MAX_BODY_LIMIT_MB=3             # Max request body size in MB (default: 3MB)
PG_META_SHUTDOWN_GRACE_PERIOD_SECS=10   # Shutdown wait on in-flight work before force-exit (default: 10)
```

```bash
PG_META_FORMAT_IN_WORKER=true           # Generate TypeScript types on a worker thread (default: false)
PG_META_FORMAT_POOL_SIZE=1              # Worker threads used for generation (default: 1)
PG_META_FORMAT_MAX_QUEUE=20             # Max generation calls in flight before returning 503 (default: 20)
PG_META_FORMAT_TIMEOUT_SECS=60          # Per-generation timeout (default: 60)
PG_META_FORMAT_IDLE_TIMEOUT_SECS=30     # Idle time before a worker exits (default: 30)
```

--------------------------------

### remove method example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-functions.md

Example usage of the `remove` method, dropping a function with cascade. The `data` and `error` are destructured from the result.

```ts
const { data, error } = await pgMeta.functions.remove(4242, { cascade: true })
```

--------------------------------

### Update trigger example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-triggers.md

Example call to update a trigger with OID 77, disabling it. The result is destructured into `data` and `error`.

```ts
const { data, error } = await pgMeta.triggers.update(77, { enabled_mode: 'DISABLED' })
```

--------------------------------

### create

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-extensions.md

Creates a new Postgres extension.

```APIDOC
## `create`

### Description
Creates a new Postgres extension.

### Method
`create`

### Parameters
- `name` (string) - Required - Extension name
- `schema` (string) - Optional - `SCHEMA {ident(schema)}` clause
- `version` (string) - Optional - `VERSION {literal(version)}` clause
- `cascade` (boolean) - Optional - Appends `CASCADE` (default: `false`)

### Generated SQL
```sql
CREATE EXTENSION {name} [SCHEMA {schema}] [VERSION {version}] [CASCADE];
```

### Return Type
`PostgresMetaResult<PostgresExtension>` - The created extension (re-retrieved by name).

### Example
```ts
const { data, error } = await pgMeta.extensions.create({
  name: 'pgcrypto',
  schema: 'public',
})
if (error) console.error(error.message)
```
```

--------------------------------

### PostgresMeta constructor implementation (src/lib/PostgresMeta.ts:54-78)

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta.md

Implementation of the PostgresMeta constructor. It initializes the pool via init(config), stores query and end methods, and creates sub-objects for each domain, all sharing the same query function.

```ts
// src/lib/PostgresMeta.ts:54-78
constructor(config: PoolConfig) {
  const { query, end } = init(config)
  this.query = query
  this.end = end
  this.columnPrivileges = new PostgresMetaColumnPrivileges(this.query)
  // ...one sub-object per domain, all sharing this.query
}
```

--------------------------------

### Build, Clean, and Type-Check

Source: https://github.com/supabase/postgres-meta/blob/master/CLAUDE.md

Build the project, clean artifacts, or type-check. The build process compiles TypeScript and copies src/lib/sql/*.sql files to dist/lib/sql/ via cpy-cli.

```bash
npm run build           # Compile TypeScript + copy SQL files to dist/
npm run clean           # Remove dist/ and tsconfig.tsbuildinfo
npm run check           # Type-check without emitting files
```

--------------------------------

### Set required environment variables for postgres-meta

Source: https://github.com/supabase/postgres-meta/blob/master/README.md

Set these environment variables before running any of the release binaries. The server connects to a Postgres database using these settings.

```bash
PG_META_HOST="0.0.0.0"
PG_META_PORT=8080
PG_META_DB_HOST="postgres"
PG_META_DB_NAME="postgres"
PG_META_DB_USER="postgres"
PG_META_DB_PORT=5432
PG_META_DB_PASSWORD="postgres"
```

--------------------------------

### create

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-publications.md

Creates a new PostgreSQL publication with the specified name, publish options, and optional table list.

```APIDOC
## `create`

### Description
Creates a new PostgreSQL publication with the specified name, publish options, and optional table list.

### Method
`create`

### Parameters
- `name` (string) - Required - Publication name
- `publish_insert` (boolean) - Optional - Adds `insert` to the `publish` list. Default: `false`
- `publish_update` (boolean) - Optional - Adds `update` to the `publish` list. Default: `false`
- `publish_delete` (boolean) - Optional - Adds `delete` to the `publish` list. Default: `false`
- `publish_truncate` (boolean) - Optional - Adds `truncate` to the `publish` list. Default: `false`
- `tables` (string[] | null) - Optional - `null`/`undefined` → `FOR ALL TABLES`; `[]` → no table clause; else `FOR TABLE {ident(schema)}.{ident(name)}, ...` (entries with a `.` are split into schema + table). Default: `null`

### Generated SQL
```sql
CREATE PUBLICATION {name} {FOR ALL TABLES | FOR TABLE ...}
  WITH (publish = 'insert,update,...');
```

### Return Type
`PostgresMetaResult<PostgresPublication>` (re-retrieved by name).

### Example
```ts
const { data, error } = await pgMeta.publications.create({
  name: 'orders_pub',
  publish_insert: true,
  publish_update: true,
  tables: ['public.orders'],
})
```
```

--------------------------------

### Format Code

Source: https://github.com/supabase/postgres-meta/blob/master/CLAUDE.md

Format the codebase with Prettier.

```bash
npm run format          # Format code with Prettier
```

--------------------------------

### Run development server against a custom database

Source: https://github.com/supabase/postgres-meta/blob/master/CLAUDE.md

Sets the PG_META_DB_URL environment variable to point at a custom PostgreSQL database before running the dev server. Replace user, pass, host, port, and dbname with actual connection details.

```bash
PG_META_DB_URL=postgresql://user:pass@host:port/dbname npm run dev:code
```

--------------------------------

### Remove trigger example

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-triggers.md

Example call to remove a trigger with OID 77, using cascade to drop dependent objects. The result is destructured into `data` and `error`.

```ts
const { data, error } = await pgMeta.triggers.remove(77, { cascade: true })
```

--------------------------------

### Generated SQL for create

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-extensions.md

SQL template for creating a Postgres extension. The placeholders are filled by the create method parameters.

```sql
CREATE EXTENSION {name} [SCHEMA {schema}] [VERSION {version}] [CASCADE];
```

--------------------------------

### PostgresMeta Class

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta.md

Documentation for the PostgresMeta class, including its constructor, methods, properties, and static methods.

```APIDOC
## Class: PostgresMeta

### Description
Top-level facade of the `@supabase/postgres-meta` library. Owns a Postgres connection pool and one sub-object per managed domain.

### Constructor
`new PostgresMeta(config: PoolConfig)`

- **config** (PoolConfig) - Required - `pg`'s `PoolConfig` plus an optional `maxResultSize` number.

### Methods

#### `query`

- **Signature**: `query(sql: string, opts?: { statementQueryTimeout?: number; trackQueryInSentry?: boolean; parameters?: unknown[] }) => Promise<PostgresMetaResult<any>>`
- **Description**: Executes a SQL query against the Postgres connection pool.
- **Parameters**:
  - `sql` (string) - Required - The SQL statement to execute.
  - `opts` (object) - Optional - Query options.
    - `statementQueryTimeout` (number) - Optional - Timeout for the query.
    - `trackQueryInSentry` (boolean) - Optional - Whether to track the query in Sentry.
    - `parameters` (unknown[]) - Optional - Query parameters.
- **Returns**: `Promise<PostgresMetaResult<any>>` - The result of the query.

#### `end`

- **Signature**: `end: () => Promise<void>`
- **Description**: Closes the connection pool.

### Properties

- `columnPrivileges` (PostgresMetaColumnPrivileges) - Sub-object for column privileges.
- `columns` (PostgresMetaColumns) - Sub-object for columns.
- `config` (PostgresMetaConfig) - Sub-object for configuration.
- `extensions` (PostgresMetaExtensions) - Sub-object for extensions.
- `foreignTables` (PostgresMetaForeignTables) - Sub-object for foreign tables.
- `functions` (PostgresMetaFunctions) - Sub-object for functions.
- `indexes` (PostgresMetaIndexes) - Sub-object for indexes.
- `materializedViews` (PostgresMetaMaterializedViews) - Sub-object for materialized views.
- `policies` (PostgresMetaPolicies) - Sub-object for policies.
- `publications` (PostgresMetaPublications) - Sub-object for publications.
- `relationships` (PostgresMetaRelationships) - Sub-object for relationships.
- `roles` (PostgresMetaRoles) - Sub-object for roles.
- `schemas` (PostgresMetaSchemas) - Sub-object for schemas.
- `tablePrivileges` (PostgresMetaTablePrivileges) - Sub-object for table privileges.
- `tables` (PostgresMetaTables) - Sub-object for tables.
- `triggers` (PostgresMetaTriggers) - Sub-object for triggers.
- `types` (PostgresMetaTypes) - Sub-object for types.
- `version` (PostgresMetaVersion) - Sub-object for version.
- `views` (PostgresMetaViews) - Sub-object for views.

### Static Methods

- `parse` - Parser.Parse
- `deparse` - Parser.Deparse
- `format` - Parser.Format

### Example

```ts
import PostgresMeta from '@supabase/postgres-meta'

const meta = new PostgresMeta({
  host: 'localhost',
  port: 5432,
  database: 'postgres',
  user: 'postgres',
  password: 'password',
})

const result = await meta.query('SELECT 1')
console.log(result)

await meta.end()
```
```

--------------------------------

### create

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-policies.md

Creates a new PostgreSQL policy on a table. Accepts policy name, table, schema, definition, check, action, command, and roles, and returns the created policy.

```APIDOC
## `create`

```ts
async create({
  name,
  table,
  schema = 'public',
  definition,
  check,
  action = 'PERMISSIVE',
  command = 'ALL',
  roles = ['public'],
}: {
  name: string
  table: string
  schema?: string
  definition?: string
  check?: string
  action?: string
  command?: string
  roles?: string[]
}): Promise<PostgresMetaResult<PostgresPolicy>>
```

### Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `name` | `string` | yes | — | Policy name |
| `table` | `string` | yes | — | Unqualified table name |
| `schema` | `string` | no | `'public'` | Table schema |
| `definition` | `string` | no | `undefined` | `USING ({definition})` — the policy expression |
| `check` | `string` | no | `undefined` | `WITH CHECK ({check})` |
| `action` | `string` | no | `'PERMISSIVE'` | `AS {action}` |
| `command` | `string` | no | `'ALL'` | `FOR {command}` |
| `roles` | `string[]` | no | `['public']` | `TO {ident(role),...}` |

### Generated SQL

```sql
CREATE POLICY {name} ON {schema}.{table}
  AS {action}
  FOR {command}
  TO {roles}
  {USING (definition)} {WITH CHECK (check)};
```

### Return Type

`PostgresMetaResult<PostgresPolicy>` (re-retrieved by name+table+schema).

### Example

```ts
const { data, error } = await pgMeta.policies.create({
  name: 'view_own_orders',
  table: 'orders',
  roles: ['authenticated'],
  definition: 'user_id = auth.uid()',
  check: 'true',
})
if (error) console.error(error.message)
```
```

--------------------------------

### list

Source: https://github.com/supabase/postgres-meta/blob/master/_autodocs/api-reference/postgres-meta-extensions.md

Retrieves a list of Postgres extensions with optional pagination.

```APIDOC
## `list`

### Description
Retrieves a list of Postgres extensions with optional pagination.

### Method
`list`

### Parameters
- `limit` (number) - Optional - SQL `LIMIT`
- `offset` (number) - Optional - SQL `OFFSET`

### Return Type
`PostgresMetaResult<PostgresExtension[]>` - Array of extension objects with fields: `name`, `schema`, `default_version`, `installed_version`, `comment`.
```
Tokens:
Raw