postgrest 3.0.0-dev.17

PostgREST client for Dart. This library provides an ORM interface to PostgREST.

postgrest

Dart client library for PostgREST, providing an ORM-like interface to the Supabase database.

Guides · Reference Docs

postgrest is the database client of the Supabase Dart and Flutter SDKs. In an app, use it through supabase_flutter or supabase, whose clients expose it as supabase.table(…), supabase.from(…) and supabase.rpc. Depend on postgrest directly only to talk to a PostgREST server without the rest of Supabase.

Usage

Queries are typed by a Dart file that supabase_typegen generates from the database schema, with a row type per table (BooksRow), the insert and update values that writes accept (BooksInsert, BooksUpdate), and a class holding the table definition and one constant per column (Books):

dart pub add dev:supabase_typegen
supabase gen types --lang dart > lib/supabase_schema.g.dart

The command needs Supabase CLI 3.0.0 or newer.

Import the generated supabase_schema.g.dart and pass the table definition to table(). Filters are methods on the column constants, so the compiler checks every column name and value:

import 'package:my_app/supabase_schema.g.dart';
import 'package:postgrest/postgrest.dart';

Future<void> main() async {
  final client = PostgrestClient(
    'https://your-project.supabase.co/rest/v1',
    headers: {'apikey': 'your-publishable-key'},
  );

  final List<BooksRow> books = await client
      .table(Books.table)
      .select()
      .where(Books.inPrint.isTrue() & Books.price.lt(10))
      .order(Books.title)
      .limit(20);

  await client
      .table(Books.table)
      .insert(BooksInsert(authorId: 2, title: 'Dune'));

  // A typed update() or delete() sends nothing until where() or all().
  await client
      .table(Books.table)
      .update(BooksUpdate(inPrint: false))
      .where(Books.id.eq(1));

  final BooksRow? book = await client.rpc.bookById(bookId: 1);
}

from('books') with Map<String, dynamic> rows and rpc('fn', params: {…}) remain as the untyped fallback for tables and functions that are not in the generated file.

Imports

Import package:postgrest/postgrest.dart and the generated schema whole, without show. Part of the typed API is made of extension methods, and Dart only finds an extension whose name is imported. When a show import leaves one out, its methods fail with "isn't defined", and the error does not name the extension.

A show import has to list the extensions of the methods the file calls:

Extension	Methods
PostgrestBooleanFilters	isTrue(), isFalse()
PostgrestTextFilters	like(), ilike(), matchRegex() and the other text filters
PostgrestArrayFilters	contains(), containedBy(), overlaps() on an array column
PostgrestJsonFilters	containsJson(), containedByJson()
PostgrestRangeFilters	contains(), rangeLt() and the other filters on a range column
PostgrestMultirangeFilters	contains(), rangeLt() and the other filters on a multirange column
PostgrestTypedRowsBuilder	single(), maybeSingle()
PostgrestTypedDelete, PostgrestTypedReadOnlyDelete	delete()
DatabaseFunctions, from the generated file	The typed function calls, such as rpc.bookById()

List PostgrestTypedReadOnlyDelete together with PostgrestTypedDelete. Without it, delete() on a view that cannot be updated compiles instead of being rejected.

import 'package:my_app/supabase_schema.g.dart'
    show Books, BooksRow, DatabaseFunctions;
import 'package:postgrest/postgrest.dart'
    show PostgrestBooleanFilters, PostgrestClient, PostgrestTypedRowsBuilder;

Future<BooksRow?> firstBookInPrint(PostgrestClient client) => client
    .table(Books.table)
    .select()
    .where(Books.inPrint.isTrue())
    .limit(1)
    .maybeSingle();

Future<BooksRow?> bookById(PostgrestClient client, int id) =>
    client.rpc.bookById(bookId: id);

Supabase Service Compatibility

postgrest only guarantees compatibility with the latest PostgREST release. Older PostgREST releases are supported on a best-effort basis, but compatibility is not guaranteed.

If you self-host PostgREST, we recommend upgrading to the latest release when upgrading this SDK.

Docs

The docs can be found on the official Supabase website.

• Dart reference
• Supabase API guide

License

This repo is licensed under MIT.

Credits

• https://github.com/supabase/postgrest-js - ported from postgrest-js library