lywsvip/supabase
1
0
Fork 0
mirror of https://github.com/supabase/supabase.git synced 2026-09-08 02:49:48 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
create-pull-request/patch
supabase/apps/docs/scripts/__snapshots__/build-reference-content.dart.v2.json
Lukas Klingsbo 833d3cb1d7 docs: migrate Dart/Flutter reference to the new reference pipeline (#47224) 
## What

Routes the **Dart/Flutter v2** reference through the new
reference-content pipeline (`scripts/build-reference-content.ts` +
`spec/reference/dart/v2/`), the same one JavaScript v2 already uses.
Dart v1 stays on the legacy YAML pipeline.

## How

Dart has no upstream TypeDoc dump, so this follows the reference
README's "adapt other formats as a pre-step" approach:

- **`scripts/generate-dart-reference.ts`** converts the committed legacy
spec (`spec/supabase_dart_v2.yml`) plus the shared section tree into a
TypeDoc-shaped dump at `spec/reference/dart/v2/supabase_flutter.json`
(gitignored, like every other dump). Each Dart method becomes a
`variant: 'declaration'` node tagged with `@category`/`@subcategory` and
carries the legacy function shape (description, notes, params, examples)
on a non-TypeDoc `content` field.
- **`build-reference-content.ts`** gains a small, backward-compatible
addition: it spreads a declaration's `content` straight onto the
`functions.json` entry. The renderer then shows params/examples/notes
exactly as the legacy YAML did, with no typeSpec round-trip. The field
is absent for real TypeDoc dumps, so **JavaScript output is unchanged**
(existing JS snapshot still passes).
- `dart-v2` added to `SUPPORTS_NEW_REFERENCE_PROCESS`; the v2 `specFile`
is dropped from the nav entry so the legacy generator skips it.
- Dart search ingest switched to the new-pipeline loader.
- `config.json` + hand-authored partials (intro markdown,
`initializing`, and subcategory overviews like `using-filters`,
`auth-mfa`) added under `spec/reference/dart/v2/partials/`, mirroring
the JS lib.
- The dart dump is regenerated in `codegen:references:new` and in CI; a
self-contained `dart/v2` snapshot test covers the full YAML → dump →
content path.

## Verification

- `vitest run scripts/build-reference-content.test.ts` — both JS and
Dart snapshots pass.
- 112 function sections all resolve to renderable `functions.json`
entries (104 methods + 7 subcategory overviews + `initializing`).
- `tsc --noEmit` clean for all changed files.
- Legacy generator confirmed to skip dart v2 (only `dart.v1.*`
regenerated).

> Note: the live dev server (which needs the Supabase backend) was not
run; verification was done at the data-pipeline level plus parity with
the production JS pipeline behavior.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added Dart v2 reference documentation sections, including Installing,
Initializing, Filters, Modifiers, Auth Admin, MFA, Passkeys, File
Buckets, Introduction, and Upgrade guidance.
* Expanded the Dart v2 reference pipeline so Dart API pages are
generated from the newer reference content flow.
* **Bug Fixes**
* Improved Dart reference rendering by preserving legacy descriptions,
notes, params, and examples in generated function entries.
* Updated Dart v2 reference search to use the new pipeline’s generated
content so results and navigation stay in sync.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
2026-07-03 15:09:56 +02:00

5313 lines
270 KiB
JSON
Raw Permalink Blame History

{
"bySlug": {
"introduction": {
"id": "introduction",
"title": "Introduction",
"slug": "introduction",
"type": "markdown"
},
"installing": {
"id": "installing",
"title": "Installing",
"slug": "installing",
"type": "markdown"
},
"initializing": {
"id": "initializing",
"title": "Initializing",
"slug": "initializing",
"type": "function"
},
"upgrade-guide": {
"id": "upgrade-guide",
"title": "Upgrade guide",
"slug": "upgrade-guide",
"type": "markdown"
},
"database": {
"type": "category",
"title": "Database"
},
"delete": {
"id": "delete",
"title": "delete",
"slug": "delete",
"product": "database",
"type": "function"
},
"insert": {
"id": "insert",
"title": "insert",
"slug": "insert",
"product": "database",
"type": "function"
},
"rpc": {
"id": "rpc",
"title": "rpc",
"slug": "rpc",
"product": "database",
"type": "function"
},
"select": {
"id": "select",
"title": "select",
"slug": "select",
"product": "database",
"type": "function"
},
"update": {
"id": "update",
"title": "update",
"slug": "update",
"product": "database",
"type": "function"
},
"upsert": {
"id": "upsert",
"title": "upsert",
"slug": "upsert",
"product": "database",
"type": "function"
},
"using-filters": {
"id": "using-filters",
"title": "Using filters",
"slug": "using-filters",
"type": "function"
},
"using-filters-containedby": {
"id": "using-filters-containedby",
"title": "containedBy",
"slug": "using-filters-containedby",
"product": "database",
"type": "function"
},
"using-filters-contains": {
"id": "using-filters-contains",
"title": "contains",
"slug": "using-filters-contains",
"product": "database",
"type": "function"
},
"using-filters-eq": {
"id": "using-filters-eq",
"title": "eq",
"slug": "using-filters-eq",
"product": "database",
"type": "function"
},
"using-filters-filter": {
"id": "using-filters-filter",
"title": "filter",
"slug": "using-filters-filter",
"product": "database",
"type": "function"
},
"using-filters-gt": {
"id": "using-filters-gt",
"title": "gt",
"slug": "using-filters-gt",
"product": "database",
"type": "function"
},
"using-filters-gte": {
"id": "using-filters-gte",
"title": "gte",
"slug": "using-filters-gte",
"product": "database",
"type": "function"
},
"using-filters-ilike": {
"id": "using-filters-ilike",
"title": "ilike",
"slug": "using-filters-ilike",
"product": "database",
"type": "function"
},
"using-filters-infilter": {
"id": "using-filters-infilter",
"title": "inFilter",
"slug": "using-filters-infilter",
"product": "database",
"type": "function"
},
"using-filters-isfilter": {
"id": "using-filters-isfilter",
"title": "isFilter",
"slug": "using-filters-isfilter",
"product": "database",
"type": "function"
},
"using-filters-like": {
"id": "using-filters-like",
"title": "like",
"slug": "using-filters-like",
"product": "database",
"type": "function"
},
"using-filters-lt": {
"id": "using-filters-lt",
"title": "lt",
"slug": "using-filters-lt",
"product": "database",
"type": "function"
},
"using-filters-lte": {
"id": "using-filters-lte",
"title": "lte",
"slug": "using-filters-lte",
"product": "database",
"type": "function"
},
"using-filters-match": {
"id": "using-filters-match",
"title": "match",
"slug": "using-filters-match",
"product": "database",
"type": "function"
},
"using-filters-neq": {
"id": "using-filters-neq",
"title": "neq",
"slug": "using-filters-neq",
"product": "database",
"type": "function"
},
"using-filters-not": {
"id": "using-filters-not",
"title": "not",
"slug": "using-filters-not",
"product": "database",
"type": "function"
},
"using-filters-or": {
"id": "using-filters-or",
"title": "or",
"slug": "using-filters-or",
"product": "database",
"type": "function"
},
"using-filters-overlaps": {
"id": "using-filters-overlaps",
"title": "overlaps",
"slug": "using-filters-overlaps",
"product": "database",
"type": "function"
},
"using-filters-rangeadjacent": {
"id": "using-filters-rangeadjacent",
"title": "rangeAdjacent",
"slug": "using-filters-rangeadjacent",
"product": "database",
"type": "function"
},
"using-filters-rangegt": {
"id": "using-filters-rangegt",
"title": "rangeGt",
"slug": "using-filters-rangegt",
"product": "database",
"type": "function"
},
"using-filters-rangegte": {
"id": "using-filters-rangegte",
"title": "rangeGte",
"slug": "using-filters-rangegte",
"product": "database",
"type": "function"
},
"using-filters-rangelt": {
"id": "using-filters-rangelt",
"title": "rangeLt",
"slug": "using-filters-rangelt",
"product": "database",
"type": "function"
},
"using-filters-rangelte": {
"id": "using-filters-rangelte",
"title": "rangeLte",
"slug": "using-filters-rangelte",
"product": "database",
"type": "function"
},
"using-filters-textsearch": {
"id": "using-filters-textsearch",
"title": "textSearch",
"slug": "using-filters-textsearch",
"product": "database",
"type": "function"
},
"using-modifiers": {
"id": "using-modifiers",
"title": "Using modifiers",
"slug": "using-modifiers",
"type": "function"
},
"using-modifiers-csv": {
"id": "using-modifiers-csv",
"title": "csv",
"slug": "using-modifiers-csv",
"product": "database",
"type": "function"
},
"using-modifiers-explain": {
"id": "using-modifiers-explain",
"title": "explain",
"slug": "using-modifiers-explain",
"product": "database",
"type": "function"
},
"using-modifiers-limit": {
"id": "using-modifiers-limit",
"title": "limit",
"slug": "using-modifiers-limit",
"product": "database",
"type": "function"
},
"using-modifiers-maxaffected": {
"id": "using-modifiers-maxaffected",
"title": "maxAffected",
"slug": "using-modifiers-maxaffected",
"product": "database",
"type": "function"
},
"using-modifiers-maybesingle": {
"id": "using-modifiers-maybesingle",
"title": "maybeSingle",
"slug": "using-modifiers-maybesingle",
"product": "database",
"type": "function"
},
"using-modifiers-order": {
"id": "using-modifiers-order",
"title": "order",
"slug": "using-modifiers-order",
"product": "database",
"type": "function"
},
"using-modifiers-range": {
"id": "using-modifiers-range",
"title": "range",
"slug": "using-modifiers-range",
"product": "database",
"type": "function"
},
"using-modifiers-select": {
"id": "using-modifiers-select",
"title": "select",
"slug": "using-modifiers-select",
"product": "database",
"type": "function"
},
"using-modifiers-single": {
"id": "using-modifiers-single",
"title": "single",
"slug": "using-modifiers-single",
"product": "database",
"type": "function"
},
"auth": {
"type": "category",
"title": "Auth"
},
"auth-currentsession": {
"id": "auth-currentsession",
"title": "currentSession",
"slug": "auth-currentsession",
"product": "auth",
"type": "function"
},
"auth-currentuser": {
"id": "auth-currentuser",
"title": "currentUser",
"slug": "auth-currentuser",
"product": "auth",
"type": "function"
},
"auth-getuseridentities": {
"id": "auth-getuseridentities",
"title": "getUserIdentities",
"slug": "auth-getuseridentities",
"product": "auth",
"type": "function"
},
"auth-linkidentity": {
"id": "auth-linkidentity",
"title": "linkIdentity",
"slug": "auth-linkidentity",
"product": "auth",
"type": "function"
},
"auth-linkidentitywithidtoken": {
"id": "auth-linkidentitywithidtoken",
"title": "linkIdentityWithIdToken",
"slug": "auth-linkidentitywithidtoken",
"product": "auth",
"type": "function"
},
"auth-onauthstatechange": {
"id": "auth-onauthstatechange",
"title": "onAuthStateChange",
"slug": "auth-onauthstatechange",
"product": "auth",
"type": "function"
},
"auth-reauthenticate": {
"id": "auth-reauthenticate",
"title": "reauthenticate",
"slug": "auth-reauthenticate",
"product": "auth",
"type": "function"
},
"auth-refreshsession": {
"id": "auth-refreshsession",
"title": "refreshSession",
"slug": "auth-refreshsession",
"product": "auth",
"type": "function"
},
"auth-registerpasskey": {
"id": "auth-registerpasskey",
"title": "registerPasskey",
"slug": "auth-registerpasskey",
"product": "auth",
"type": "function"
},
"auth-resend": {
"id": "auth-resend",
"title": "resend",
"slug": "auth-resend",
"product": "auth",
"type": "function"
},
"auth-resetpasswordforemail": {
"id": "auth-resetpasswordforemail",
"title": "resetPasswordForEmail",
"slug": "auth-resetpasswordforemail",
"product": "auth",
"type": "function"
},
"auth-setsession": {
"id": "auth-setsession",
"title": "setSession",
"slug": "auth-setsession",
"product": "auth",
"type": "function"
},
"auth-signinanonymously": {
"id": "auth-signinanonymously",
"title": "signInAnonymously",
"slug": "auth-signinanonymously",
"product": "auth",
"type": "function"
},
"auth-signinwithidtoken": {
"id": "auth-signinwithidtoken",
"title": "signInWithIdToken",
"slug": "auth-signinwithidtoken",
"product": "auth",
"type": "function"
},
"auth-signinwithoauth": {
"id": "auth-signinwithoauth",
"title": "signInWithOAuth",
"slug": "auth-signinwithoauth",
"product": "auth",
"type": "function"
},
"auth-signinwithotp": {
"id": "auth-signinwithotp",
"title": "signInWithOtp",
"slug": "auth-signinwithotp",
"product": "auth",
"type": "function"
},
"auth-signinwithpasskey": {
"id": "auth-signinwithpasskey",
"title": "signInWithPasskey",
"slug": "auth-signinwithpasskey",
"product": "auth",
"type": "function"
},
"auth-signinwithpassword": {
"id": "auth-signinwithpassword",
"title": "signInWithPassword",
"slug": "auth-signinwithpassword",
"product": "auth",
"type": "function"
},
"auth-signinwithsso": {
"id": "auth-signinwithsso",
"title": "signInWithSSO",
"slug": "auth-signinwithsso",
"product": "auth",
"type": "function"
},
"auth-signout": {
"id": "auth-signout",
"title": "signOut",
"slug": "auth-signout",
"product": "auth",
"type": "function"
},
"auth-signup": {
"id": "auth-signup",
"title": "signUp",
"slug": "auth-signup",
"product": "auth",
"type": "function"
},
"auth-unlinkidentity": {
"id": "auth-unlinkidentity",
"title": "unlinkIdentity",
"slug": "auth-unlinkidentity",
"product": "auth",
"type": "function"
},
"auth-updateuser": {
"id": "auth-updateuser",
"title": "updateUser",
"slug": "auth-updateuser",
"product": "auth",
"type": "function"
},
"auth-verifyotp": {
"id": "auth-verifyotp",
"title": "verifyOtp",
"slug": "auth-verifyotp",
"product": "auth",
"type": "function"
},
"auth-admin": {
"id": "auth-admin",
"title": "Auth Admin",
"slug": "auth-admin",
"type": "function"
},
"auth-admin-createuser": {
"id": "auth-admin-createuser",
"title": "createUser",
"slug": "auth-admin-createuser",
"product": "auth",
"type": "function"
},
"auth-admin-deleteuser": {
"id": "auth-admin-deleteuser",
"title": "deleteUser",
"slug": "auth-admin-deleteuser",
"product": "auth",
"type": "function"
},
"auth-admin-generatelink": {
"id": "auth-admin-generatelink",
"title": "generateLink",
"slug": "auth-admin-generatelink",
"product": "auth",
"type": "function"
},
"auth-admin-getuserbyid": {
"id": "auth-admin-getuserbyid",
"title": "getUserById",
"slug": "auth-admin-getuserbyid",
"product": "auth",
"type": "function"
},
"auth-admin-inviteuserbyemail": {
"id": "auth-admin-inviteuserbyemail",
"title": "inviteUserByEmail",
"slug": "auth-admin-inviteuserbyemail",
"product": "auth",
"type": "function"
},
"auth-admin-listusers": {
"id": "auth-admin-listusers",
"title": "listUsers",
"slug": "auth-admin-listusers",
"product": "auth",
"type": "function"
},
"auth-admin-updateuserbyid": {
"id": "auth-admin-updateuserbyid",
"title": "updateUserById",
"slug": "auth-admin-updateuserbyid",
"product": "auth",
"type": "function"
},
"auth-mfa": {
"id": "auth-mfa",
"title": "Auth MFA",
"slug": "auth-mfa",
"type": "function"
},
"auth-mfa-challenge": {
"id": "auth-mfa-challenge",
"title": "challenge",
"slug": "auth-mfa-challenge",
"product": "auth",
"type": "function"
},
"auth-mfa-challengeandverify": {
"id": "auth-mfa-challengeandverify",
"title": "challengeAndVerify",
"slug": "auth-mfa-challengeandverify",
"product": "auth",
"type": "function"
},
"auth-mfa-enroll": {
"id": "auth-mfa-enroll",
"title": "enroll",
"slug": "auth-mfa-enroll",
"product": "auth",
"type": "function"
},
"auth-mfa-getauthenticatorassurancelevel": {
"id": "auth-mfa-getauthenticatorassurancelevel",
"title": "getAuthenticatorAssuranceLevel",
"slug": "auth-mfa-getauthenticatorassurancelevel",
"product": "auth",
"type": "function"
},
"auth-mfa-unenroll": {
"id": "auth-mfa-unenroll",
"title": "unenroll",
"slug": "auth-mfa-unenroll",
"product": "auth",
"type": "function"
},
"auth-mfa-verify": {
"id": "auth-mfa-verify",
"title": "verify",
"slug": "auth-mfa-verify",
"product": "auth",
"type": "function"
},
"auth-passkey": {
"id": "auth-passkey",
"title": "Auth Passkey",
"slug": "auth-passkey",
"type": "function"
},
"auth-passkey-delete": {
"id": "auth-passkey-delete",
"title": "delete",
"slug": "auth-passkey-delete",
"product": "auth",
"type": "function"
},
"auth-passkey-list": {
"id": "auth-passkey-list",
"title": "list",
"slug": "auth-passkey-list",
"product": "auth",
"type": "function"
},
"auth-passkey-startauthentication": {
"id": "auth-passkey-startauthentication",
"title": "startAuthentication",
"slug": "auth-passkey-startauthentication",
"product": "auth",
"type": "function"
},
"auth-passkey-startregistration": {
"id": "auth-passkey-startregistration",
"title": "startRegistration",
"slug": "auth-passkey-startregistration",
"product": "auth",
"type": "function"
},
"auth-passkey-update": {
"id": "auth-passkey-update",
"title": "update",
"slug": "auth-passkey-update",
"product": "auth",
"type": "function"
},
"auth-passkey-verifyauthentication": {
"id": "auth-passkey-verifyauthentication",
"title": "verifyAuthentication",
"slug": "auth-passkey-verifyauthentication",
"product": "auth",
"type": "function"
},
"auth-passkey-verifyregistration": {
"id": "auth-passkey-verifyregistration",
"title": "verifyRegistration",
"slug": "auth-passkey-verifyregistration",
"product": "auth",
"type": "function"
},
"passkey-admin": {
"id": "passkey-admin",
"title": "Passkey Admin",
"slug": "passkey-admin",
"type": "function"
},
"passkey-admin-deletepasskey": {
"id": "passkey-admin-deletepasskey",
"title": "deletePasskey",
"slug": "passkey-admin-deletepasskey",
"product": "auth",
"type": "function"
},
"passkey-admin-listpasskeys": {
"id": "passkey-admin-listpasskeys",
"title": "listPasskeys",
"slug": "passkey-admin-listpasskeys",
"product": "auth",
"type": "function"
},
"functions": {
"type": "category",
"title": "Edge Functions"
},
"functions-invoke": {
"id": "functions-invoke",
"title": "invoke",
"slug": "functions-invoke",
"product": "edge-functions",
"type": "function"
},
"realtime": {
"type": "category",
"title": "Realtime"
},
"getchannels": {
"id": "getchannels",
"title": "getChannels",
"slug": "getchannels",
"product": "realtime",
"type": "function"
},
"removeallchannels": {
"id": "removeallchannels",
"title": "removeAllChannels",
"slug": "removeallchannels",
"product": "realtime",
"type": "function"
},
"removechannel": {
"id": "removechannel",
"title": "removeChannel",
"slug": "removechannel",
"product": "realtime",
"type": "function"
},
"stream": {
"id": "stream",
"title": "stream",
"slug": "stream",
"product": "realtime",
"type": "function"
},
"subscribe": {
"id": "subscribe",
"title": "subscribe",
"slug": "subscribe",
"product": "realtime",
"type": "function"
},
"storage": {
"type": "category",
"title": "Storage"
},
"file-buckets": {
"id": "file-buckets",
"title": "File Buckets",
"slug": "file-buckets",
"type": "function"
},
"file-buckets-createbucket": {
"id": "file-buckets-createbucket",
"title": "createBucket",
"slug": "file-buckets-createbucket",
"product": "storage",
"type": "function"
},
"file-buckets-createsignedurl": {
"id": "file-buckets-createsignedurl",
"title": "createSignedUrl",
"slug": "file-buckets-createsignedurl",
"product": "storage",
"type": "function"
},
"file-buckets-deletebucket": {
"id": "file-buckets-deletebucket",
"title": "deleteBucket",
"slug": "file-buckets-deletebucket",
"product": "storage",
"type": "function"
},
"file-buckets-download": {
"id": "file-buckets-download",
"title": "download",
"slug": "file-buckets-download",
"product": "storage",
"type": "function"
},
"file-buckets-emptybucket": {
"id": "file-buckets-emptybucket",
"title": "emptyBucket",
"slug": "file-buckets-emptybucket",
"product": "storage",
"type": "function"
},
"file-buckets-getbucket": {
"id": "file-buckets-getbucket",
"title": "getBucket",
"slug": "file-buckets-getbucket",
"product": "storage",
"type": "function"
},
"file-buckets-getpublicurl": {
"id": "file-buckets-getpublicurl",
"title": "getPublicUrl",
"slug": "file-buckets-getpublicurl",
"product": "storage",
"type": "function"
},
"file-buckets-list": {
"id": "file-buckets-list",
"title": "list",
"slug": "file-buckets-list",
"product": "storage",
"type": "function"
},
"file-buckets-listbuckets": {
"id": "file-buckets-listbuckets",
"title": "listBuckets",
"slug": "file-buckets-listbuckets",
"product": "storage",
"type": "function"
},
"file-buckets-move": {
"id": "file-buckets-move",
"title": "move",
"slug": "file-buckets-move",
"product": "storage",
"type": "function"
},
"file-buckets-remove": {
"id": "file-buckets-remove",
"title": "remove",
"slug": "file-buckets-remove",
"product": "storage",
"type": "function"
},
"file-buckets-update": {
"id": "file-buckets-update",
"title": "update",
"slug": "file-buckets-update",
"product": "storage",
"type": "function"
},
"file-buckets-updatebucket": {
"id": "file-buckets-updatebucket",
"title": "updateBucket",
"slug": "file-buckets-updatebucket",
"product": "storage",
"type": "function"
},
"file-buckets-upload": {
"id": "file-buckets-upload",
"title": "upload",
"slug": "file-buckets-upload",
"product": "storage",
"type": "function"
}
},
"flat": [
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]"
],
"sections": [
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
{
"type": "category",
"title": "Database",
"items": [
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
{
"id": "using-filters",
"isFunc": false,
"title": "Using filters",
"slug": "using-filters",
"product": "database",
"type": "function",
"items": [
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]"
]
},
{
"id": "using-modifiers",
"isFunc": false,
"title": "Using modifiers",
"slug": "using-modifiers",
"product": "database",
"type": "function",
"items": [
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]"
]
}
]
},
{
"type": "category",
"title": "Auth",
"items": [
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
{
"id": "auth-admin",
"isFunc": false,
"title": "Auth Admin",
"slug": "auth-admin",
"product": "auth",
"type": "function",
"items": [
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]"
]
},
{
"id": "auth-mfa",
"isFunc": false,
"title": "Auth MFA",
"slug": "auth-mfa",
"product": "auth",
"type": "function",
"items": [
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]"
]
},
{
"id": "auth-passkey",
"isFunc": false,
"title": "Auth Passkey",
"slug": "auth-passkey",
"product": "auth",
"type": "function",
"items": [
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]"
]
},
{
"id": "passkey-admin",
"isFunc": false,
"title": "Passkey Admin",
"slug": "passkey-admin",
"product": "auth",
"type": "function",
"items": [
"[Circular]",
"[Circular]",
"[Circular]"
]
}
]
},
{
"type": "category",
"title": "Edge Functions",
"items": [
"[Circular]"
]
},
{
"type": "category",
"title": "Realtime",
"items": [
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]"
]
},
{
"type": "category",
"title": "Storage",
"items": [
{
"id": "file-buckets",
"isFunc": false,
"title": "File Buckets",
"slug": "file-buckets",
"product": "storage",
"type": "function",
"items": [
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]",
"[Circular]"
]
}
]
}
],
"functionsList": [
{
"id": "initializing",
"title": "Initializing",
"description": "You can initialize Supabase with the static `initialize()` method of the `Supabase` class.\n\nThe Supabase client is your entrypoint to the rest of the Supabase functionality\nand is the easiest way to interact with everything we offer within the Supabase ecosystem.\n",
"params": [
{
"name": "url",
"isOptional": false,
"type": "string",
"description": "The unique Supabase URL which is supplied when you create a new project in your project dashboard."
},
{
"name": "publishableKey",
"isOptional": false,
"type": "string",
"description": "The publishable (anon) key supplied when you create a new project in your project dashboard. Use this for client-side apps. The deprecated `anonKey` parameter is still accepted but `publishableKey` takes precedence when both are supplied."
},
{
"name": "headers",
"isOptional": true,
"type": "Map<String, String>",
"description": "Custom header to be passed to the Supabase client."
},
{
"name": "httpClient",
"isOptional": true,
"type": "Client",
"description": "Custom http client to be used by the Supabase client."
},
{
"name": "authOptions",
"isOptional": true,
"type": "FlutterAuthClientOptions",
"description": "Options to change the Auth behaviors.",
"subContent": [
{
"name": "authFlowType",
"isOptional": true,
"type": "AuthFlowType",
"description": "Whether to use the `pkce` flow or the `implicit` flow. Defaults to `pkce`."
},
{
"name": "localStorage",
"isOptional": true,
"type": "LocalStorage",
"description": "Parameter to override the local storage to store auth tokens."
},
{
"name": "autoRefreshToken",
"isOptional": true,
"type": "bool",
"description": "Whether to automatically refresh the token when it expires. Defaults to `true`."
}
]
},
{
"name": "postgrestOptions",
"isOptional": true,
"type": "PostgrestClientOptions",
"description": "Options to change the Postgrest behaviors.",
"subContent": [
{
"name": "schema",
"isOptional": true,
"type": "String",
"description": "Schema to query with the Supabase client. Defaults to `public`."
}
]
},
{
"name": "realtimeClientOptions",
"isOptional": true,
"type": "RealtimeClientOptions",
"description": "Options to change the Realtime behaviors.",
"subContent": [
{
"name": "logLevel",
"isOptional": true,
"type": "RealtimeLogLevel",
"description": "Level of realtime server logs to to be logged."
}
]
},
{
"name": "storageOptions",
"isOptional": true,
"type": "StorageClientOptions",
"description": "Options to change the Storage behaviors.",
"subContent": [
{
"name": "retryAttempts",
"isOptional": true,
"type": "int",
"description": "The number of times to retry a failed upload request. Defaults to `0`."
},
{
"name": "useNewHostname",
"isOptional": true,
"type": "bool",
"description": "Whether to rewrite legacy storage URLs to use the dedicated storage host (`<ref>.storage.supabase.co`). Set to `true` only if your project has the dedicated storage host enabled. Defaults to `false`."
}
]
}
],
"examples": [
{
"id": "flutter-initialize",
"name": "For Flutter",
"code": "```dart\nFuture<void> main() async {\n await Supabase.initialize(\n url: 'https://xyzcompany.supabase.co',\n publishableKey: 'your-publishable-key',\n );\n\n runApp(MyApp());\n}\n\n// Get a reference your Supabase client\nfinal supabase = Supabase.instance.client;\n```\n"
},
{
"id": "for-other-dart-projects",
"name": "For other Dart projects",
"code": "```dart\nfinal supabase = SupabaseClient(\n 'https://xyzcompany.supabase.co',\n 'your-secret-key', // use your secret key for server-side usage\n);\n```\n"
}
]
},
{
"id": "delete",
"$ref": "supabase_flutter.delete",
"description": "Perform a DELETE on the table or view.\n",
"notes": "- `delete()` should always be combined with [Filters](/docs/reference/dart/using-filters) to target the item(s) you wish to delete.\n- If you use `delete()` with filters and you have RLS enabled, only rows visible through `SELECT` policies are deleted. Note that by default no rows are visible, so you need at least one `SELECT`/`ALL` policy that makes the rows visible.\n",
"examples": [
{
"id": "delete-records",
"name": "Delete records",
"isSpotlight": true,
"code": "```dart\nawait supabase\n .from('countries')\n .delete()\n .eq('id', 1);\n```\n",
"data": {
"sql": "```sql\ncreate table\n countries (id int8 primary key, name text);\n\ninsert into\n countries (id, name)\nvalues\n (1, 'Mordor');\n```\n"
}
},
{
"id": "delete-multiple-records",
"name": "Delete multiple records",
"code": "```dart\nawait supabase\n .from('countries')\n .delete()\n .inFilter('id', [1, 2, 3])\n```\n",
"data": {
"sql": "```sql\ncreate table\n countries (id int8 primary key, name text);\n\ninsert into\n countries (id, name)\nvalues\n (1, 'Mordor'), (2, 'Gondor'), (3, 'Rohan');\n```\n"
}
},
{
"id": "fetch-delete-records",
"name": "Fetch deleted records",
"code": "```dart\nfinal List<Map<String,dynamic>> data = await supabase\n .from('cities')\n .delete()\n .match({ 'id': 666 })\n .select();\n```\n"
}
]
},
{
"id": "insert",
"$ref": "supabase_flutter.insert",
"description": "Perform an INSERT into the table or view.\n",
"params": [
{
"name": "values",
"isOptional": false,
"type": "Map<String, dynamic> or List<Map<String, dynamic>>",
"description": "The values to insert. Pass an object to insert a single row or an array to insert multiple rows."
}
],
"examples": [
{
"id": "create-a-record",
"name": "Create a record",
"isSpotlight": true,
"code": "```dart\nawait supabase\n .from('cities')\n .insert({'name': 'The Shire', 'country_id': 554});\n```\n",
"data": {
"sql": "```sql\ncreate table\n countries (id int8 primary key, name text);\n```\n"
},
"hideCodeBlock": true
},
{
"id": "fetch-inserted-data",
"name": "Fetch inserted record",
"code": "```dart\nfinal List<Map<String, dynamic>> data =\n await supabase.from('cities').insert([\n {'name': 'The Shire', 'country_id': 554},\n {'name': 'Rohan', 'country_id': 555},\n ]).select();\n```\n",
"data": {
"sql": "```sql\ncreate table\n countries (id int8 primary key, name text);\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'name': 'Denmark'\n }\n]\n```\n"
},
{
"id": "bulk-create",
"name": "Bulk create",
"code": "```dart\nawait supabase.from('cities').insert([\n {'name': 'The Shire', 'country_id': 554},\n {'name': 'Rohan', 'country_id': 555},\n]);\n```\n",
"data": {
"sql": "```sql\ncreate table\n countries (id int8 primary key, name text);\n```\n"
},
"response": "```json\nPostgrestException(\n 'code': '23505',\n 'details': 'Key (id)=(1) already exists.',\n 'hint': null,\n 'message': 'duplicate key value violates unique constraint \"countries_pkey\"'\n);\n```\n"
}
]
},
{
"id": "rpc",
"$ref": "supabase_flutter.rpc",
"description": "Perform a function call.\n\nYou can call Postgres functions as Remote Procedure Calls, logic in your database that you can execute from anywhere.\nFunctions are useful when the logic rarely changes—like for password resets and updates.\n",
"params": [
{
"name": "fn",
"isOptional": false,
"type": "String",
"description": "The function name to call."
},
{
"name": "params",
"isOptional": true,
"type": "Map<String, dynamic>",
"description": "The arguments to pass to the function call."
}
],
"examples": [
{
"id": "call-a-postgres-function-without-arguments",
"name": "Call a Postgres function without arguments",
"code": "```dart\nfinal data = await supabase\n .rpc('hello_world');\n```\n",
"data": {
"sql": "```sql\ncreate function hello_world() returns text as $$\n select 'Hello world';\n$$ language sql;\n```\n"
},
"response": "```json\n'Hello world'\n```\n",
"hideCodeBlock": true,
"isSpotlight": true
},
{
"id": "call-a-postgres-function-with-arguments",
"name": "Call a Postgres function with arguments",
"code": "```dart\nfinal data = await supabase\n .rpc('echo_city', params: { 'say': '👋' });\n```\n",
"data": {
"sql": "```sql\ncreate function echo(say text) returns text as $$\n select say;\n$$ language sql;\n```\n"
},
"response": "```json\n'👋'\n```\n",
"hideCodeBlock": true
},
{
"id": "bulk-processing",
"name": "Bulk processing",
"code": "```dart\nfinal data = await supabase\n .rpc('add_one_each', params: { arr: [1, 2, 3] });\n```\n",
"data": {
"sql": "```sql\ncreate function add_one_each(arr int[]) returns int[] as $$\n select array_agg(n + 1) from unnest(arr) as n;\n$$ language sql;\n```\n"
},
"response": "```json\n[\n 2,\n 3,\n 4,\n]\n```\n",
"description": "You can process large payloads by passing in an array as an argument.\n",
"hideCodeBlock": true
},
{
"id": "call-a-postgres-function-with-filters",
"name": "Call a Postgres function with filters",
"code": "```dart\nfinal data = await supabase\n .rpc('list_stored_countries')\n .eq('id', 1)\n .single();\n```\n",
"data": {
"sql": "```sql\ncreate table\n countries (id int8 primary key, name text);\n\ninsert into\n countries (id, name)\nvalues\n (1, 'Mordor'),\n (2, 'Gondor');\n\ncreate function list_stored_countries() returns setof countries as $$\n select * from countries;\n$$ language sql;\n```\n"
},
"response": "```json\n{\n 'id': 1,\n 'name': 'Mordor'\n}\n```\n",
"description": "Postgres functions that return tables can also be combined with [Filters](/docs/reference/dart/using-filters) and [Modifiers](/docs/reference/dart/using-modifiers).\n",
"hideCodeBlock": true
}
]
},
{
"id": "select",
"$ref": "supabase_flutter.select",
"description": "Perform a SELECT query on the table or view.\n",
"notes": "- By default, Supabase projects will return a maximum of 1,000 rows. This setting can be changed in Project API Settings. It's recommended that you keep it low to limit the payload size of accidental or malicious requests. You can use `range()` queries to paginate through your data.\n- `select()` can be combined with [Filters](/docs/reference/dart/using-filters)\n- `select()` can be combined with [Modifiers](/docs/reference/dart/using-modifiers)\n- `apikey` is a reserved keyword if you're using the [Supabase Platform](/docs/guides/platform) and [should be avoided as a column name](https://github.com/supabase/supabase/issues/5465).\n",
"params": [
{
"name": "columns",
"isOptional": true,
"type": "String",
"description": "The columns to retrieve, separated by commas. Columns can be renamed when returned with `customName:columnName`"
}
],
"examples": [
{
"id": "getting-your-data",
"name": "Getting your data",
"isSpotlight": true,
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select();\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'name': 'violin'\n },\n {\n 'id': 2,\n 'name': 'viola'\n },\n {\n 'id': 3,\n 'name': 'cello'\n },\n]\n```\n"
},
{
"id": "selecting-specific-columns",
"name": "Selecting specific columns",
"description": "You can select specific fields from your tables.",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select('''\n name\n ''');\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```json\n[\n {\n 'name': 'violin'\n },\n {\n 'name': 'viola'\n },\n {\n 'name': 'cello'\n },\n]\n```\n"
},
{
"id": "query-referenced-tables",
"name": "Query referenced tables",
"description": "If your database has relationships, you can query related tables too.",
"code": "```dart\nfinal data = await supabase\n .from('orchestral_sections')\n .select('''\n name,\n instruments ( name )\n ''');\n```\n",
"data": {
"sql": "```sql\ncreate table\n orchestral_sections (id int8 primary key, name text);\ncreate table\n instruments (\n id int8 primary key,\n section_id int8 not null references sections,\n name text\n );\n\ninsert into\n orchestral_sections (id, name)\nvalues\n (1, 'strings'),\n (2, 'woodwinds');\ninsert into\n instruments (id, section_id, name)\nvalues\n (1, 2, 'flute'),\n (2, 1, 'violin');\n```\n"
},
"response": "```json\n[\n {\n 'name': 'strings',\n 'instruments': [\n {\n 'name': 'violin'\n },\n ]\n },\n {\n 'name': 'woodwinds',\n 'instruments': [\n {\n 'name': 'flute'\n },\n ]\n },\n]\n```\n"
},
{
"id": "query-referenced-tables-through-a-join-table",
"name": "Query referenced tables through a join table",
"code": "```dart\nfinal data = await supabase\n .from('users')\n .select('''\n name,\n teams (\n name\n )\n ''');\n ```\n",
"data": {
"sql": "```sql\ncreate table\n users (\n id int8 primary key,\n name text\n );\ncreate table\n teams (\n id int8 primary key,\n name text\n );\n-- join table\ncreate table\n users_teams (\n user_id int8 not null references users,\n team_id int8 not null references teams,\n -- both foreign keys must be part of a composite primary key\n primary key (user_id, team_id)\n );\n\ninsert into\n users (id, name)\nvalues\n (1, 'Kiran'),\n (2, 'Evan');\ninsert into\n teams (id, name)\nvalues\n (1, 'Green'),\n (2, 'Blue');\ninsert into\n users_teams (user_id, team_id)\nvalues\n (1, 1),\n (1, 2),\n (2, 2);\n```\n"
},
"response": "```json\n[\n {\n 'name': 'Kiran',\n 'teams': [\n {\n 'name': 'Green'\n },\n {\n 'name': 'Blue'\n },\n ]\n },\n {\n 'name': 'Evan',\n 'teams': [\n {\n 'name': 'Blue'\n }\n ]\n }\n]\n```\n",
"description": "If you're in a situation where your tables are **NOT** directly\nrelated, but instead are joined by a _join table_, you can still use\nthe `select()` method to query the related data. The join table needs\nto have the foreign keys as part of its composite primary key.\n",
"hideCodeBlock": true
},
{
"id": "query-the-same-referenced-table-multiple-times",
"name": "Query the same referenced table multiple times",
"description": "Sometimes you will need to query the same referenced table twice. In\nthis case, you can use the name of the joined column to identify which\njoin you intend to use. For convenience, you can also give an alias\nfor each column. This example queries a `messages` table that is\njoined to a `users` table via `sender_id` and `receiver_id`. Since you\nwant the `name` for both sender and receiver, you can alias the\ncolumns as `to` and `from`.\n",
"code": "```dart\nfinal data = await supabase\n .from('messages')\n .select('''\n content,\n from:sender_id(name),\n to:receiver_id(name)\n ''');\n```\n",
"data": {
"sql": "```sql\n create table\n users (id int8 primary key, name text);\n\n create table\n messages (\n sender_id int8 not null references users,\n receiver_id int8 not null references users,\n content text\n );\n\n insert into\n users (id, name)\n values\n (1, 'Kiran'),\n (2, 'Evan');\n\n insert into\n messages (sender_id, receiver_id, content)\n values\n (1, 2, '👋');\n ```\n"
},
"response": "```json\n[\n {\n 'content': '👋',\n 'from': {\n 'name': 'Kiran'\n },\n 'to': {\n 'name': 'Evan'\n }\n }\n]\n```\n"
},
{
"id": "filtering-through-referenced-tables",
"name": "Filtering through referenced tables",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select('name, orchestral_sections(*)')\n .eq('orchestral_sections.name', 'percussion');\n```\n",
"data": {
"sql": "```sql\ncreate table\n orchestral_sections (id int8 primary key, name text);\ncreate table\n instruments (\n id int8 primary key,\n section_id int8 not null references orchestral_sections,\n name text\n );\n\ninsert into\n orchestral_sections (id, name)\nvalues\n (1, 'strings'),\n (2, 'woodwinds');\ninsert into\n instruments (id, section_id, name)\nvalues\n (1, 2, 'flute'),\n (2, 1, 'violin');\n```\n"
},
"response": "```json\n[\n {\n 'name': 'flute',\n 'orchestral_sections': null\n },\n {\n 'name': 'violin',\n 'orchestral_sections': null\n }\n]\n```\n",
"description": "If the filter on a referenced table's column is not satisfied, the referenced\ntable returns `[]` or `null` but the parent table is not filtered out.\nIf you want to filter out the parent table rows, use the `!inner` hint\n",
"hideCodeBlock": true
},
{
"id": "querying-with-count-option",
"name": "Querying with count option",
"description": "You can get the number of rows by using the count option.\nAllowed values for count option are [CountOption.exact](https://postgrest.org/en/stable/api.html#exact-count), [CountOptionplanned](https://postgrest.org/en/stable/api.html#planned-count) and [CountOption.estimated](https://postgrest.org/en/stable/api.html#estimated-count).\n",
"code": "```dart\nfinal res = await supabase\n .from('instruments')\n .select('name')\n .count(CountOption.exact);\n\nfinal data = res.data;\nfinal count = res.count;\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```json\nPostgrestResponse(\n data: [\n {\n 'id': 1,\n 'name': 'violin'\n },\n {\n 'id': 2,\n 'name': 'viola'\n },\n {\n 'id': 3,\n 'name': 'cello'\n }\n ],\n count: 3\n);\n```\n"
},
{
"id": "querying-json-data",
"name": "Querying JSON data",
"description": "If you have data inside of a JSONB column, you can apply select\nand query filters to the data values. Postgres offers a\n[number of operators](https://www.postgresql.org/docs/current/functions-json.html)\nfor querying JSON data. Also see\n[PostgREST docs](http://postgrest.org/en/v7.0.0/api.html#json-columns) for more details.\n",
"code": "```dart\nfinal data = await supabase\n .from('users')\n .select('''\n id, name,\n address->city\n ''');\n```\n",
"data": {
"sql": "```sql\ncreate table\n users (\n id int8 primary key,\n name text,\n address jsonb\n );\n\ninsert into\n users (id, name, address)\nvalues\n (1, 'Frodo', '{\"city\":\"Hobbiton\"}');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'name': 'Frodo',\n 'city': 'Hobbiton'\n }\n]\n```\n"
},
{
"id": "querying-referenced-table-with-inner-join",
"name": "Querying referenced table with inner join",
"code": "```dart\nfinal data = await supabase\n .from('orchestral_sections')\n .select('name, instruments!inner(name)')\n .eq('orchestral_sections.name', 'strings')\n .limit(1);\n```\n",
"data": {
"sql": "```sql\ncreate table orchestral_sections (\n \"id\" \"uuid\" primary key default \"extensions\".\"uuid_generate_v4\"() not null,\n \"name\" text\n);\n\ncreate table instruments (\n \"id\" \"uuid\" primary key default \"extensions\".\"uuid_generate_v4\"() not null,\n \"name\" text,\n \"section_id\" \"uuid\" references public.orchestral_sections on delete cascade\n);\n\nwith section as (\n insert into orchestral_sections (name)\n values ('strings') returning id\n)\ninsert into instruments (name, section_id) values\n('violin', (select id from section)),\n('viola', (select id from section)),\n('cello', (select id from section)),\n('double bass', (select id from section));\n```\n"
},
"response": "```json\n[\n {\n 'name': 'violin',\n 'orchestral_sections': {'name': 'strings'}\n }\n]\n```\n",
"description": "If you don't want to return the referenced table contents, you can leave the parenthesis empty.\nLike `.select('name, books!inner()')`.\n",
"hideCodeBlock": true
},
{
"id": "switching-schemas-per-query",
"name": "Switching schemas per query",
"code": "```dart\nfinal data = await supabase\n .schema('myschema')\n .from('mytable')\n .select();\n```\n",
"data": {
"sql": "```sql\ncreate schema myschema;\n\ncreate table myschema.mytable (\n id uuid primary key default gen_random_uuid(),\n data text\n);\n\ninsert into myschema.mytable (data) values ('mydata');\n```\n"
},
"response": "```json\n[\n {\n 'id': '4162e008-27b0-4c0f-82dc-ccaeee9a624d',\n 'data': 'mydata'\n }\n]\n```\n",
"description": "In addition to setting the schema during initialization, you can also switch schemas on a per-query basis.\nMake sure you've set up your [database privileges and API settings](/docs/guides/api/using-custom-schemas).\n",
"hideCodeBlock": true
}
]
},
{
"id": "update",
"$ref": "supabase_flutter.update",
"description": "Perform an UPDATE on the table or view.\n",
"notes": "- `update()` should always be combined with [Filters](/docs/reference/dart/using-filters) to target the item(s) you wish to update.\n",
"params": [
{
"name": "values",
"isOptional": false,
"type": "Map<String, dynamic>",
"description": "The values to update with."
}
],
"examples": [
{
"id": "updating-your-data",
"name": "Update your data",
"isSpotlight": true,
"code": "```dart\nawait supabase\n .from('instruments')\n .update({ 'name': 'piano' })\n .eq('id', 1);\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'harpsichord');\n```\n"
}
},
{
"id": "update-a-record-and-return-it",
"name": "Update a record and return it",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .update({ 'name': 'piano' })\n .eq('id', 1)\n .select();\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'harpsichord');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'name': 'piano'\n }\n]\n```\n",
"hideCodeBlock": true
},
{
"id": "updating-json-data",
"name": "Update JSON data",
"code": "```dart\nawait supabase\n .from('users')\n .update({\n 'address': {\n 'street': 'Melrose Place',\n 'postcode': 90210\n }\n })\n .eq('address->postcode', 90210);\n```\n",
"data": {
"sql": "```sql\ncreate table\n users (\n id int8 primary key,\n name text,\n address jsonb\n );\n\ninsert into\n users (id, name, address)\nvalues\n (1, 'Michael', '{ \"postcode\": 90210 }');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'name': 'Michael',\n 'address': {\n 'street': 'Melrose Place',\n 'postcode': 90210\n }\n }\n]\n```\n",
"description": "Postgres offers some\n[operators](/docs/guides/database/json#query-the-jsonb-data) for\nworking with JSON data. Currently, it is only possible to update the entire JSON document.\n"
}
]
},
{
"id": "upsert",
"$ref": "supabase_flutter.upsert",
"description": "Perform an UPSERT on the table or view. Depending on the column(s) passed to `onConflict`, `.upsert()` allows you to perform the equivalent of `.insert()` if a row with the corresponding `onConflict` columns doesn't exist, or if it does exist, perform an alternative action depending on `ignoreDuplicates`.\n",
"notes": "- Primary keys must be included in `values` to use upsert.\n",
"params": [
{
"name": "values",
"isOptional": false,
"type": "Map<String, dynamic> or List<Map<String, dynamic>>",
"description": "The values to upsert with. Pass a Map to upsert a single row or an array to upsert multiple rows."
},
{
"name": "onConflict",
"isOptional": true,
"type": "String",
"description": "Comma-separated UNIQUE column(s) to specify how duplicate rows are determined. Two rows are duplicates if all the `onConflict` columns are equal."
},
{
"name": "ignoreDuplicates",
"isOptional": true,
"type": "bool",
"description": "If `true`, duplicate rows are ignored. If `false`, duplicate rows are merged with existing rows."
},
{
"name": "defaultToNull",
"isOptional": true,
"type": "bool",
"description": "Make missing fields default to `null`. Otherwise, use the default value for the column. This only applies when inserting new rows, not when merging with existing rows where ignoreDuplicates is set to false. This also only applies when doing bulk upserts."
}
],
"examples": [
{
"id": "upsert-your-data",
"name": "Upsert your data",
"isSpotlight": true,
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .upsert({ 'id': 1, 'name': 'piano' })\n .select();\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'harpsichord');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'name': 'piano'\n }\n]\n```\n"
},
{
"id": "bulk-upsert-your-data",
"name": "Bulk Upsert your data",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .upsert([\n { 'id': 1, 'name': 'piano' },\n { 'id': 2, 'name': 'harp' },\n ])\n .select();\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'harpsichord');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'name': 'piano'\n },\n {\n 'id': 2,\n 'name': 'harp'\n }\n]\n```\n",
"hideCodeBlock": true
},
{
"id": "upserting-into-tables-with-constraints",
"name": "Upserting into tables with constraints",
"isSpotlight": true,
"code": "```dart\nfinal data = await supabase\n .from('users')\n .upsert({ 'id': 42, 'handle': 'saoirse', 'display_name': 'Saoirse' }, { onConflict: 'handle' })\n .select();\n```\n",
"data": {
"sql": "```sql\ncreate table\n users (\n id int8 generated by default as identity primary key,\n handle text not null unique,\n display_name text\n );\n\ninsert into\n users (id, handle, display_name)\nvalues\n (1, 'saoirse', null);\n```\n"
},
"response": "```json\nPostgrestException(\n 'code': '23505',\n 'details': 'Key (handle)=(saoirse) already exists.',\n 'hint': null,\n 'message': \"duplicate key value violates unique constraint \"users_handle_key\"'\n)\n```\n",
"description": "In the above query, `upsert()` implicitly uses the `id`\n(primary key) column to determine conflicts. If there is no existing\nrow with the same `id`, `upsert()` inserts a new row, which\nwill fail in this case as there is already a row with `handle` `\"saoirse\"`.\nUsing the `onConflict` option, you can instruct `upsert()` to use\nanother column with a unique constraint to determine conflicts.\n"
}
]
},
{
"id": "using-filters",
"title": "Using filters",
"description": "Filters allow you to only return rows that match certain conditions.\n\nFilters can be used on `select()`, `update()`, `upsert()`, and `delete()` queries.\n\nIf a Database function returns a table response, you can also apply filters.\n",
"examples": [
{
"id": "applying-filters",
"name": "Applying Filters",
"description": "Filters must be applied after any of `select()`, `update()`, `upsert()`,\n`delete()`, and `rpc()` and before\n[modifiers](/docs/reference/dart/using-modifiers).\n",
"code": "```dart\nfinal data = await supabase\n .from('cities')\n .select('name, country_id')\n .eq('name', 'The Shire'); // Correct\n\nfinal data = await supabase\n .from('cities')\n .eq('name', 'The Shire') // Incorrect\n .select('name, country_id');\n```\n"
},
{
"id": "chaining-filters",
"name": "Chaining Filters",
"description": "Filters can be chained together to produce advanced queries as shown in the example code.\n",
"code": "```dart\nfinal data = await supabase\n .from('cities')\n .select('name, country_id')\n .gte('population', 1000)\n .lt('population', 10000)\n```\n"
},
{
"id": "conditional-chaining",
"name": "Conditional Chaining",
"description": "Filters can be built up one step at a time and then executed as shown in the example code.\n",
"code": "```dart\nfinal filterByName = null;\nfinal filterPopLow = 1000;\nfinal filterPopHigh = 10000;\n\nvar query = supabase\n .from('cities')\n .select('name, country_id');\n\nif (filterByName != null) query = query.eq('name', filterByName);\nif (filterPopLow != null) query = query.gte('population', filterPopLow);\nif (filterPopHigh != null) query = query.lt('population', filterPopHigh);\n\nfinal data = await query;\n```\n"
},
{
"id": "filter-by-value-within-json-column",
"name": "Filter by values within a JSON column",
"data": {
"sql": "```sql\ncreate table\n users (\n id int8 primary key,\n name text,\n address jsonb\n );\n\ninsert into\n users (id, name, address)\nvalues\n (1, 'Michael', '{ \"postcode\": 90210 }'),\n (2, 'Jane', null);\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'name': 'Michael',\n 'address': {\n 'postcode': 90210\n }\n },\n]\n```\n",
"code": "```dart\nfinal data = await supabase\n .from('users')\n .select()\n .eq('address->postcode', 90210);\n```\n"
},
{
"id": "filter-referenced-tables",
"name": "Filter Referenced Tables",
"code": "```dart\nfinal data = await supabase\n .from('orchestral_sections')\n .select('''\n name,\n instruments!inner (\n name\n )\n ''')\n .eq('instruments.name', 'flute');\n```\n",
"data": {
"sql": "```sql\ncreate table\n orchestral_sections (id int8 primary key, name text);\ncreate table\n instruments (\n id int8 primary key,\n section_id int8 not null references orchestral_sections,\n name text\n );\n\ninsert into\n orchestral_sections (id, name)\nvalues\n (1, 'strings'),\n (2, 'woodwinds');\ninsert into\n instruments (id, section_id, name)\nvalues\n (1, 2, 'flute'),\n (2, 1, 'violin');\n```\n"
},
"response": "```json\n[\n {\n 'name': 'strings',\n 'instruments': [\n {\n 'name': 'flute'\n }\n ]\n },\n]\n```\n",
"description": "You can filter on referenced tables in your `select()` query using dot\nnotation.\n"
}
]
},
{
"id": "using-filters-containedby",
"$ref": "supabase_flutter.containedBy",
"description": "Only relevant for jsonb, array, and range columns. Match only rows where every element appearing in `column` is contained by `value`.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The jsonb, array, or range column to filter on."
},
{
"name": "value",
"isOptional": false,
"type": "Object",
"description": "The jsonb, array, or range value to filter with."
}
],
"examples": [
{
"id": "on-array-columns",
"name": "On array columns",
"isSpotlight": true,
"code": "```dart\nfinal data = await supabase\n .from('classes')\n .select('name')\n .containedBy('days', ['monday', 'tuesday', 'wednesday', 'friday']);\n```\n",
"data": {
"sql": "```sql\ncreate table\n classes (\n id int8 primary key,\n name text,\n days text[]\n );\n\ninsert into\n classes (id, name, days)\nvalues\n (1, 'Chemistry', array['monday', 'friday']),\n (2, 'History', array['monday', 'wednesday', 'thursday']);\n```\n"
},
"response": "```json\n[\n {\n 'name': 'Chemistry'\n },\n]\n```\n",
"hideCodeBlock": true
},
{
"id": "on-range-columns",
"name": "On range columns",
"code": "```dart\nfinal data = await supabase\n .from('reservations')\n .select()\n .containedBy('during', '[2000-01-01 00:00, 2000-01-01 23:59)');\n```\n",
"data": {
"sql": "```sql\ncreate table\n reservations (\n id int8 primary key,\n room_name text,\n during tsrange\n );\n\ninsert into\n reservations (id, room_name, during)\nvalues\n (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),\n (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'room_name': 'Emerald',\n 'during': '[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")'\n },\n]\n```\n",
"description": "Postgres supports a number of [range\ntypes](https://www.postgresql.org/docs/current/rangetypes.html). You\ncan filter on range columns using the string representation of range\nvalues.\n",
"hideCodeBlock": true
},
{
"id": "on-jsonb-columns",
"name": "On `jsonb` columns",
"code": "```dart\nfinal data = await supabase\n .from('users')\n .select('name')\n .containedBy('address', {'postcode': 90210});\n```\n",
"data": {
"sql": "```sql\ncreate table\n users (\n id int8 primary key,\n name text,\n address jsonb\n );\n\ninsert into\n users (id, name, address)\nvalues\n (1, 'Michael', '{ \"postcode\": 90210, \"street\": \"Melrose Place\" }'),\n (2, 'Jane', '{\"postcode\": 90210}');\n```\n"
},
"response": "```json\n [\n {\n 'name': 'Jane'\n },\n ]\n ```\n",
"hideCodeBlock": true
}
]
},
{
"id": "using-filters-contains",
"$ref": "supabase_flutter.contains",
"description": "Only relevant for jsonb, array, and range columns. Match only rows where `column` contains every element appearing in `value`.",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The jsonb, array, or range column to filter on."
},
{
"name": "value",
"isOptional": false,
"type": "Object",
"description": "The jsonb, array, or range value to filter with."
}
],
"examples": [
{
"id": "on-array-columns",
"name": "On array columns",
"description": "Only relevant for jsonb, array, and range columns. Match only rows where `column` contains every element appearing in `value`.\n",
"isSpotlight": true,
"code": "```dart\nfinal data = await supabase\n .from('issues')\n .select()\n .contains('tags', ['is:open', 'priority:low']);\n```\n",
"data": {
"sql": "```sql\ncreate table\n issues (\n id int8 primary key,\n title text,\n tags text[]\n );\n\ninsert into\n issues (id, title, tags)\nvalues\n (1, 'Cache invalidation is not working', array['is:open', 'severity:high', 'priority:low']),\n (2, 'Use better names', array['is:open', 'severity:low', 'priority:medium']);\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'title': 'Cache invalidation is not working',\n 'tags': ['is:open', 'severity:high', 'priority:low']\n },\n]\n```\n",
"hideCodeBlock": true
},
{
"id": "on-range-columns",
"name": "On range columns",
"code": "```dart\nfinal data = await supabase\n .from('reservations')\n .select()\n .contains('during', '[2000-01-01 13:00, 2000-01-01 13:30)');\n```\n",
"data": {
"sql": "```sql\ncreate table\n reservations (\n id int8 primary key,\n room_name text,\n during tsrange\n );\n\ninsert into\n reservations (id, room_name, during)\nvalues\n (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),\n (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'room_name': 'Emerald',\n 'during': '[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")'\n },\n]\n```\n",
"description": "Postgres supports a number of [range\ntypes](https://www.postgresql.org/docs/current/rangetypes.html). You\ncan filter on range columns using the string representation of range\nvalues.\n",
"hideCodeBlock": true
},
{
"id": "on-jsonb-columns",
"name": "On `jsonb` columns",
"code": "```dart\nfinal data = await supabase\n .from('users')\n .select('name')\n .contains('address', { 'street': 'Melrose Place' });\n```\n",
"data": {
"sql": "```sql\ncreate table\n users (\n id int8 primary key,\n name text,\n address jsonb\n );\n\ninsert into\n users (id, name, address)\nvalues\n (1, 'Michael', '{ \"postcode\": 90210, \"street\": \"Melrose Place\" }'),\n (2, 'Jane', '{\"postcode\": 90210}');\n```\n"
},
"response": "```json\n[\n {\n 'name': 'Michael'\n },\n]\n```\n",
"hideCodeBlock": true
}
]
},
{
"id": "using-filters-eq",
"$ref": "supabase_flutter.eq",
"description": "Match only rows where `column` is equal to `value`.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The column to filter on."
},
{
"name": "value",
"isOptional": false,
"type": "Object",
"description": "The value to filter with."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select()\n .eq('name', 'viola');\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```json\n[\n {\n 'id': 2,\n 'name': 'viola'\n },\n]\n```\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-filter",
"$ref": "supabase_flutter.filter",
"description": "Match only rows which satisfy the filter. This is an escape hatch - you should use the specific filter methods wherever possible.\n",
"notes": "`.filter()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values, so it should only be used as an escape hatch in case other filters don't work.\n```dart\n.filter('arraycol','cs','{\"a\",\"b\"}') // Use Postgres array {} and 'cs' for contains.\n.filter('rangecol','cs','(1,2]') // Use Postgres range syntax for range column.\n.filter('id','in','(6,7)') // Use Postgres list () and 'in' for in_ filter.\n.filter('id','cs','{${mylist.join(',')}}') // You can insert a Dart array list.\n```\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The column to filter on."
},
{
"name": "operator",
"isOptional": false,
"type": "String",
"description": "The operator to filter with, following PostgREST syntax."
},
{
"name": "value",
"isOptional": false,
"type": "Object",
"description": "The value to filter with, following PostgREST syntax."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"isSpotlight": true,
"code": "```dart\nfinal data = await supabase\n .from('characters')\n .select()\n .filter('name', 'in', '(\"Ron\",\"Dumbledore\")')\n```\n",
"data": {
"sql": "```sql\ncreate table\n characters (id int8 primary key, name text);\n\ninsert into\n characters (id, name)\nvalues\n (1, 'Harry'),\n (2, 'Hermione'),\n (3, 'Ron');\n```\n"
},
"response": "```json\n[\n {\n 'id': 3,\n 'name': 'Ron'\n }\n]\n```\n"
},
{
"id": "with-update",
"name": "With update()",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .update({ 'name': 'piano' })\n .filter('name', 'in', '(\"harpsichord\",\"clavichord\")');\n```\n"
},
{
"id": "with-delete",
"name": "With delete()",
"code": "```dart\nfinal data = await supabase\n .from('countries')\n .delete()\n .filter('name', 'in', '(\"Rohan\",\"Mordor\")');\n```\n"
},
{
"id": "with-rpc",
"name": "With rpc()",
"code": "```dart\n// Only valid if the database function returns a table type.\nfinal data = await supabase\n .rpc('echo_all_countries')\n .filter('name', 'in', '(\"Rohan\",\"Mordor\")');\n```\n"
},
{
"id": "on-a-referenced-table",
"name": "On a referenced table",
"code": "```dart\nfinal data = await supabase\n .from('orchestral_sections')\n .select('''\n name,\n instruments!inner (\n name\n )\n ''')\n .filter('characters.name', 'eq', 'flute')\n```\n",
"data": {
"sql": "```sql\ncreate table\n orchestral_sections (id int8 primary key, name text);\ncreate table\n instruments (\n id int8 primary key,\n section_id int8 not null references orchestral_sections,\n name text\n );\n\ninsert into\n orchestral_sections (id, name)\nvalues\n (1, 'strings'),\n (2, 'woodwinds');\ninsert into\n instruments (id, section_id, name)\nvalues\n (1, 2, 'flute'),\n (2, 1, 'violin');\n```\n"
},
"response": "```json\n[\n {\n 'name': 'woodwinds',\n 'instruments': [\n {\n 'name': 'flute'\n }\n ]\n }\n]\n```\n",
"hideCodeBlock": true
}
]
},
{
"id": "using-filters-gt",
"$ref": "supabase_flutter.gt",
"description": "Finds all rows whose value on the stated `column` is greater than the specified `value`.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The column to filter on."
},
{
"name": "value",
"isOptional": false,
"type": "Object",
"description": "The value to filter with."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('countries')\n .select()\n .gt('id', 2);\n```\n",
"data": {
"sql": "```sql\ncreate table\n countries (id int8 primary key, name text);\n\ninsert into\n countries (id, name)\nvalues\n (1, 'Rohan'),\n (2, 'The Shire'),\n (3, 'Mordor');\n```\n"
},
"response": "```json\n[\n {\n 'id': 3,\n 'name': 'Mordor'\n },\n]\n```\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-gte",
"$ref": "supabase_flutter.gte",
"description": "Finds all rows whose value on the stated `column` is greater than or equal to the specified `value`.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The column to filter on."
},
{
"name": "value",
"isOptional": false,
"type": "Object",
"description": "The value to filter with."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('countries')\n .select()\n .gte('id', 2);\n```\n",
"data": {
"sql": "```sql\ncreate table\n countries (id int8 primary key, name text);\n\ninsert into\n countries (id, name)\nvalues\n (1, 'Rohan'),\n (2, 'The Shire'),\n (3, 'Mordor');\n```\n"
},
"response": "```json\n[\n {\n 'id': 2,\n 'name': 'The Shire'\n },\n {\n 'id': 3,\n 'name': 'Mordor'\n },\n]\n```\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-ilike",
"$ref": "supabase_flutter.ilike",
"description": "Finds all rows whose value in the stated `column` matches the supplied `pattern` (case insensitive).\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The column to filter on."
},
{
"name": "pattern",
"isOptional": false,
"type": "String",
"description": "The pattern to match with."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('planets')\n .select()\n .ilike('name', '%ea%');\n```\n",
"data": {
"sql": "```sql\ncreate table\n planets (id int8 primary key, name text);\n\ninsert into\n planets (id, name)\nvalues\n (1, 'Mercury'),\n (2, 'Earth'),\n (3, 'Mars');\n```\n"
},
"response": "```json\n[\n {\n 'id': 2,\n 'name': 'Earth'\n },\n]\n```\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-infilter",
"$ref": "supabase_flutter.inFilter",
"description": "Finds all rows whose value on the stated `column` is found on the specified `values`.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The column to filter on."
},
{
"name": "values",
"isOptional": false,
"type": "List",
"description": "The List to filter with."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('characters')\n .select()\n .inFilter('name', ['Luke', 'Leia']);\n```\n",
"data": {
"sql": "```sql\ncreate table\n characters (id int8 primary key, name text);\n\ninsert into\n characters (id, name)\nvalues\n (1, 'Han'),\n (2, 'Luke'),\n (3, 'Leia');\n```\n"
},
"response": "```json\n[\n {\n 'id': 2,\n 'name': 'Luke'\n },\n {\n 'id': 3,\n 'name': 'Leia'\n },\n]\n```\n",
"description": "`inFilter()` is equivalent to `in()` in SDKs for other languages. It's named `inFilter()` in Dart to avoid a conflict with the `in` keyword in Dart.\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-isfilter",
"$ref": "supabase_flutter.isFilter",
"description": "A check for exact equality (null, true, false), finds all rows whose value on the stated `column` exactly match the specified `value`.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The column to filter on."
},
{
"name": "value",
"isOptional": false,
"type": "Object?",
"description": "The value to filter with."
}
],
"examples": [
{
"id": "checking-nullness",
"name": "Checking for nullness, true or false",
"code": "```dart\nfinal data = await supabase\n .from('countries')\n .select()\n .isFilter('name', null);\n```\n",
"data": {
"sql": "```sql\ncreate table\n countries (id int8 primary key, name text);\n\ninsert into\n countries (id, name)\nvalues\n (1, 'null'),\n (2, null);\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'name': 'null'\n },\n]\n```\n",
"description": "Using the `eq()` filter doesn't work when filtering for `null`.\n\nInstead, you need to use `isFilter()`.\n\n`isFilter()` is equivalent to `is()` in SDKs for other languages. It's named `isFilter()` in Dart to avoid a conflict with the `is` keyword in Dart.\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-like",
"$ref": "supabase_flutter.like",
"description": "Finds all rows whose value in the stated `column` matches the supplied `pattern` (case sensitive).\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The column to filter on."
},
{
"name": "pattern",
"isOptional": false,
"type": "String",
"description": "The pattern to match with."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('planets')\n .select()\n .like('name', '%Ea%');\n```\n",
"data": {
"sql": "```sql\ncreate table\n planets (id int8 primary key, name text);\n\ninsert into\n planets (id, name)\nvalues\n (1, 'Mercury'),\n (2, 'Earth'),\n (3, 'Mars');\n```\n"
},
"response": "```json\n[\n {\n 'id': 2,\n 'name': 'Earth'\n },\n]\n```\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-lt",
"$ref": "supabase_flutter.lt",
"description": "Finds all rows whose value on the stated `column` is less than the specified `value`.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The column to filter on."
},
{
"name": "value",
"isOptional": false,
"type": "Object",
"description": "The value to filter with."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('countries')\n .select()\n .lt('id', 2);\n```\n",
"data": {
"sql": "```sql\ncreate table\n countries (id int8 primary key, name text);\n\ninsert into\n countries (id, name)\nvalues\n (1, 'Rohan'),\n (2, 'The Shire'),\n (3, 'Mordor');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'name': 'Rohan'\n },\n]\n```\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-lte",
"$ref": "supabase_flutter.lte",
"description": "Finds all rows whose value on the stated `column` is less than or equal to the specified `value`.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The column to filter on."
},
{
"name": "value",
"isOptional": false,
"type": "Object",
"description": "The value to filter with."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('countries')\n .select()\n .lte('id', 2);\n```\n",
"data": {
"sql": "```sql\ncreate table\n countries (id int8 primary key, name text);\n\ninsert into\n countries (id, name)\nvalues\n (1, 'Rohan'),\n (2, 'The Shire'),\n (3, 'Mordor');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'name': 'Rohan'\n },\n {\n 'id': 2,\n 'name': 'The Shire'\n },\n]\n```\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-match",
"$ref": "supabase_flutter.match",
"description": "Finds all rows whose columns match the specified `query` object.\n",
"params": [
{
"name": "query",
"isOptional": false,
"type": "Map<String, dynamic>",
"description": "The object to filter with, with column names as keys mapped to their filter values"
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select()\n .match({ 'id': 2, 'name': 'viola' });\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```json\n[\n {\n 'name': 'viola'\n }\n]\n```\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-neq",
"$ref": "supabase_flutter.neq",
"description": "Finds all rows whose value on the stated `column` doesn't match the specified `value`.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The column to filter on."
},
{
"name": "value",
"isOptional": false,
"type": "Object",
"description": "The value to filter with."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select('id, name')\n .neq('name', 'viola');\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'name': 'violin'\n },\n {\n 'id': 3,\n 'name': 'cello'\n },\n]\n```\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-not",
"$ref": "supabase_flutter.not",
"description": "Finds all rows which doesn't satisfy the filter.\n",
"notes": "- `.not()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values.\n\n ```dart\n .not('name','eq','violin')\n .not('arraycol','cs','{\"a\",\"b\"}') // Use Postgres array {} for array column and 'cs' for contains.\n .not('rangecol','cs','(1,2]') // Use Postgres range syntax for range column.\n .not('id','in','(6,7)') // Use Postgres list () and 'in' instead of `inFilter`.\n .not('id','in','(${mylist.join(',')})') // You can insert a Dart list array.\n ```\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The column to filter on."
},
{
"name": "operator",
"isOptional": false,
"type": "String",
"description": "The operator to be negated to filter with, following PostgREST syntax."
},
{
"name": "value",
"isOptional": true,
"type": "Object",
"description": "The value to filter with, following PostgREST syntax."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"isSpotlight": false,
"code": "```dart\nfinal data = await supabase\n .from('countries')\n .select()\n .not('name', 'is', null)\n```\n",
"data": {
"sql": "```sql\ncreate table\n countries (id int8 primary key, name text);\n\ninsert into\n countries (id, name)\nvalues\n (1, 'null'),\n (2, null);\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'name': 'null'\n }\n]\n```\n"
},
{
"id": "with-update",
"name": "With update()",
"code": "```dart\nfinal data = await supabase\n .from('cities')\n .update({ 'name': 'Mordor' })\n .not('name', 'eq', 'Rohan');\n```\n"
},
{
"id": "with-delete",
"name": "With delete()",
"code": "```dart\nfinal data = await supabase\n .from('cities')\n .delete()\n .not('name', 'eq', 'Mordor');\n```\n"
},
{
"id": "with-rpc",
"name": "With rpc()",
"code": "```dart\n// Only valid if the database function returns a table type.\nfinal data = await supabase\n .rpc('echo_all_cities')\n .not('name', 'eq', 'Mordor');\n```\n"
}
]
},
{
"id": "using-filters-or",
"$ref": "supabase_flutter.or",
"description": "Finds all rows satisfying at least one of the filters.\n",
"notes": "- `.or()` expects you to use the raw [PostgREST syntax](https://postgrest.org/en/stable/api.html#horizontal-filtering-rows) for the filter names and values.\n\n ```dart\n .or('id.in.(6,7),arraycol.cs.{\"a\",\"b\"}') // Use Postgres list () and 'in' instead of `inFilter`. Array {} and 'cs' for contains.\n .or('id.in.(${mylist.join(',')}),arraycol.cs.{${mylistArray.join(',')}}')\t// You can insert a Dart list for list or array column.\n .or('id.in.(${mylist.join(',')}),rangecol.cs.(${mylistRange.join(',')}]')\t// You can insert a Dart list for list or range column.\n ```\n",
"params": [
{
"name": "filters",
"isOptional": false,
"type": "String",
"description": "The filters to use, following PostgREST syntax"
},
{
"name": "referencedTable",
"isOptional": true,
"type": "String",
"description": "Set this to filter on referenced tables instead of the parent table"
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"isSpotlight": true,
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select('name')\n .or('id.eq.2,name.eq.cello');\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```json\n[\n {\n 'name': 'viola'\n },\n {\n 'name': 'cello'\n }\n]\n```\n"
},
{
"id": "use-or-with-and",
"name": "Use `or` with `and`",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select('name')\n .or('id.gt.3,and(id.eq.1,name.eq.violin)');\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```json\n[\n {\n 'name': 'violin'\n }\n]\n```\n"
},
{
"id": "use-or-on-referenced-tables",
"name": "Use `or` on referenced tables",
"code": "```dart\nfinal data = await supabase\n .from('orchestral_sections')\n .select('''\n name,\n instruments!inner (\n name\n )\n ''')\n .or('section_id.eq.1,name.eq.guzheng', referencedTable: 'instruments' );\n```\n",
"data": {
"sql": "```sql\ncreate table\n orchestral_sections (id int8 primary key, name text);\ncreate table\n instruments (\n id int8 primary key,\n section_id int8 not null references orchestral_sections,\n name text\n );\n\ninsert into\n orchestral_sections (id, name)\nvalues\n (1, 'strings'),\n (2, 'woodwinds');\ninsert into\n instruments (id, book_id, name)\nvalues\n (1, 2, 'flute'),\n (2, 1, 'violin');\n```\n"
},
"response": "```json\n[\n {\n 'name': 'strings',\n 'instruments': [\n {\n 'name': 'violin'\n }\n ]\n }\n]\n```\n",
"hideCodeBlock": true
}
]
},
{
"id": "using-filters-overlaps",
"$ref": "supabase_flutter.overlaps",
"description": "Only relevant for array and range columns. Match only rows where `column` and `value` have an element in common.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The array or range column to filter on."
},
{
"name": "value",
"isOptional": false,
"type": "Object",
"description": "The array or range value to filter with."
}
],
"examples": [
{
"id": "on-array-columns",
"name": "On array columns",
"code": "```dart\nfinal data = await supabase\n .from('issues')\n .select('title')\n .overlaps('tags', ['is:closed', 'severity:high']);\n```\n",
"data": {
"sql": "```sql\ncreate table\n issues (\n id int8 primary key,\n title text,\n tags text[]\n );\n\ninsert into\n issues (id, title, tags)\nvalues\n (1, 'Cache invalidation is not working', array['is:open', 'severity:high', 'priority:low']),\n (2, 'Use better names', array['is:open', 'severity:low', 'priority:medium']);\n```\n"
},
"response": "```json\n[\n {\n 'title': 'Cache invalidation is not working'\n },\n]\n```\n",
"hideCodeBlock": true,
"isSpotlight": true
},
{
"id": "on-range-columns",
"name": "On range columns",
"code": "```dart\nfinal data = await supabase\n .from('reservations')\n .select()\n .overlaps('during', '[2000-01-01 12:45, 2000-01-01 13:15)');\n```\n",
"data": {
"sql": "```sql\ncreate table\n reservations (\n id int8 primary key,\n room_name text,\n during tsrange\n );\n\ninsert into\n reservations (id, room_name, during)\nvalues\n (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),\n (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'room_name': 'Emerald',\n 'during': '[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")'\n },\n]\n```\n",
"description": "Postgres supports a number of [range\ntypes](https://www.postgresql.org/docs/current/rangetypes.html). You\ncan filter on range columns using the string representation of range\nvalues.\n",
"hideCodeBlock": true
}
]
},
{
"id": "using-filters-rangeadjacent",
"$ref": "supabase_flutter.rangeAdjacent",
"description": "Only relevant for range columns. Match only rows where `column` is mutually exclusive to `range` and there can be no element between the two ranges.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The range column to filter on."
},
{
"name": "range",
"isOptional": false,
"type": "String",
"description": "The range to filter with."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('reservations')\n .select()\n .rangeAdjacent('during', '[2000-01-01 12:00, 2000-01-01 13:00)');\n```\n",
"data": {
"sql": "```sql\ncreate table\n reservations (\n id int8 primary key,\n room_name text,\n during tsrange\n );\n\ninsert into\n reservations (id, room_name, during)\nvalues\n (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),\n (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'room_name': 'Emerald',\n 'during': '[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")'\n },\n]\n```\n",
"description": "Postgres supports a number of [range\ntypes](https://www.postgresql.org/docs/current/rangetypes.html). You\ncan filter on range columns using the string representation of range\nvalues.\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-rangegt",
"$ref": "supabase_flutter.rangeGt",
"description": "Only relevant for range columns. Match only rows where every element in `column` is greater than any element in `range`.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The range column to filter on."
},
{
"name": "range",
"isOptional": false,
"type": "String",
"description": "The range to filter with."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('reservations')\n .select()\n .rangeGt('during', '[2000-01-02 08:00, 2000-01-02 09:00)');\n```\n",
"data": {
"sql": "```sql\ncreate table\n reservations (\n id int8 primary key,\n room_name text,\n during tsrange\n );\n\ninsert into\n reservations (id, room_name, during)\nvalues\n (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),\n (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');\n```\n"
},
"response": "```json\n[\n {\n 'id': 2,\n 'room_name': 'Topaz',\n 'during': '[\"2000-01-02 09:00:00\",\"2000-01-02 10:00:00\")'\n }\n]\n```\n",
"description": "Postgres supports a number of [range\ntypes](https://www.postgresql.org/docs/current/rangetypes.html). You\ncan filter on range columns using the string representation of range\nvalues.\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-rangegte",
"$ref": "supabase_flutter.rangeGte",
"description": "Only relevant for range columns. Match only rows where every element in `column` is either contained in `range` or greater than any element in `range`.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The range column to filter on."
},
{
"name": "range",
"isOptional": false,
"type": "String",
"description": "The range to filter with."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('reservations')\n .select()\n .rangeGte('during', '[2000-01-02 08:30, 2000-01-02 09:30)');\n```\n",
"data": {
"sql": "```sql\ncreate table\n reservations (\n id int8 primary key,\n room_name text,\n during tsrange\n );\n\ninsert into\n reservations (id, room_name, during)\nvalues\n (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),\n (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');\n```\n"
},
"response": "```json\n[\n {\n 'id': 2,\n 'room_name': 'Topaz',\n 'during': '[\"2000-01-02 09:00:00\",\"2000-01-02 10:00:00\")''\n },\n]\n```\n",
"description": "Postgres supports a number of [range\ntypes](https://www.postgresql.org/docs/current/rangetypes.html). You\ncan filter on range columns using the string representation of range\nvalues.\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-rangelt",
"$ref": "supabase_flutter.rangeLt",
"description": "Only relevant for range columns. Match only rows where every element in `column` is less than any element in `range`.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The range column to filter on."
},
{
"name": "range",
"isOptional": false,
"type": "String",
"description": "The range to filter with."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('reservations')\n .select()\n .rangeLt('during', '[2000-01-01 15:00, 2000-01-01 16:00)');\n```\n",
"data": {
"sql": "```sql\ncreate table\n reservations (\n id int8 primary key,\n room_name text,\n during tsrange\n );\n\ninsert into\n reservations (id, room_name, during)\nvalues\n (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),\n (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'room_name': 'Emerald',\n 'during': '[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")'\n },\n]\n```\n",
"description": "Postgres supports a number of [range\ntypes](https://www.postgresql.org/docs/current/rangetypes.html). You\ncan filter on range columns using the string representation of range\nvalues.\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-rangelte",
"$ref": "supabase_flutter.rangeLte",
"description": "Only relevant for range columns. Match only rows where every element in `column` is either contained in `range` or less than any element in `range`.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The range column to filter on."
},
{
"name": "range",
"isOptional": false,
"type": "String",
"description": "The range to filter with."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('reservations')\n .select()\n .rangeLte('during', '[2000-01-01 15:00, 2000-01-01 16:00)');\n```\n",
"data": {
"sql": "```sql\ncreate table\n reservations (\n id int8 primary key,\n room_name text,\n during tsrange\n );\n\ninsert into\n reservations (id, room_name, during)\nvalues\n (1, 'Emerald', '[2000-01-01 13:00, 2000-01-01 15:00)'),\n (2, 'Topaz', '[2000-01-02 09:00, 2000-01-02 10:00)');\n```\n"
},
"response": "```json\n[\n {\n 'id': 1,\n 'room_name': 'Emerald',\n 'during': '[\"2000-01-01 13:00:00\",\"2000-01-01 15:00:00\")'\n },\n]\n```\n",
"description": "Postgres supports a number of [range\ntypes](https://www.postgresql.org/docs/current/rangetypes.html). You\ncan filter on range columns using the string representation of range\nvalues.\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-filters-textsearch",
"$ref": "supabase_flutter.textSearch",
"description": "Finds all rows whose tsvector value on the stated `column` matches to_tsquery(query).\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The text or tsvector column to filter on."
},
{
"name": "query",
"isOptional": false,
"type": "String",
"description": "The query text to match with."
},
{
"name": "config",
"isOptional": true,
"type": "String",
"description": "The text search configuration to use."
},
{
"name": "type",
"isOptional": true,
"type": "TextSearchType",
"description": "Change how the `query` text is interpreted."
}
],
"examples": [
{
"id": "text-search",
"name": "Text search",
"code": "```dart\nfinal data = await supabase\n .from('quotes')\n .select('catchphrase')\n .textSearch('content', \"'eggs' & 'ham'\",\n config: 'english'\n );\n```\n",
"data": {
"sql": "```sql\ncreate table texts (\n id bigint\n primary key\n generated always as identity,\n content text\n);\n\ninsert into texts (content) values\n ('Four score and seven years ago'),\n ('The road goes ever on and on'),\n ('Green eggs and ham')\n;\n```\n"
},
"response": "```json\n[\n {\n 'content': 'Green eggs and ham'\n }\n]\n```\n"
},
{
"id": "basic-normalization",
"name": "Basic normalization",
"description": "Uses PostgreSQL's `plainto_tsquery` function.",
"code": "```dart\nfinal data = await supabase\n .from('quotes')\n .select('catchphrase')\n .textSearch('catchphrase', \"'fat' & 'cat'\",\n type: TextSearchType.plain,\n config: 'english'\n );\n```\n"
},
{
"id": "full-normalization",
"name": "Full normalization",
"description": "Uses PostgreSQL's `phraseto_tsquery` function.",
"code": "```dart\nfinal data = await supabase\n .from('quotes')\n .select('catchphrase')\n .textSearch('catchphrase', \"'fat' & 'cat'\",\n type: TextSearchType.phrase,\n config: 'english'\n );\n```\n"
},
{
"id": "web-search",
"name": "Websearch",
"description": "Uses PostgreSQL's `websearch_to_tsquery` function.\nThis function will never raise syntax errors, which makes it possible to use raw user-supplied input for search, and can be used\nwith advanced operators.\n\n- `unquoted text`: text not inside quote marks will be converted to terms separated by & operators, as if processed by plainto_tsquery.\n- `\"quoted text\"`: text inside quote marks will be converted to terms separated by `<->` operators, as if processed by phraseto_tsquery.\n- `OR`: the word “or” will be converted to the | operator.\n- `-`: a dash will be converted to the ! operator.\n",
"code": "```dart\nfinal data = await supabase\n .from('quotes')\n .select('catchphrase')\n .textSearch('catchphrase', \"'fat or cat'\",\n type: TextSearchType.websearch,\n config: 'english'\n );\n```\n"
}
]
},
{
"id": "using-modifiers",
"title": "Using modifiers",
"description": "Filters work on the row level. That is, they allow you to return rows that\nonly match certain conditions without changing the shape of the rows.\nModifiers are everything that don't fit that definition—allowing you to\nchange the format of the response (e.g., returning a CSV string).\n\nModifiers must be specified after filters. Some modifiers only apply for\nqueries that return rows (e.g., `select()` or `rpc()` on a function that\nreturns a table response).\n"
},
{
"id": "using-modifiers-csv",
"$ref": "supabase_flutter.csv",
"examples": [
{
"id": "return-data-as-csv",
"name": "Return data as CSV",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select()\n .csv();\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```json\n'id,name\\n1,violin\\n2,viola\\n3,cello'\n```\n",
"description": "By default, the data is returned in JSON format, but can also be returned as Comma Separated Values.\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-modifiers-explain",
"$ref": "supabase_flutter.explain",
"description": "For debugging slow queries, you can get the [Postgres `EXPLAIN` execution plan](https://www.postgresql.org/docs/current/sql-explain.html) of a query\nusing the `explain()` method. This works on any query, even for `rpc()` or writes.\n\nExplain is not enabled by default as it can reveal sensitive information about your database.\nIt's best to only enable this for testing environments but if you wish to enable it for production you can provide additional protection by using a `pre-request` function.\n\nFollow the [Performance Debugging Guide](/docs/guides/database/debugging-performance) to enable the functionality on your project.\n",
"params": [
{
"name": "analyze",
"isOptional": true,
"type": "bool",
"description": "If `true`, the query will be executed and the actual run time will be returned."
},
{
"name": "verbose",
"isOptional": true,
"type": "bool",
"description": "If `true`, the query identifier will be returned and `data` will include the output columns of the query."
},
{
"name": "settings",
"isOptional": true,
"type": "bool",
"description": "If `true`, include information on configuration parameters that affect query planning."
},
{
"name": "buffers",
"isOptional": true,
"type": "bool",
"description": "If `true`, include information on buffer usage."
},
{
"name": "wal",
"isOptional": true,
"type": "bool",
"description": "If `true`, include information on WAL record generation."
}
],
"examples": [
{
"id": "get-execution-plan",
"name": "Get the execution plan",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select()\n .explain();\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```\nAggregate (cost=33.34..33.36 rows=1 width=112)\n -> Limit (cost=0.00..18.33 rows=1000 width=40)\n -> Seq Scan on instruments (cost=0.00..22.00 rows=1200 width=40)\n```\n",
"description": "By default, the data is returned in TEXT format, but can also be returned as JSON by using the `format` parameter.\n",
"hideCodeBlock": true,
"isSpotlight": true
},
{
"id": "get-execution-plan-with-analyze-and-verbose",
"name": "Get the execution plan with analyze and verbose",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select()\n .explain(analyze:true, verbose:true);\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```\nAggregate (cost=33.34..33.36 rows=1 width=112) (actual time=0.041..0.041 rows=1 loops=1)\n Output: NULL::bigint, count(ROW(instruments.id, instruments.name)), COALESCE(json_agg(ROW(instruments.id, instruments.name)), '[]'::json), NULLIF(current_setting('response.headers'::text, true), ''::text), NULLIF(current_setting('response.status'::text, true), ''::text)\n -> Limit (cost=0.00..18.33 rows=1000 width=40) (actual time=0.005..0.006 rows=3 loops=1)\n Output: instruments.id, instruments.name\n -> Seq Scan on public.instruments (cost=0.00..22.00 rows=1200 width=40) (actual time=0.004..0.005 rows=3 loops=1)\n Output: instruments.id, instruments.name\nQuery Identifier: -4730654291623321173\nPlanning Time: 0.407 ms\nExecution Time: 0.119 ms\n```\n",
"description": "By default, the data is returned in TEXT format, but can also be returned as JSON by using the `format` parameter.\n",
"hideCodeBlock": true,
"isSpotlight": false
}
]
},
{
"id": "using-modifiers-limit",
"$ref": "supabase_flutter.limit",
"description": "Limits the result with the specified count.\n",
"params": [
{
"name": "count",
"isOptional": false,
"type": "int",
"description": "The maximum number of rows to return."
},
{
"name": "referencedTable",
"isOptional": true,
"type": "int",
"description": "Set this to limit rows of referenced tables instead of the parent table."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"isSpotlight": true,
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select('name')\n .limit(1);\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```json\n[\n {\n 'name': 'violin'\n }\n]\n```\n"
},
{
"id": "on-a-referenced-table",
"name": "On a referenced table",
"code": "```dart\nfinal data = await supabase\n .from('orchestral_sections')\n .select('''\n name,\n instruments (\n name\n )\n ''')\n .limit(1, referencedTable: 'instruments');\n```\n",
"data": {
"sql": "```sql\ncreate table\n orchestral_sections (id int8 primary key, name text);\ncreate table\n instruments (\n id int8 primary key,\n section_id int8 not null references orchestral_sections,\n name text\n );\n\ninsert into\n orchestral_sections (id, name)\nvalues\n (1, 'strings');\ninsert into\n instruments (id, section_id, name)\nvalues\n (1, 1, 'violin'),\n (2, 1, 'viola');\n```\n"
},
"response": "```json\n[\n {\n 'name': 'strings',\n 'instruments': [\n {\n 'name': 'violin'\n }\n ]\n }\n]\n```\n"
}
]
},
{
"id": "using-modifiers-maxaffected",
"$ref": "supabase_flutter.maxAffected",
"description": "Sets the maximum number of rows that can be affected by the query. Only effective with PATCH and DELETE operations. Requires PostgREST v13 or higher.\n\nWhen the limit is exceeded, the query will fail with an error. This provides a safety mechanism to prevent accidentally affecting more rows than intended.\n",
"notes": "- This method is only effective with UPDATE and DELETE operations.\n- Requires PostgREST v13 or higher on your Supabase instance.\n- If the number of affected rows exceeds the limit, the query will fail and no rows will be modified.\n",
"params": [
{
"name": "count",
"isOptional": false,
"type": "int",
"description": "The maximum number of rows that can be affected by the query."
}
],
"examples": [
{
"id": "with-update",
"name": "With update()",
"isSpotlight": true,
"code": "```dart\nawait supabase\n .from('users')\n .update({'active': false})\n .eq('status', 'inactive')\n .maxAffected(5);\n```\n",
"description": "Limit the number of rows that can be updated. If more than 5 rows match the filter, the operation will fail.\n"
},
{
"id": "with-delete",
"name": "With delete()",
"code": "```dart\nawait supabase\n .from('users')\n .delete()\n .eq('active', false)\n .maxAffected(10);\n```\n",
"description": "Limit the number of rows that can be deleted. If more than 10 rows match the filter, the operation will fail.\n"
},
{
"id": "with-select",
"name": "With select()",
"code": "```dart\nfinal data = await supabase\n .from('users')\n .update({'status': 'INACTIVE'})\n .eq('id', 1)\n .maxAffected(1)\n .select();\n```\n",
"description": "Combine maxAffected with select() to limit affected rows and return the updated data.\n"
}
]
},
{
"id": "using-modifiers-maybesingle",
"$ref": "supabase_flutter.maybeSingle",
"examples": [
{
"id": "with-select",
"name": "With `select()`",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select()\n .eq('name', 'guzheng')\n .maybeSingle();\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```json\nnull\n```\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-modifiers-order",
"$ref": "supabase_flutter.order",
"description": "Orders the result with the specified column.\n",
"params": [
{
"name": "column",
"isOptional": false,
"type": "String",
"description": "The column to order by."
},
{
"name": "ascending",
"isOptional": true,
"type": "bool",
"description": "Whether to order in ascending order. Default is `false`."
},
{
"name": "nullsFirst",
"isOptional": true,
"type": "bool",
"description": "Whether to order nulls first. Default is `false`."
},
{
"name": "referencedTable",
"isOptional": true,
"type": "String",
"description": "Specify the referenced table when ordering by a column in an embedded resource."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"isSpotlight": true,
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select('id, name')\n .order('id', ascending: false);\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```json\n[\n {\n 'id': 3,\n 'name': 'cello'\n },\n {\n 'id': 2,\n 'name': 'viola'\n },\n {\n 'id': 1,\n 'name': 'viola'\n }\n]\n```\n"
},
{
"id": "on-a-referenced-table",
"name": "On a referenced table",
"code": "```dart\nfinal data = await supabase\n .from('orchestral_sections')\n .select('''\n name,\n instruments (\n name\n )\n ''')\n .order('name', referencedTable: 'instruments', ascending: false);\n ```\n",
"data": {
"sql": "```sql\ncreate table\n orchestral_sections (id int8 primary key, name text);\ncreate table\n instruments (\n id int8 primary key,\n section_id int8 not null references orchestral_sections,\n name text\n );\n\ninsert into\n orchestral_sections (id, name)\nvalues\n (1, 'strings'),\n (2, 'woodwinds');\ninsert into\n instruments (id, section_id, name)\nvalues\n (1, 1, 'harp'),\n (2, 1, 'violin');\n```\n"
},
"response": "```json\n[\n {\n 'name': 'strings',\n 'instruments': [\n {\n 'name': 'violin'\n },\n {\n 'name': 'harp'\n }\n ]\n },\n {\n 'name': 'woodwinds',\n 'instruments': []\n }\n]\n```\n"
},
{
"id": "order-parent-table-by-a-referenced-table",
"name": "Order parent table by a referenced table",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select('''\n name,\n section:orchestral_sections (\n name\n )\n ''')\n .order('section(name)', ascending: true)\n```\n",
"data": {
"sql": "```sql\ncreate table\n orchestral_sections (id int8 primary key, name text);\ncreate table\n instruments (\n id int8 primary key,\n section_id int8 not null references orchestral_sections,\n name text\n );\n\ninsert into\n orchestral_sections (id, name)\nvalues\n (1, 'strings'),\n (2, 'woodwinds');\ninsert into\n instruments (id, section_id, name)\nvalues\n (1, 1, 'violin'),\n (2, 2, 'flute');\n```\n"
},
"response": "```json\n[\n {\n \"name\": \"violin\",\n \"orchestral_sections\": { \"name\": \"strings\" }\n },\n {\n \"name\": \"flute\",\n \"orchestral_sections\": { \"name\": \"woodwinds\" }\n }\n]\n```\n"
}
]
},
{
"id": "using-modifiers-range",
"$ref": "supabase_flutter.range",
"description": "Limits the result to rows within the specified range, inclusive.\n",
"params": [
{
"name": "from",
"isOptional": false,
"type": "int",
"description": "The starting index from which to limit the result."
},
{
"name": "to",
"isOptional": false,
"type": "int",
"description": "The last index to which to limit the result."
},
{
"name": "referencedTable",
"isOptional": true,
"type": "String",
"description": "Set this to limit rows of referenced tables instead of the parent table."
}
],
"examples": [
{
"id": "with-select",
"name": "With select()",
"isSpotlight": true,
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select('name')\n .range(0, 1);\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```json\n[\n {\n 'name': 'violin'\n },\n {\n 'name': 'viola'\n }\n]\n```\n"
}
]
},
{
"id": "using-modifiers-select",
"$ref": "supabase_flutter.select",
"examples": [
{
"id": "with-upsert",
"name": "With `upsert()`",
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .upsert({ 'id': 1, 'name': 'piano' })\n .select();\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'harpsichord');\n```\n"
},
"response": "```json\n[\n {\n \"id\": 1,\n \"name\": \"piano\"\n }\n]\n```\n",
"hideCodeBlock": true,
"isSpotlight": true
}
]
},
{
"id": "using-modifiers-single",
"$ref": "supabase_flutter.single",
"description": "Retrieves only one row from the result. Result must be one row (e.g. using limit), otherwise this will result in an error.\n",
"examples": [
{
"id": "with-select",
"name": "With select()",
"isSpotlight": true,
"code": "```dart\nfinal data = await supabase\n .from('instruments')\n .select('name')\n .limit(1)\n .single();\n```\n",
"data": {
"sql": "```sql\ncreate table\n instruments (id int8 primary key, name text);\n\ninsert into\n instruments (id, name)\nvalues\n (1, 'violin'),\n (2, 'viola'),\n (3, 'cello');\n```\n"
},
"response": "```json\n{\n 'name': 'violin'\n}\n```\n"
}
]
},
{
"id": "auth-currentsession",
"$ref": "supabase_flutter.currentSession",
"description": "Returns the session data, if there is an active session.\n",
"examples": [
{
"id": "get-the-session-data",
"name": "Get the session data",
"isSpotlight": true,
"code": "```dart\nfinal Session? session = supabase.auth.currentSession;\n```\n",
"response": "```json\nSession(\n accessToken: '<ACCESS_TOKEN>',\n tokenType: 'bearer',\n expiresIn: 3600,\n refreshToken: '<REFRESH_TOKEN>',\n user: User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n);\n```\n"
}
]
},
{
"id": "auth-currentuser",
"$ref": "supabase_flutter.currentUser",
"description": "Returns the user data, if there is a logged in user.\n",
"examples": [
{
"name": "Get the logged in user",
"isSpotlight": true,
"code": "```dart\nfinal User? user = supabase.auth.currentUser;\n```\n",
"response": "```json\nUser(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n);\n```\n"
}
]
},
{
"id": "auth-getuseridentities",
"$ref": "supabase_flutter.getUserIdentities",
"description": "Gets all the identities linked to a user.\n",
"notes": "- The user needs to be signed in to call `getUserIdentities()`.\n",
"examples": [
{
"id": "get-user-identities",
"name": "Returns a list of identities linked to the user",
"isSpotlight": true,
"code": "```dart\nfinal identities = await supabase.auth.getUserIdentities();\n```\n",
"response": "```json\n[\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '2024-01-01T00:00:00Z',\n userId: '2024-01-01T00:00:00Z',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n];\n```\n"
}
]
},
{
"id": "auth-linkidentity",
"$ref": "supabase_flutter.linkIdentity",
"description": "Links an oauth identity to an existing user. This method supports the PKCE flow.\n",
"notes": "- The **Enable Manual Linking** option must be enabled from your [project's authentication settings](/dashboard/project/_/auth/providers).\n- The user needs to be signed in to call `linkIdentity()`.\n- If the candidate identity is already linked to the existing user or another user, `linkIdentity()` will fail.\n",
"params": [
{
"name": "provider",
"isOptional": false,
"type": "OAuthProvider",
"description": "The provider to link the identity to."
},
{
"name": "redirectTo",
"isOptional": true,
"type": "String",
"description": "The URL to redirect the user to after they sign in with the third-party provider."
},
{
"name": "scopes",
"isOptional": true,
"type": "String",
"description": "A list of scopes to request from the third-party provider."
},
{
"name": "authScreenLaunchMode",
"isOptional": true,
"type": "LaunchMode",
"description": "The launch mode for the auth screen. Defaults to `LaunchMode.platformDefault`."
},
{
"name": "queryParams",
"isOptional": true,
"type": "Map<String, String>",
"description": "Additional query parameters to be passed to the OAuth flow."
}
],
"examples": [
{
"id": "link-identity",
"name": "Link an identity to a user",
"isSpotlight": true,
"code": "```dart\nawait supabase.auth.linkIdentity(OAuthProvider.google);\n```\n"
}
]
},
{
"id": "auth-linkidentitywithidtoken",
"$ref": "supabase_flutter.linkIdentityWithIdToken",
"description": "Links an identity to an existing user using an ID token obtained from a third-party OAuth provider. This allows linking identities using native OAuth flows (Google, Apple, Facebook, etc.) similar to `signInWithIdToken()` but for linking rather than signing in.\n",
"notes": "- The **Enable Manual Linking** option must be enabled from your [project's authentication settings](/dashboard/project/_/auth/providers).\n- The user needs to be signed in to call `linkIdentityWithIdToken()`.\n- Supports the same OAuth providers as `signInWithIdToken()`: Google, Apple, Facebook, Kakao, and Keycloak.\n- If the candidate identity is already linked to another user, the operation will fail.\n",
"params": [
{
"name": "provider",
"isOptional": false,
"type": "OAuthProvider",
"description": "The OAuth provider to link the identity from."
},
{
"name": "idToken",
"isOptional": false,
"type": "String",
"description": "The identity token obtained from the third-party provider."
},
{
"name": "accessToken",
"isOptional": true,
"type": "String",
"description": "Access token obtained from the third-party provider. Required for Google sign in."
},
{
"name": "nonce",
"isOptional": true,
"type": "String",
"description": "Raw nonce value used to perform the third-party sign in. Required for Apple sign-in."
},
{
"name": "captchaToken",
"isOptional": true,
"type": "String",
"description": "The captcha token to be used for captcha verification."
}
],
"examples": [
{
"id": "link-google-identity",
"name": "Link Google identity",
"isSpotlight": true,
"description": "Link a Google identity to the currently signed-in user using native Google Sign-In.\n",
"code": "```dart\nimport 'package:google_sign_in/google_sign_in.dart';\nimport 'package:supabase_flutter/supabase_flutter.dart';\n\nconst webClientId = '<web client ID>';\nconst iosClientId = '<iOS client ID>';\n\nfinal GoogleSignIn googleSignIn = GoogleSignIn(\n clientId: iosClientId,\n serverClientId: webClientId,\n);\nfinal googleUser = await googleSignIn.signIn();\nfinal googleAuth = await googleUser!.authentication;\nfinal accessToken = googleAuth.accessToken;\nfinal idToken = googleAuth.idToken;\n\nif (accessToken == null) {\n throw 'No Access Token found.';\n}\nif (idToken == null) {\n throw 'No ID Token found.';\n}\n\nfinal response = await supabase.auth.linkIdentityWithIdToken(\n provider: OAuthProvider.google,\n idToken: idToken,\n accessToken: accessToken,\n);\n```\n"
},
{
"id": "link-apple-identity",
"name": "Link Apple identity",
"description": "Link an Apple identity to the currently signed-in user using native Apple Sign In.\n",
"code": "```dart\nimport 'package:sign_in_with_apple/sign_in_with_apple.dart';\nimport 'package:supabase_flutter/supabase_flutter.dart';\nimport 'package:crypto/crypto.dart';\n\nfinal rawNonce = supabase.auth.generateRawNonce();\nfinal hashedNonce = sha256.convert(utf8.encode(rawNonce)).toString();\n\nfinal credential = await SignInWithApple.getAppleIDCredential(\n scopes: [\n AppleIDAuthorizationScopes.email,\n AppleIDAuthorizationScopes.fullName,\n ],\n nonce: hashedNonce,\n);\n\nfinal idToken = credential.identityToken;\nif (idToken == null) {\n throw const AuthException(\n 'Could not find ID Token from generated credential.',\n );\n}\n\nfinal response = await supabase.auth.linkIdentityWithIdToken(\n provider: OAuthProvider.apple,\n idToken: idToken,\n nonce: rawNonce,\n);\n```\n"
}
]
},
{
"id": "auth-onauthstatechange",
"$ref": "supabase_flutter.onAuthStateChange",
"description": "Receive a notification every time an auth event happens.\n",
"notes": "- **You must provide an `onError` handler.** Network errors (e.g. an offline token refresh) are emitted as stream errors. If no `onError` is provided, Dart rethrows them as unhandled zone exceptions, crashing the app.\n- Auth event types: `initialSession`, `signedIn`, `signedOut`, `passwordRecovery`, `tokenRefreshed`, `userUpdated`, `userDeleted`, `mfaChallengeVerified`\n",
"examples": [
{
"id": "listen-to-auth-changes",
"name": "Listen to auth changes",
"isSpotlight": true,
"code": "```dart\nfinal authSubscription = supabase.auth.onAuthStateChange.listen(\n (data) {\n final AuthChangeEvent event = data.event;\n final Session? session = data.session;\n // handle event\n },\n onError: (error, stackTrace) {\n // Network errors (e.g. offline) are emitted here.\n // Handle or log them to avoid an unhandled exception crash.\n },\n);\n```\n"
},
{
"id": "listen-to-a-specific-event",
"name": "Listen to a specific event",
"code": "```dart\nfinal authSubscription = supabase.auth.onAuthStateChange.listen(\n (data) {\n final AuthChangeEvent event = data.event;\n if (event == AuthChangeEvent.signedIn) {\n // handle signIn\n }\n },\n onError: (error, stackTrace) {\n // Handle or log network / auth errors here.\n },\n);\n```\n"
},
{
"id": "unsubscribe-from-auth-subscription",
"name": "Unsubscribe from auth subscription",
"code": "```dart\nfinal authSubscription = supabase.auth.onAuthStateChange.listen(\n (data) {},\n onError: (error, stackTrace) {},\n);\n\nauthSubscription.cancel();\n```\n"
}
]
},
{
"id": "auth-reauthenticate",
"$ref": "supabase_flutter.reauthenticate",
"notes": "- This method is used together with `updateUser()` when a user's password needs to be updated.\n- This method sends a nonce to the user's email. If the user doesn't have a confirmed email address, the method sends the nonce to the user's confirmed phone number instead.\n",
"examples": [
{
"id": "send-reauthentication-nonce",
"name": "Send reauthentication nonce",
"description": "Sends a reauthentication nonce to the user's email or phone number.",
"isSpotlight": true,
"code": "```dart\nawait supabase.auth.reauthenticate();\n```\n"
}
]
},
{
"id": "auth-refreshsession",
"$ref": "supabase_flutter.refreshSession",
"notes": "- This method will refresh and return a new session whether the current one is expired or not.\n",
"examples": [
{
"id": "refresh-session-using-the-current-session",
"name": "Refresh session using the current session",
"isSpotlight": true,
"code": "```dart\nfinal AuthResponse res = await supabase.auth.refreshSession();\nfinal session = res.session;\n```\n",
"response": "```json\nAuthResponse(\n user: User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n session: Session(\n accessToken: '<ACCESS_TOKEN>',\n tokenType: 'bearer',\n expiresIn: 3600,\n refreshToken: '<REFRESH_TOKEN>',\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n ),\n);\n```\n"
}
]
},
{
"id": "auth-registerpasskey",
"$ref": "supabase_flutter.registerPasskey",
"notes": "Registers a new passkey (WebAuthn credential) for the signed in user.\n- Available on `supabase_flutter` 2.15.0 and later as an extension on `GoTrueClient`.\n- Drives the full WebAuthn ceremony end to end: starts the registration with the Supabase server, prompts the user to create a credential on the device, and verifies it with the server.\n- Requires a signed in (non-anonymous) user. If the user has verified MFA factors, the session has to be at `aal2` to manage passkeys.\n- For native flows or custom UI, use the lower-level [`auth.passkey`](/docs/reference/dart/auth-passkey-api) namespace instead.\n- Passkeys are a BETA feature and must be enabled for your project in the Supabase Dashboard under Authentication > Configuration > Passkeys.\n",
"examples": [
{
"id": "register-passkey",
"name": "Register a passkey for the current user",
"isSpotlight": true,
"code": "```dart\nfinal Passkey passkey = await supabase.auth.registerPasskey();\n```\n"
}
]
},
{
"id": "auth-resend",
"$ref": "supabase_flutter.resend",
"notes": "- Resends a signup confirmation, email change, or phone change email to the user.\n- Passwordless sign-ins can be resent by calling the `signInWithOtp()` method again.\n- Password recovery emails can be resent by calling the `resetPasswordForEmail()` method again.\n- This method only resend an email or phone OTP to the user if an initial signup, email change, or phone change request was made.\n",
"examples": [
{
"id": "resend-email-signup-confirmation",
"name": "Resend an email signup confirmation",
"description": "Resends the email signup confirmation to the user",
"isSpotlight": true,
"code": "```dart\nfinal ResendResponse res = await supabase.auth.resend(\n type: OtpType.signup,\n email: 'email@example.com',\n);\n```\n"
}
]
},
{
"id": "auth-resetpasswordforemail",
"$ref": "supabase_flutter.resetPasswordForEmail",
"description": "Sends a reset request to an email address.\n",
"notes": "Sends a password reset request to an email address. When the user clicks the reset link in the email they are redirected back to your application. Prompt the user for a new password and call auth.updateUser():\n\n```dart\nawait supabase.auth.resetPasswordForEmail(\n 'sample@email.com',\n redirectTo: kIsWeb ? null : 'io.supabase.flutter://reset-callback/',\n);\n```\n",
"examples": [
{
"id": "reset-password",
"name": "Reset password for Flutter",
"isSpotlight": true,
"code": "`redirectTo` is used to open the app via deeplink when user opens the password reset email.\n```dart\nawait supabase.auth.resetPasswordForEmail(\n 'sample@email.com',\n redirectTo: kIsWeb ? null : 'io.supabase.flutter://reset-callback/',\n);\n```\n"
}
]
},
{
"id": "auth-setsession",
"$ref": "supabase_flutter.setSession",
"notes": "- `setSession()` takes in a refresh token and uses it to get a new session.\n- The refresh token can only be used once to obtain a new session.\n- [Refresh token rotation](/docs/guides/cli/config#auth.enable_refresh_token_rotation) is enabled by default on all projects to guard against replay attacks.\n- You can configure the [`REFRESH_TOKEN_REUSE_INTERVAL`](/docs/guides/cli/config#auth.refresh_token_reuse_interval) which provides a short window in which the same refresh token can be used multiple times in the event of concurrency or offline issues.\n",
"params": [
{
"name": "refreshToken",
"isOptional": false,
"type": "String",
"description": "Refresh token to use to get a new session."
},
{
"name": "accessToken",
"isOptional": true,
"type": "String",
"description": "Optional access token to set along with the refresh token."
}
],
"examples": [
{
"id": "refresh-the-session",
"name": "Refresh the session",
"description": "Sets the session data from refresh_token and returns current session or an error if the refresh_token is invalid.",
"isSpotlight": true,
"code": "```dart\nfinal refreshToken = supabase.currentSession?.refreshToken ?? '';\nfinal AuthResponse response = await supabase.auth.setSession(refreshToken);\n\nfinal session = res.session;\n```\n"
},
{
"id": "set-session-with-access-token",
"name": "Set session with access token",
"description": "You can optionally provide an access token along with the refresh token.",
"isSpotlight": false,
"code": "```dart\nfinal AuthResponse response = await supabase.auth.setSession(\n refreshToken,\n accessToken: accessToken,\n);\n```\n",
"response": "```json\nAuthResponse(\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n session: Session(\n accessToken: '<ACCESS_TOKEN>',\n tokenType: 'bearer',\n expiresIn: 3600,\n refreshToken: '<REFRESH_TOKEN>',\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n ),\n);\n```\n"
}
]
},
{
"id": "auth-signinanonymously",
"$ref": "supabase_flutter.signInAnonymously",
"description": "Creates an anonymous user.\n",
"notes": "- Returns an anonymous user\n- It is recommended to set up captcha for anonymous sign-ins to prevent abuse. You can pass in the captcha token in the `options` param.\n",
"params": [
{
"name": "data",
"isOptional": true,
"type": "Map<String, dynamic>",
"description": "The user's metadata to be stored in the user's object."
},
{
"name": "captchaToken",
"isOptional": true,
"type": "String",
"description": "The captcha token to be used for captcha verification."
}
],
"examples": [
{
"id": "sign-in-anonymously",
"name": "Create an anonymous user",
"isSpotlight": true,
"code": "```dart\nawait supabase.auth.signInAnonymously();\n```\n",
"response": "```json\nAuthResponse(\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: '',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {},\n userMetadata: {},\n identities: [],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n isAnonymous: true,\n ),\n session: Session(\n accessToken: '<ACCESS_TOKEN>',\n tokenType: 'bearer',\n expiresIn: 3600,\n refreshToken: '<REFRESH_TOKEN>',\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: '',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {},\n userMetadata: {},\n identities: [],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n isAnonymous: true,\n ),\n ),\n);\n```\n"
},
{
"id": "sign-in-anonymously-with-user-metadata",
"name": "Create an anonymous user with custom user metadata",
"isSpotlight": false,
"code": "```dart\nawait supabase.auth.signInAnonymously(\n data: {'hello': 'world'},\n);\n```\n"
}
]
},
{
"id": "auth-signinwithidtoken",
"$ref": "supabase_flutter.signInWithIdToken",
"description": "Allows you to perform native Google, Apple, and Facebook sign in by combining it with [google_sign_in](https://pub.dev/packages/google_sign_in), [sign_in_with_apple](https://pub.dev/packages/sign_in_with_apple), or [flutter_facebook_auth](https://pub.dev/packages/flutter_facebook_auth) packages.\n",
"params": [
{
"name": "provider",
"isOptional": false,
"type": "OAuthProvider",
"description": "The provider to perform the sign in with."
},
{
"name": "idToken",
"isOptional": false,
"type": "String",
"description": "The identity token obtained from the third-party provider."
},
{
"name": "accessToken",
"isOptional": true,
"type": "String",
"description": "Access token obtained from the third-party provider. Required for Google sign in."
},
{
"name": "nonce",
"isOptional": true,
"type": "String",
"description": "Raw nonce value used to perform the third-party sign in. Required for Apple sign-in."
},
{
"name": "captchaToken",
"isOptional": true,
"type": "String",
"description": "The captcha token to be used for captcha verification."
}
],
"examples": [
{
"id": "sign-in-with-google",
"name": "Native Google sign in",
"isSpotlight": true,
"description": "You can perform native Google sign in on Android and iOS using [google_sign_in](https://pub.dev/packages/google_sign_in).\nFor platform specific settings, follow the instructions in the package README.\n\nFirst, create client IDs for your app. You need to create a web client ID as well to perform Google sign-in with Supabase.\n\n- [Steps to obtain web client ID](https://developers.google.com/identity/sign-in/android/start-integrating#configure_a_project)\n- [Steps to obtain Android client ID](https://developers.google.com/identity/sign-in/android/start-integrating#configure_a_project)\n- [Steps to obtain iOS client ID](https://developers.google.com/identity/sign-in/ios/start-integrating#get_an_oauth_client_id)\n\nAdd the web client ID to the `Authentication -> Providers -> Google -> Client IDs` section in your Supabase dashboard\n",
"code": "```dart\nimport 'package:google_sign_in/google_sign_in.dart';\nimport 'package:supabase_flutter/supabase_flutter.dart';\n\nconst webClientId = '<web client ID that you registered on Google Cloud, for example my-web.apps.googleusercontent.com>';\n\nconst iosClientId = '<iOS client ID that you registered on Google Cloud, for example my-ios.apps.googleusercontent.com';\n\nfinal GoogleSignIn googleSignIn = GoogleSignIn(\n clientId: iosClientId,\n serverClientId: webClientId,\n);\nfinal googleUser = await googleSignIn.signIn();\nfinal googleAuth = await googleUser!.authentication;\nfinal accessToken = googleAuth.accessToken;\nfinal idToken = googleAuth.idToken;\n\nif (accessToken == null) {\n throw 'No Access Token found.';\n}\nif (idToken == null) {\n throw 'No ID Token found.';\n}\n\nfinal response = await supabase.auth.signInWithIdToken(\n provider: OAuthProvider.google,\n idToken: idToken,\n accessToken: accessToken,\n);\n```\n",
"response": "```json\nAuthResponse(\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n ...\n },\n userMetadata: {\n ...\n },\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n provider: 'google',\n ...\n ),\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n session: Session(\n accessToken: '<ACCESS_TOKEN>',\n tokenType: 'bearer',\n expiresIn: 3600,\n refreshToken: '<REFRESH_TOKEN>',\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n ...\n },\n userMetadata: {\n ...\n },\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n provider: 'google',\n ...\n )\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n ),\n);\n```\n"
},
{
"id": "sign-in-with-apple",
"name": "Native Apple Sign in",
"description": "You need to [register your app ID with Apple](https://developer.apple.com/help/account/manage-identifiers/register-an-app-id/) with the `Sign In with Apple` capability selected, and add the bundle ID to your Supabase dashboard in `Authentication -> Providers -> Apple` before performing native Apple sign in.",
"code": "```dart\nimport 'package:sign_in_with_apple/sign_in_with_apple.dart';\nimport 'package:supabase_flutter/supabase_flutter.dart';\nimport 'package:crypto/crypto.dart';\n\n/// Performs Apple sign in on iOS or macOS\nfinal rawNonce = supabase.auth.generateRawNonce();\nfinal hashedNonce = sha256.convert(utf8.encode(rawNonce)).toString();\n\nfinal credential = await SignInWithApple.getAppleIDCredential(\n scopes: [\n AppleIDAuthorizationScopes.email,\n AppleIDAuthorizationScopes.fullName,\n ],\n nonce: hashedNonce,\n);\n\nfinal idToken = credential.identityToken;\nif (idToken == null) {\n throw const AuthException(\n 'Could not find ID Token from generated credential.',\n );\n}\n\nfinal response = await supabase.auth.signInWithIdToken(\n provider: OAuthProvider.apple,\n idToken: idToken,\n nonce: rawNonce,\n);\n```\n"
},
{
"id": "sign-in-with-facebook",
"name": "Native Facebook Sign in",
"description": "You can perform native Facebook sign in using [flutter_facebook_auth](https://pub.dev/packages/flutter_facebook_auth).\n\nFirst, set up your Facebook app in the [Facebook Developer Console](https://developers.facebook.com) and configure it in your Supabase dashboard under `Authentication -> Providers -> Facebook`.\n",
"code": "```dart\nimport 'package:flutter_facebook_auth/flutter_facebook_auth.dart';\nimport 'package:supabase_flutter/supabase_flutter.dart';\n\nFuture<void> signInWithFacebook() async {\n final LoginResult result = await FacebookAuth.instance.login(\n permissions: ['public_profile', 'email'],\n );\n\n if (result.status == LoginStatus.success) {\n final accessToken = result.accessToken!.tokenString;\n\n final response = await supabase.auth.signInWithIdToken(\n provider: OAuthProvider.facebook,\n idToken: accessToken,\n );\n } else {\n throw const AuthException(\n 'Facebook login failed: ${result.status}',\n );\n }\n}\n```\n"
}
]
},
{
"id": "auth-signinwithoauth",
"$ref": "supabase_flutter.signInWithOAuth",
"description": "Signs the user in using third-party OAuth providers.\n",
"notes": "- This method is used for signing in using a third-party provider.\n- Supabase supports many different [third-party providers](https://supabase.com/docs/guides/auth#providers).\n",
"params": [
{
"name": "provider",
"isOptional": false,
"type": "OAuthProvider",
"description": "The OAuth provider to use for signing in."
},
{
"name": "redirectTo",
"isOptional": true,
"type": "String",
"description": "The URL to redirect the user to after they sign in with the third-party provider."
},
{
"name": "scopes",
"isOptional": true,
"type": "String",
"description": "A list of scopes to request from the third-party provider."
},
{
"name": "authScreenLaunchMode",
"isOptional": true,
"type": "LaunchMode",
"description": "The launch mode for the auth screen. Defaults to `LaunchMode.platformDefault`."
},
{
"name": "queryParams",
"isOptional": true,
"type": "Map<String, String>",
"description": "Additional query parameters to be passed to the OAuth flow."
}
],
"examples": [
{
"id": "sign-in-using-a-third-party-provider",
"name": "Sign in using a third-party provider",
"isSpotlight": true,
"code": "```dart\nawait supabase.auth.signInWithOAuth(\n OAuthProvider.github,\n redirectTo: kIsWeb ? null : 'my.scheme://my-host', // Optionally set the redirect link to bring back the user via deeplink.\n authScreenLaunchMode:\n kIsWeb ? LaunchMode.platformDefault : LaunchMode.externalApplication, // Launch the auth screen in a new webview on mobile.\n);\n```\n"
},
{
"id": "sign-in-with-custom-provider",
"name": "Sign in with a custom OIDC provider",
"description": "`OAuthProvider` is now a class instead of an enum, allowing you to use custom OIDC providers by passing a custom provider string.\n",
"isSpotlight": false,
"code": "```dart\nawait supabase.auth.signInWithOAuth(\n OAuthProvider('custom:my-oidc-provider'),\n redirectTo: kIsWeb ? null : 'my.scheme://my-host',\n);\n```\n"
},
{
"id": "sign-in-using-a-third-party-provider-with-redirect",
"name": "With `redirectTo`",
"description": "Specify the redirect link to bring back the user via deeplink.\nNote that `redirectTo` should be null for Flutter Web.\n",
"code": "```dart\nawait supabase.auth.signInWithOAuth(\n OAuthProvider.github,\n redirectTo: kIsWeb ? null : 'io.supabase.flutter://reset-callback/',\n);\n```\n"
},
{
"id": "sign-in-with-scopes",
"name": "With scopes",
"description": "If you need additional data from an OAuth provider, you can include a space-separated list of scopes in your request to get back an OAuth provider token.\nYou may also need to specify the scopes in the provider's OAuth app settings, depending on the provider.\n",
"code": "```dart\nawait supabase.auth.signInWithOAuth(\n OAuthProvider.github,\n scopes: 'repo gist notifications'\n);\n...\n// after user comes back from signin flow\n\nfinal Session? session = supabase.auth.currentSession;\nfinal String? oAuthToken = session?.providerToken;\n```\n"
}
]
},
{
"id": "auth-signinwithotp",
"$ref": "supabase_flutter.signInWithOtp",
"notes": "- Requires either an email or phone number.\n- This method is used for passwordless sign-ins where an OTP is sent to the user's email or phone number.\n- If you're using an email, you can configure whether you want the user to receive a magiclink or an OTP.\n- If you're using phone, you can configure whether you want the user to receive an OTP.\n- The magic link's destination URL is determined by the [`SITE_URL`](https://supabase.com/docs/guides/auth/redirect-urls). You can modify the `SITE_URL` or add additional redirect urls in [your project](https://supabase.com/dashboard/project/_/auth/url-configuration).\n",
"params": [
{
"name": "email",
"isOptional": true,
"type": "String",
"description": "Email address to send the magic link or OTP to."
},
{
"name": "phone",
"isOptional": true,
"type": "String",
"description": "Phone number to send the OTP to."
},
{
"name": "emailRedirectTo",
"isOptional": true,
"type": "String",
"description": "The URL to redirect the user to after they click on the magic link."
},
{
"name": "shouldCreateUser",
"isOptional": true,
"type": "bool",
"description": "If set to false, this method will not create a new user. Defaults to true."
},
{
"name": "data",
"isOptional": true,
"type": "Map<String, dynamic>",
"description": "The user's metadata to be stored in the user's object."
},
{
"name": "captchaToken",
"isOptional": true,
"type": "String",
"description": "The captcha token to be used for captcha verification."
},
{
"name": "channel",
"isOptional": true,
"type": "OtpChannel",
"description": "Messaging channel to use (e.g. whatsapp or sms). Defaults to `OtpChannel.sms`."
}
],
"examples": [
{
"id": "sign-in-with-email",
"name": "Sign in with email.",
"isSpotlight": true,
"description": "The user will be sent an email which contains either a magiclink or an OTP or both. By default, a given user can only request an OTP once every 60 seconds.\nYou can pass `emailRedirectTo` with a dynamic link to bring the users back to your app after they click on the magic link.\n",
"code": "```dart\nawait supabase.auth.signInWithOtp(\n email: 'example@email.com',\n emailRedirectTo: kIsWeb ? null : 'io.supabase.flutter://signin-callback/',\n);\n```\n",
"response": "```json\nAuthResponse(\n user: null,\n session: null,\n);\n```\n"
},
{
"id": "sign-in-with-sms-otp",
"name": "Sign in with SMS OTP.",
"description": "The user will be sent a SMS which contains an OTP. By default, a given user can only request an OTP once every 60 seconds.",
"code": "```dart\nawait supabase.auth.signInWithOtp(\n phone: '+13334445555',\n);\n```\n"
},
{
"id": "sign-in-with-whatsapp-otp",
"name": "Sign in with WhatsApp OTP",
"isSpotlight": false,
"description": "The user will be sent a WhatsApp message which contains an OTP. By default, a given user can only request an OTP once every 60 seconds. Note that a user will need to have a valid WhatsApp account that is linked to Twilio in order to use this feature.",
"code": "```dart\nawait supabase.auth.signInWithOtp(\n phone: '+13334445555',\n channel: OtpChannel.whatsapp,\n);\n```\n"
}
]
},
{
"id": "auth-signinwithpasskey",
"$ref": "supabase_flutter.signInWithPasskey",
"notes": "Signs the user in with a passkey (WebAuthn).\n- Available on `supabase_flutter` 2.15.0 and later as an extension on `GoTrueClient`.\n- Drives the full WebAuthn ceremony end to end: starts the challenge with the Supabase server, prompts the user for biometrics or a security key via the platform passkey API, and verifies the credential with the server.\n- Does not require an existing session. On success the session is persisted and an `AuthChangeEvent.signedIn` event is fired.\n- For native flows or custom UI, use the lower-level [`auth.passkey`](/docs/reference/dart/auth-passkey-api) namespace instead.\n- Passkeys are a BETA feature and must be enabled for your project in the Supabase Dashboard under Authentication > Configuration > Passkeys.\n- Platform setup the library cannot perform (Associated Domains on iOS/macOS, Digital Asset Links on Android, the `passkeys` web SDK on web) is documented in the `supabase_flutter` package README.\n",
"params": [
{
"name": "captchaToken",
"isOptional": true,
"type": "String",
"description": "Captcha token to be used for captcha verification."
}
],
"examples": [
{
"id": "sign-in-with-passkey",
"name": "Sign in with a passkey",
"isSpotlight": true,
"code": "```dart\nfinal AuthResponse res = await supabase.auth.signInWithPasskey();\nfinal Session? session = res.session;\nfinal User? user = res.user;\n```\n"
}
]
},
{
"id": "auth-signinwithpassword",
"$ref": "supabase_flutter.signInWithPassword",
"description": "Log in an existing user using email or phone number with password.\n",
"notes": "- Requires either an email and password or a phone number and password.\n",
"params": [
{
"name": "email",
"isOptional": true,
"type": "String",
"description": "User's email address to be used for email authentication."
},
{
"name": "phone",
"isOptional": true,
"type": "String",
"description": "User's phone number to be used for phone authentication."
},
{
"name": "password",
"isOptional": false,
"type": "String",
"description": "Password to be used for authentication."
},
{
"name": "captchaToken",
"isOptional": true,
"type": "String",
"description": "The captcha token to be used for captcha verification."
}
],
"examples": [
{
"id": "sign-in-with-email-and-password",
"name": "Sign in with email and password",
"isSpotlight": true,
"code": "```dart\nfinal AuthResponse res = await supabase.auth.signInWithPassword(\n email: 'example@email.com',\n password: 'example-password',\n);\nfinal Session? session = res.session;\nfinal User? user = res.user;\n```\n",
"response": "```json\nAuthResponse(\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n session: Session(\n accessToken: '<ACCESS_TOKEN>',\n tokenType: 'bearer',\n expiresIn: 3600,\n refreshToken: '<REFRESH_TOKEN>',\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n ),\n);\n```\n"
},
{
"id": "sign-in-with-phone-and-password",
"name": "Sign in with phone and password",
"code": "```dart\nfinal AuthResponse res = await supabase.auth.signInWithPassword(\n phone: '+13334445555',\n password: 'example-password',\n);\nfinal Session? session = res.session;\nfinal User? user = res.user;\n```\n"
}
]
},
{
"id": "auth-signinwithsso",
"$ref": "supabase_flutter.signInWithSSO",
"notes": "- Before you can call this method you need to [establish a connection](/docs/guides/auth/sso/auth-sso-saml#managing-saml-20-connections) to an identity provider. Use the [CLI commands](/docs/reference/cli/supabase-sso) to do this.\n- If you've associated an email domain to the identity provider, you can use the `domain` property to start a sign-in flow.\n- In case you need to use a different way to start the authentication flow with an identity provider, you can use the `providerId` property. For example:\n - Mapping specific user email addresses with an identity provider.\n - Using different hints to identify the correct identity provider, like a company-specific page, IP address or other tracking information.\n",
"params": [
{
"name": "providerId",
"isOptional": true,
"type": "String",
"description": "The ID of the SSO provider to use for signing in."
},
{
"name": "domain",
"isOptional": true,
"type": "String",
"description": "The email domain to use for signing in."
},
{
"name": "redirectTo",
"isOptional": true,
"type": "String",
"description": "The URL to redirect the user to after they sign in with the third-party provider."
},
{
"name": "captchaToken",
"isOptional": true,
"type": "String",
"description": "The captcha token to be used for captcha verification."
},
{
"name": "launchMode",
"isOptional": true,
"type": "LaunchMode",
"description": "The launch mode for the auth screen. Defaults to `LaunchMode.platformDefault`."
}
],
"examples": [
{
"id": "sign-in-with-domain",
"name": "Sign in with email domain",
"isSpotlight": true,
"code": "```dart\nawait supabase.auth.signInWithSSO(\n domain: 'company.com',\n);\n```\n"
},
{
"id": "sign-in-with-provider-uuid",
"name": "Sign in with provider UUID",
"isSpotlight": true,
"code": "```dart\nawait supabase.auth.signInWithSSO(\n providerId: '21648a9d-8d5a-4555-a9d1-d6375dc14e92',\n);\n```\n"
}
]
},
{
"id": "auth-signout",
"$ref": "supabase_flutter.signOut",
"description": "Signs out the current user, if there is a logged in user.\n",
"notes": "- In order to use the `signOut()` method, the user needs to be signed in first.\n",
"params": [
{
"name": "scope",
"isOptional": true,
"type": "SignOutScope",
"description": "Whether to sign out from all devices or just the current device. Defaults to `SignOutScope.local`."
}
],
"examples": [
{
"id": "sign-out",
"name": "Sign out",
"isSpotlight": true,
"code": "```dart\nawait supabase.auth.signOut();\n```\n"
}
]
},
{
"id": "auth-signup",
"$ref": "supabase_flutter.signUp",
"description": "Creates a new user.\n",
"notes": "- By default, the user needs to verify their email address before logging in. To turn this off, disable **Confirm email** in [your project](https://supabase.com/dashboard/project/_/auth/providers).\n- **Confirm email** determines if users need to confirm their email address after signing up.\n - If **Confirm email** is enabled, a `user` is returned but `session` is null.\n - If **Confirm email** is disabled, both a `user` and a `session` are returned.\n- When the user confirms their email address, they are redirected to the [`SITE_URL`](https://supabase.com/docs/guides/auth/redirect-urls) by default. You can modify your `SITE_URL` or add additional redirect URLs in [your project](https://supabase.com/dashboard/project/_/auth/url-configuration).\n- If signUp() is called for an existing confirmed user:\n - When both **Confirm email** and **Confirm phone** (even when phone provider is disabled) are enabled in [your project](/dashboard/project/_/auth/providers), an obfuscated/fake user object is returned.\n - When either **Confirm email** or **Confirm phone** (even when phone provider is disabled) is disabled, the error message, `User already registered` is returned.\n",
"params": [
{
"name": "email",
"isOptional": true,
"type": "String",
"description": "User's email address to be used for email authentication."
},
{
"name": "phone",
"isOptional": true,
"type": "String",
"description": "User's phone number to be used for phone authentication."
},
{
"name": "password",
"isOptional": false,
"type": "String",
"description": "Password to be used for authentication."
},
{
"name": "emailRedirectTo",
"isOptional": true,
"type": "String",
"description": "The URL to redirect the user to after they confirm their email address."
},
{
"name": "data",
"isOptional": true,
"type": "Map<String, dynamic>",
"description": "The user's metadata to be stored in the user's object."
},
{
"name": "captchaToken",
"isOptional": true,
"type": "String",
"description": "The captcha token to be used for captcha verification."
},
{
"name": "channel",
"isOptional": true,
"type": "OtpChannel",
"description": "Messaging channel to use (e.g. whatsapp or sms). Defaults to `OtpChannel.sms`."
}
],
"examples": [
{
"id": "sign-up",
"name": "Sign up with an email and password",
"isSpotlight": true,
"code": "```dart\nfinal AuthResponse res = await supabase.auth.signUp(\n email: 'example@email.com',\n password: 'example-password',\n);\nfinal Session? session = res.session;\nfinal User? user = res.user;\n```\n",
"response": "```json\n// Some fields may be null if \"confirm email\" is enabled.\nAuthResponse(\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n session: Session(\n accessToken: '<ACCESS_TOKEN>',\n tokenType: 'bearer',\n expiresIn: 3600,\n refreshToken: '<REFRESH_TOKEN>',\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n ),\n);\n```\n"
},
{
"id": "sign-up-phone",
"name": "Sign up with a phone number and password (SMS)",
"isSpotlight": true,
"code": "```dart\nfinal AuthResponse res = await supabase.auth.signUp(\n phone: '123456789',\n password: 'example-password',\n channel: OtpChannel.sms,\n);\n```\n"
},
{
"id": "sign-up-with-metadata",
"name": "Sign up with additional metadata",
"isSpotlight": true,
"code": "```dart\nfinal AuthResponse res = await supabase.auth.signUp(\n email: 'example@email.com',\n password: 'example-password',\n data: {'username': 'my_user_name'},\n);\nfinal Session? session = res.session;\nfinal User? user = res.user;\n```\n"
},
{
"id": "sign-up-with-redirect-url",
"name": "Sign up with redirect URL",
"isSpotlight": true,
"description": "- See [redirect URLs and wildcards](/docs/guides/auth#redirect-urls-and-wildcards) to add additional redirect URLs to your project.\n",
"code": "```dart\nfinal AuthResponse res = await supabase.auth.signUp(\n email: 'example@email.com',\n password: 'example-password',\n emailRedirectTo: 'com.supabase.myapp://callback',\n);\nfinal Session? session = res.session;\nfinal User? user = res.user;\n```\n"
}
]
},
{
"id": "auth-unlinkidentity",
"$ref": "supabase_flutter.unlinkIdentity",
"description": "Unlinks an identity from a user by deleting it. The user will no longer be able to sign in with that identity once it's unlinked.\n",
"notes": "- The **Enable Manual Linking** option must be enabled from your [project's authentication settings](/dashboard/project/_/auth/providers).\n- The user needs to be signed in to call `unlinkIdentity()`.\n- The user must have at least 2 identities in order to unlink an identity.\n- The identity to be unlinked must belong to the user.\n",
"params": [
{
"name": "identity",
"isOptional": false,
"type": "UserIdentity",
"description": "The user identity to unlink."
}
],
"examples": [
{
"id": "unlink-identity",
"name": "Unlink an identity",
"isSpotlight": true,
"code": "```dart\n// retrieve all identities linked to a user\nfinal identities = await supabase.auth.getUserIdentities();\n\n// find the google identity\nfinal googleIdentity = identities.firstWhere(\n (element) => element.provider == 'google',\n);\n\n// unlink the google identity\nawait supabase.auth.unlinkIdentity(googleIdentity);\n```\n"
}
]
},
{
"id": "auth-updateuser",
"$ref": "supabase_flutter.updateUser",
"description": "Updates user data for a logged in user.\n",
"notes": "- In order to use the `updateUser()` method, the user needs to be signed in first.\n- By default, email updates sends a confirmation link to both the user's current and new email.\nTo only send a confirmation link to the user's new email, disable **Secure email change** in your project's [email auth provider settings](https://supabase.com/dashboard/project/_/auth/providers).\n",
"params": [
{
"name": "attributes",
"isOptional": false,
"type": "UserAttributes",
"description": "Attributes to update for the user.",
"subContent": [
{
"name": "email",
"isOptional": true,
"type": "String",
"description": "The new email address for the user."
},
{
"name": "phone",
"isOptional": true,
"type": "String",
"description": "The new phone number for the user."
},
{
"name": "password",
"isOptional": true,
"type": "String",
"description": "The new password for the user."
},
{
"name": "data",
"isOptional": true,
"type": "Map<String, dynamic>",
"description": "The user's metadata to be stored in the user's object."
},
{
"name": "nonce",
"isOptional": true,
"type": "String",
"description": "The nonce sent for reauthentication if the user's password is to be updated."
}
]
},
{
"name": "emailRedirectTo",
"isOptional": true,
"type": "String",
"description": "The URI to redirect the user to after the email is updated."
}
],
"examples": [
{
"id": "update-the-email-for-an-authenticated-user",
"name": "Update the email for an authenticated user",
"description": "Sends a \"Confirm Email Change\" email to the new email address.",
"isSpotlight": true,
"code": "```dart\nfinal UserResponse res = await supabase.auth.updateUser(\n UserAttributes(\n email: 'example@email.com',\n ),\n);\nfinal User? updatedUser = res.user;\n```\n",
"response": "```json\nUserResponse(\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n);\n```\n"
},
{
"id": "update-the-password-for-an-authenticated-user",
"name": "Update the password for an authenticated user",
"isSpotlight": false,
"code": "```dart\nfinal UserResponse res = await supabase.auth.updateUser(\n UserAttributes(\n password: 'new password',\n ),\n);\nfinal User? updatedUser = res.user;\n```\n"
},
{
"id": "update-the-users-metadata",
"name": "Update the user's metadata",
"isSpotlight": true,
"code": "```dart\nfinal UserResponse res = await supabase.auth.updateUser(\n UserAttributes(\n data: { 'hello': 'world' },\n ),\n);\nfinal User? updatedUser = res.user;\n```\n"
},
{
"id": "update-password-with-reauthentication",
"name": "Update the user's password with a nonce",
"description": "If \"Secure password change\" is enabled, updating the user's password requires a nonce. The nonce is sent to the user's email or phone number.",
"isSpotlight": true,
"code": "```dart\nsupabase.auth.updateUser(UserAttributes(\n email: 'example@email.com',\n nonce: '123456',\n));\n```\n"
}
]
},
{
"id": "auth-verifyotp",
"$ref": "supabase_flutter.verifyOtp",
"notes": "- The `verifyOtp` method takes in different verification types. If a phone number is used, the type can either be `sms` or `phone_change`. If an email address is used, the type can be one of the following: `email`, `recovery`, `invite` or `email_change` (`signup` and `magiclink` types are deprecated).\n- The verification type used should be determined based on the corresponding auth method called before `verifyOtp` to sign up or sign in a user.\n",
"params": [
{
"name": "token",
"isOptional": false,
"type": "String",
"description": "The token that user was sent to their email or mobile phone"
},
{
"name": "type",
"isOptional": false,
"type": "OtpType",
"description": "Type of the OTP to verify"
},
{
"name": "email",
"isOptional": true,
"type": "String",
"description": "Email address that the OTP was sent to"
},
{
"name": "phone",
"isOptional": true,
"type": "String",
"description": "Phone number that the OTP was sent to"
},
{
"name": "redirectTo",
"isOptional": true,
"type": "String",
"description": "URI to redirect the user to after the OTP is verified"
},
{
"name": "captchaToken",
"isOptional": true,
"type": "String",
"description": "The captcha token to be used for captcha verification"
},
{
"name": "tokenHash",
"isOptional": true,
"type": "String",
"description": "Token used in an email link"
}
],
"examples": [
{
"id": "verify-signup-one-time-password(otp)",
"name": "Verify Signup One-Time Password (OTP)",
"isSpotlight": false,
"code": "```dart\nfinal AuthResponse res = await supabase.auth.verifyOTP(\n type: OtpType.signup,\n token: token,\n phone: '+13334445555',\n);\nfinal Session? session = res.session;\nfinal User? user = res.user;\n```\n",
"response": "```json\nAuthResponse(\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n session: Session(\n accessToken: '<ACCESS_TOKEN>',\n tokenType: 'bearer',\n expiresIn: 3600,\n refreshToken: '<REFRESH_TOKEN>',\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n ),\n);\n```\n"
},
{
"id": "verify-sms-one-time-password(otp)",
"name": "Verify SMS One-Time Password (OTP)",
"isSpotlight": true,
"code": "```dart\nfinal AuthResponse res = await supabase.auth.verifyOTP(\n type: OtpType.sms,\n token: '111111',\n phone: '+13334445555',\n);\nfinal Session? session = res.session;\nfinal User? user = res.user;\n```\n"
}
]
},
{
"id": "auth-admin",
"title": "Auth Admin",
"notes": "- Any method under the `supabase.auth.admin` namespace requires a `secret` key.\n- These methods are considered admin methods and should be called on a trusted server. Never expose your `secret` key in the Flutter app.\n",
"examples": [
{
"id": "create-auth-admin-client",
"name": "Create server-side auth client",
"isSpotlight": true,
"code": "```dart\nfinal supabase = SupabaseClient(supabaseUrl, secretKey);\n```\n"
}
]
},
{
"id": "auth-admin-createuser",
"$ref": "supabase_flutter.createUser",
"notes": "Creates a new user.\n- To confirm the user's email address or phone number, set `email_confirm` or `phone_confirm` to true. Both arguments default to false.\n- `createUser()` will not send a confirmation email to the user. You can use [`inviteUserByEmail()`](/docs/reference/dart/auth-admin-inviteuserbyemail) if you want to send them an email invite instead.\n- If you are sure that the created user's email or phone number is legitimate and verified, you can set the `email_confirm` or `phone_confirm` param to `true`.\n",
"params": [
{
"name": "attributes",
"isOptional": false,
"type": "AdminUserAttributes",
"description": "Attributes to create the user with.",
"subContent": [
{
"name": "email",
"isOptional": false,
"type": "String",
"description": "The email address of the user."
},
{
"name": "password",
"isOptional": false,
"type": "String",
"description": "The password of the user."
},
{
"name": "phone",
"isOptional": true,
"type": "String",
"description": "The phone number of the user."
},
{
"name": "userMetadata",
"isOptional": true,
"type": "Map<String, dynamic>",
"description": "A custom data object to store the user's metadata. This maps to the `auth.users.user_metadata` column."
},
{
"name": "appMetadata",
"isOptional": true,
"type": "Map<String, dynamic>",
"description": "A custom data object to store the user's application specific metadata. This maps to the `auth.users.app_metadata` column."
},
{
"name": "emailConfirm",
"isOptional": true,
"type": "bool",
"description": "Whether to confirm the user's email address."
},
{
"name": "phoneConfirm",
"isOptional": true,
"type": "bool",
"description": "Whether to confirm the user's phone number."
},
{
"name": "banDuration",
"isOptional": true,
"type": "String",
"description": "Determines how long a user is banned for. Some possible durations include '300ms', '2h45m'."
}
]
}
],
"examples": [
{
"id": "create-a-new-user-with-custom-user-metadata",
"name": "With custom user metadata",
"isSpotlight": true,
"code": "```dart\nfinal res = await supabase.auth.admin.createUser(AdminUserAttributes(\n email: 'user@email.com',\n password: 'password',\n userMetadata: {'name': 'Yoda'},\n));\n```\n",
"response": "```json\nUserResponse(\n user: User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'user@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {'name': 'Yoda'},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'user@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n);\n```\n"
},
{
"id": "auto-confirm-the-users-email",
"name": "Auto-confirm the user's email",
"code": "```dart\nfinal res = await supabase.auth.admin.createUser(AdminUserAttributes(\n email: 'user@email.com',\n emailConfirm: true,\n));\n```\n"
},
{
"id": "auto-confirm-the-users-phone-number",
"name": "Auto-confirm the user's phone number",
"code": "```dart\nfinal res = await supabase.auth.admin.createUser(AdminUserAttributes(\n phone: '1234567890',\n phoneConfirm: true,\n));\n```\n"
}
]
},
{
"id": "auth-admin-deleteuser",
"$ref": "supabase_flutter.deleteUser",
"notes": "Delete a user.\n- The `deleteUser()` method requires the user's ID, which maps to the `auth.users.id` column.\n",
"params": [
{
"name": "id",
"isOptional": false,
"type": "String",
"description": "ID of the user to be deleted."
}
],
"examples": [
{
"id": "removes-a-user",
"name": "Removes a user",
"isSpotlight": true,
"code": "```dart\nawait supabase.auth.admin\n .deleteUser('715ed5db-f090-4b8c-a067-640ecee36aa0');\n```\n"
}
]
},
{
"id": "auth-admin-generatelink",
"$ref": "supabase_flutter.generateLink",
"notes": "Generates email links and OTPs. This will not send links or OTPs to the end user. This function is for custom admin functionality.\n- The following types can be passed into `generateLink()`: `signup`, `magiclink`, `invite`, `recovery`, `emailChangeCurrent`, `emailChangeNew`, `phoneChange`.\n- `generateLink()` only generates the email link for `email_change_email` if the \"Secure email change\" setting is enabled under the \"Email\" provider in your Supabase project.\n- `generateLink()` handles the creation of the user for `signup`, `invite` and `magiclink`.\n",
"params": [
{
"name": "type",
"isOptional": false,
"type": "GenerateLinkType",
"description": "The type of invite link to generate."
},
{
"name": "email",
"isOptional": false,
"type": "String",
"description": "Email address of the user to invite."
},
{
"name": "password",
"isOptional": true,
"type": "String",
"description": "Password for the user. Required for `signup` type."
},
{
"name": "redirectTo",
"isOptional": true,
"type": "String",
"description": "URI to redirect the user to after they open the invite link."
},
{
"name": "data",
"isOptional": true,
"type": "Map<String, dynamic>",
"description": "A custom data object to store the user's metadata. This maps to the `auth.users.user_metadata` column."
}
],
"examples": [
{
"id": "generate-a-signup-link",
"name": "Generate a signup link",
"isSpotlight": true,
"code": "```dart\nfinal res = await supabase.auth.admin.generateLink(\n type: GenerateLinkType.signup,\n email: 'email@example.com',\n password: 'secret',\n);\nfinal actionLink = res.properties.actionLink;\n```\n",
"response": "```json\nGenerateLinkResponse(\n properties: GenerateLinkProperties(\n actionLink: '<LINK_TO_SEND_TO_USER>',\n emailOtp: '999999',\n hashedToken: '<HASHED_TOKEN',\n redirectTo: '<REDIRECT_URL>',\n verificationType: GenerateLinkType.signup\n ),\n user: User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'email@example.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'email@example.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n)\n```\n"
}
]
},
{
"id": "auth-admin-getuserbyid",
"$ref": "supabase_flutter.getUserById",
"notes": "Get user by id.\n- Fetches the user object from the database based on the user's id.\n- The `getUserById()` method requires the user's id which maps to the `auth.users.id` column.\n",
"params": [
{
"name": "uid",
"isOptional": false,
"type": "String",
"description": "User ID of the user to fetch."
}
],
"examples": [
{
"id": "fetch-the-user-object-using-the-access-token-jwt",
"name": "Fetch the user object using the access_token jwt",
"isSpotlight": true,
"code": "```dart\nfinal res = await supabase.auth.admin.getUserById(userId);\nfinal user = res.user;\n```\n",
"response": "```json\nUserResponse(\n user: const User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n);\n```\n"
}
]
},
{
"id": "auth-admin-inviteuserbyemail",
"$ref": "supabase_flutter.inviteUserByEmail",
"notes": "Sends an invite link to the user's email address.\n",
"params": [
{
"name": "email",
"isOptional": false,
"type": "String",
"description": "Email address of the user to invite."
},
{
"name": "redirectTo",
"isOptional": true,
"type": "String",
"description": "URI to redirect the user to after they open the invite link."
},
{
"name": "data",
"isOptional": true,
"type": "Map<String, dynamic>",
"description": "A custom data object to store the user's metadata. This maps to the `auth.users.user_metadata` column."
}
],
"examples": [
{
"id": "invite-a-user",
"name": "Invite a user",
"isSpotlight": true,
"code": "```dart\nfinal UserResponse res = await supabase.auth.admin\n .inviteUserByEmail('email@example.com');\nfinal User? user = res.user;\n```\n",
"response": "```json\nUserResponse(\n user: User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'email@example.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'email@example.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n);\n```\n"
}
]
},
{
"id": "auth-admin-listusers",
"$ref": "supabase_flutter.listUsers",
"notes": "Get a list of users.\n- Defaults to return 50 users per page.\n",
"params": [
{
"name": "page",
"isOptional": true,
"type": "int",
"description": "What page of users to return."
},
{
"name": "page",
"isOptional": true,
"type": "int",
"description": "How many users to be returned per page. Defaults to 50."
}
],
"examples": [
{
"id": "get-a-full-list-of-users",
"name": "Get a page of users",
"isSpotlight": true,
"code": "```dart\n// Returns the first 50 users.\nfinal List<User> users = await supabase.auth.admin.listUsers();\n```\n",
"response": "```json\n[\n User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n )\n]\n```\n"
},
{
"id": "get-paginated-list-of-users",
"name": "Paginated list of users",
"isSpotlight": false,
"code": "```dart\n// Returns the 101th - 200th users.\nfinal List<User> res = await supabase.auth.admin.listUsers(\n page: 2,\n perPage: 100,\n);\n```\n"
}
]
},
{
"id": "auth-admin-updateuserbyid",
"$ref": "supabase_flutter.updateUserById",
"params": [
{
"name": "uid",
"isOptional": false,
"type": "GenerateLinkType",
"description": "User ID of the user to update."
},
{
"name": "attributes",
"isOptional": false,
"type": "AdminUserAttributes",
"description": "Attributes to update for the user.",
"subContent": [
{
"name": "email",
"isOptional": false,
"type": "String",
"description": "The email address of the user."
},
{
"name": "password",
"isOptional": false,
"type": "String",
"description": "The password of the user."
},
{
"name": "phone",
"isOptional": true,
"type": "String",
"description": "The phone number of the user."
},
{
"name": "userMetadata",
"isOptional": true,
"type": "Map<String, dynamic>",
"description": "A custom data object to store the user's metadata. This maps to the `auth.users.user_metadata` column."
},
{
"name": "appMetadata",
"isOptional": true,
"type": "Map<String, dynamic>",
"description": "A custom data object to store the user's application specific metadata. This maps to the `auth.users.app_metadata` column."
},
{
"name": "emailConfirm",
"isOptional": true,
"type": "bool",
"description": "Whether to confirm the user's email address."
},
{
"name": "phoneConfirm",
"isOptional": true,
"type": "bool",
"description": "Whether to confirm the user's phone number."
},
{
"name": "banDuration",
"isOptional": true,
"type": "String",
"description": "Determines how long a user is banned for. Some possible durations include '300ms', '2h45m'."
}
]
}
],
"examples": [
{
"id": "updates-a-users-email",
"name": "Updates a user's email",
"isSpotlight": false,
"code": "```dart\nawait supabase.auth.admin.updateUserById(\n '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',\n attributes: AdminUserAttributes(\n email: 'new@email.com',\n ),\n);\n```\n"
}
]
},
{
"id": "auth-mfa",
"title": "Auth MFA",
"notes": "This section contains methods commonly used for Multi-Factor Authentication (MFA) and are invoked behind the `supabase.auth.mfa` namespace.\n\nCurrently, Supabase supports time-based one-time password (TOTP) and phone verification code as the 2nd factor. Recovery codes are not supported but users can enroll multiple factors, with an upper limit of 10..\n\nHaving a 2nd factor for recovery frees the user of the burden of having to store their recovery codes somewhere. It also reduces the attack surface since multiple recovery codes are usually generated compared to just having 1 backup factor.\n\nLearn more about implementing MFA on your application on our guide [here](https://supabase.com/docs/guides/auth/auth-mfa#overview).\n"
},
{
"id": "auth-mfa-challenge",
"$ref": "supabase_flutter.challenge",
"notes": "Prepares a challenge used to verify that a user has access to a MFA factor.\n- An [enrolled factor](/docs/reference/dart/auth-mfa-enroll) is required before creating a challenge.\n- To verify a challenge, see [`mfa.verify()`](/docs/reference/dart/auth-mfa-verify).\n",
"params": [
{
"name": "factorId",
"isOptional": false,
"type": "String",
"description": "System assigned identifier for authenticator device as returned by enroll"
}
],
"examples": [
{
"id": "create-mfa-challenge",
"name": "Create a challenge for a factor",
"isSpotlight": true,
"code": "```dart\nfinal res = await supabase.auth.mfa.challenge(\n factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',\n);\n```\n",
"response": "```json\nAuthMFAChallengeResponse(\n id: '<ID>',\n expiresAt: DateTime.fromMillisecondsSinceEpoch(1700000000),\n);\n```\n"
}
]
},
{
"id": "auth-mfa-challengeandverify",
"$ref": "supabase_flutter.challengeAndVerify",
"notes": "Helper method which creates a challenge and immediately uses the given code to verify against it thereafter. The verification code is provided by the user by entering a code seen in their authenticator app.\n- An [enrolled factor](/docs/reference/dart/auth-mfa-enroll) is required before invoking `challengeAndVerify()`.\n- Executes [`mfa.challenge()`](/docs/reference/dart/auth-mfa-challenge) and [`mfa.verify()`](/docs/reference/dart/auth-mfa-verify) in a single step.\n",
"params": [
{
"name": "factorId",
"isOptional": false,
"type": "String",
"description": "System assigned identifier for authenticator device as returned by enroll"
},
{
"name": "code",
"isOptional": false,
"type": "String",
"description": "The verification code on the user's authenticator app"
}
],
"examples": [
{
"id": "challenge-and-verify",
"name": "Create and verify a challenge for a factor",
"isSpotlight": true,
"code": "```dart\nfinal res = await supabase.auth.mfa.challengeAndVerify(\n factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',\n code: '123456',\n);\n```\n",
"response": "```json\nAuthMFAVerifyResponse(\n accessToken: '<ACCESS_TOKEN>',\n tokenType: 'Bearer',\n expiresIn: Duration(seconds: 3600),\n refreshToken: '<REFRESH_TOKEN>',\n user: User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n isAnonymous: false,\n factors: [\n Factor(\n id: '<ID>',\n friendlyName: 'Important Auth App',\n factorType: FactorType.totp,\n status: 'verified',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z'\n )\n ]\n )\n);\n```\n"
}
]
},
{
"id": "auth-mfa-enroll",
"$ref": "supabase_flutter.enroll",
"notes": "Starts the enrollment process for a new Multi-Factor Authentication (MFA) factor. This method creates a new `unverified` factor.\nTo verify a factor, present the QR code or secret to the user and ask them to add it to their authenticator app.\nThe user has to enter the code from their authenticator app to verify it.\n- Use `totp` or `phone` as the `factorType` and the returned `id` to create a challenge.\n- To create a challenge, see [`mfa.challenge()`](/docs/reference/dart/auth-mfa-challenge).\n- To verify a challenge, see [`mfa.verify()`](/docs/reference/dart/auth-mfa-verify).\n- To create and verify a challenge in a single step, see [`mfa.challengeAndVerify()`](/docs/reference/dart/auth-mfa-challengeandverify).\n",
"params": [
{
"name": "factorType",
"isOptional": true,
"type": "String",
"description": "Type of factor being enrolled."
},
{
"name": "issuer",
"isOptional": true,
"type": "String",
"description": "Domain which the user is enrolled with."
},
{
"name": "friendlyName",
"isOptional": true,
"type": "String",
"description": "Human readable name assigned to the factor."
},
{
"name": "phone",
"isOptional": true,
"type": "String",
"description": "Phone number to enroll for phone factor type."
}
],
"examples": [
{
"id": "enroll-totp-factor",
"name": "Enroll a time-based, one-time password (TOTP) factor",
"isSpotlight": true,
"code": "```dart\nfinal res = await supabase.auth.mfa.enroll(factorType: FactorType.totp);\n\nfinal qrCodeUrl = res.totp.qrCode;\n```\n",
"response": "```json\nAuthMFAEnrollResponse(\n id: '<ID>',\n type: FactorType.totp,\n totp: TOTPEnrollment(\n qrCode: '<QR_CODE_AS_SVG_DATA>',\n secret: '<SECRET>',\n uri: '<URI>',\n ),\n phone: null,\n);\n```\n"
},
{
"id": "enroll-phone-factor",
"name": "Enroll a Phone Factor",
"isSpotlight": true,
"code": "```dart\nfinal res = await supabase.auth.mfa.enroll(factorType: FactorType.phone, phone: '+1234567890');\n\nfinal phone = res.phone;\n```\n",
"response": "```json\nAuthMFAEnrollResponse(\n id: '<ID>',\n type: FactorType.phone,\n totp: null,\n phone: PhoneEnrollment(\n phone: '+1234567890',\n ),\n);\n```\n"
}
]
},
{
"id": "auth-mfa-getauthenticatorassurancelevel",
"$ref": "supabase_flutter.getAuthenticatorAssuranceLevel",
"notes": "Returns the Authenticator Assurance Level (AAL) for the active session.\n- Authenticator Assurance Level (AAL) is the measure of the strength of an authentication mechanism.\n- In Supabase, having an AAL of `aal1` means the user has signed in with their first factor, such as email, password, or OAuth sign-in. An AAL of `aal2` means the user has also signed in with their second factor, such as a time-based, one-time-password (TOTP).\n- If the user has a verified factor, the `nextLevel` field returns `aal2`. Otherwise, it returns `aal1`.\n",
"examples": [
{
"id": "get-aal",
"name": "Get the AAL details of a session",
"isSpotlight": true,
"code": "```dart\nfinal res = supabase.auth.mfa.getAuthenticatorAssuranceLevel();\nfinal currentLevel = res.currentLevel;\nfinal nextLevel = res.nextLevel;\nfinal currentAuthenticationMethods = res.currentAuthenticationMethods;\n```\n",
"response": "```json\nAuthMFAGetAuthenticatorAssuranceLevelResponse(\n currentLevel: AuthenticatorAssuranceLevels.aal1,\n nextLevel: AuthenticatorAssuranceLevels.aal2,\n currentAuthenticationMethods: [\n AMREntry(\n method: AMRMethod.password,\n timestamp: DateTime.fromMillisecondsSinceEpoch(1700000000000),\n )\n ]\n}\n```\n"
}
]
},
{
"id": "auth-mfa-unenroll",
"$ref": "supabase_flutter.unenroll",
"notes": "Unenroll removes a MFA factor.\nA user has to have an `aal2` authenticator level in order to unenroll a `verified` factor.\n",
"params": [
{
"name": "factorId",
"isOptional": false,
"type": "String",
"description": "System assigned identifier for authenticator device as returned by enroll"
}
],
"examples": [
{
"id": "unenroll-a-factor",
"name": "Unenroll a factor",
"isSpotlight": true,
"code": "```dart\nfinal res = await supabase.auth.mfa.unenroll(\n '34e770dd-9ff9-416c-87fa-43b31d7ef225',\n);\n```\n",
"response": "```json\nAuthMFAUnenrollResponse(\n id: '<FACTOR_ID>',\n);\n```\n"
}
]
},
{
"id": "auth-mfa-verify",
"$ref": "supabase_flutter.verify",
"notes": "Verifies a code against a challenge. The verification code is provided by the user by entering a code seen in their authenticator app.\n- To verify a challenge, please [create a challenge](/docs/reference/dart/auth-mfa-challenge) first.\n",
"params": [
{
"name": "factorId",
"isOptional": false,
"type": "String",
"description": "System assigned identifier for authenticator device as returned by enroll"
},
{
"name": "challengeId",
"isOptional": false,
"type": "String",
"description": "The ID of the challenge to verify"
},
{
"name": "code",
"isOptional": false,
"type": "String",
"description": "The verification code on the user's authenticator app"
}
],
"examples": [
{
"id": "verify-challenge",
"name": "Verify a challenge for a factor",
"isSpotlight": true,
"code": "```dart\nfinal res = await supabase.auth.mfa.verify(\n factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',\n challengeId: '4034ae6f-a8ce-4fb5-8ee5-69a5863a7c15',\n code: '123456',\n);\n```\n",
"response": "```json\nAuthMFAVerifyResponse(\n accessToken: '<ACCESS_TOKEN>',\n tokenType: 'Bearer',\n expiresIn: Duration(seconds: 3600),\n refreshToken: '<REFRESH_TOKEN>',\n user: User(\n id: '11111111-1111-1111-1111-111111111111',\n aud: 'authenticated',\n role: 'authenticated',\n email: 'example@email.com',\n emailConfirmedAt: '2024-01-01T00:00:00Z',\n phone: '',\n lastSignInAt: '2024-01-01T00:00:00Z',\n appMetadata: {\n 'provider': 'email',\n 'providers': ['email']\n },\n userMetadata: {},\n identities: [\n UserIdentity(\n identityId: '22222222-2222-2222-2222-222222222222',\n id: '11111111-1111-1111-1111-111111111111',\n userId: '11111111-1111-1111-1111-111111111111',\n identityData: {\n 'email': 'example@email.com',\n 'email_verified': false,\n 'phone_verified': false,\n 'sub': '11111111-1111-1111-1111-111111111111'\n },\n provider: 'email',\n lastSignInAt: '2024-01-01T00:00:00Z',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n ),\n ],\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z',\n isAnonymous: false,\n factors: [\n Factor(\n id: '<ID>',\n friendlyName: 'Important Auth App',\n factorType: FactorType.totp,\n status: 'verified',\n createdAt: '2024-01-01T00:00:00Z',\n updatedAt: '2024-01-01T00:00:00Z'\n )\n ]\n )\n);\n```\n"
}
]
},
{
"id": "auth-passkey",
"title": "Auth Passkey",
"notes": "This section contains methods for WebAuthn passkey registration, authentication, and management. Methods are invoked behind the `supabase.auth.passkey` namespace.\n\nThese methods expose the server side of the WebAuthn ceremony. The client side (the FaceID/TouchID/security key prompt) has to be performed with a platform passkey API: `navigator.credentials.create()`/`get()` on web, or a passkey plugin on iOS/Android/macOS. Options and credentials are exchanged as `Map<String, dynamic>` in the W3C WebAuthn Level 3 JSON format.\n\nFor a one-call alternative that runs the full ceremony, see [`signInWithPasskey()`](/docs/reference/dart/auth-signinwithpasskey) and [`registerPasskey()`](/docs/reference/dart/auth-registerpasskey) on `supabase_flutter`.\n\nPasskey support is a BETA feature and must be enabled for your project in the Supabase Dashboard under Authentication > Configuration > Passkeys.\n"
},
{
"id": "auth-passkey-delete",
"$ref": "supabase_flutter.delete",
"notes": "Deletes a passkey from the signed in user.\n- If the user has verified MFA factors, the session has to be at `aal2` to manage passkeys.\n",
"params": [
{
"name": "passkeyId",
"isOptional": false,
"type": "String",
"description": "ID of the passkey to delete."
}
],
"examples": [
{
"id": "delete-passkey",
"name": "Delete a passkey",
"isSpotlight": true,
"code": "```dart\nawait supabase.auth.passkey.delete(\n passkeyId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',\n);\n```\n"
}
]
},
{
"id": "auth-passkey-list",
"$ref": "supabase_flutter.list",
"notes": "Returns the list of passkeys registered to the signed in user.\n",
"examples": [
{
"id": "list-passkeys",
"name": "List the current user's passkeys",
"isSpotlight": true,
"code": "```dart\nfinal List<Passkey> passkeys = await supabase.auth.passkey.list();\n```\n"
}
]
},
{
"id": "auth-passkey-startauthentication",
"$ref": "supabase_flutter.startAuthentication",
"notes": "Starts a passkey sign in.\n- Does not require an existing session.\n- Pass the returned `options` to the platform's passkey API to obtain an assertion, then call [`passkey.verifyAuthentication()`](/docs/reference/dart/auth-passkey-verifyauthentication) with the result.\n",
"params": [
{
"name": "captchaToken",
"isOptional": true,
"type": "String",
"description": "Captcha token to be used for captcha verification."
}
],
"examples": [
{
"id": "start-passkey-authentication",
"name": "Start a passkey sign in",
"isSpotlight": true,
"code": "```dart\nfinal PasskeyAuthenticationOptionsResponse authentication =\n await supabase.auth.passkey.startAuthentication();\n\n// Hand authentication.options to the platform passkey API.\n```\n"
}
]
},
{
"id": "auth-passkey-startregistration",
"$ref": "supabase_flutter.startRegistration",
"notes": "Starts the registration of a new passkey for the signed in user.\n- Requires a signed in (non-anonymous) user.\n- Pass the returned `options` to the platform's passkey API to create the credential, then call [`passkey.verifyRegistration()`](/docs/reference/dart/auth-passkey-verifyregistration) with the result.\n",
"examples": [
{
"id": "start-passkey-registration",
"name": "Start a passkey registration",
"isSpotlight": true,
"code": "```dart\nfinal PasskeyRegistrationOptionsResponse registration =\n await supabase.auth.passkey.startRegistration();\n\n// Hand registration.options to the platform passkey API.\n```\n"
}
]
},
{
"id": "auth-passkey-update",
"$ref": "supabase_flutter.update",
"notes": "Updates the friendly name of a passkey.\n",
"params": [
{
"name": "passkeyId",
"isOptional": false,
"type": "String",
"description": "ID of the passkey to rename."
},
{
"name": "friendlyName",
"isOptional": false,
"type": "String",
"description": "New human readable name for the passkey. Limited to 120 characters."
}
],
"examples": [
{
"id": "rename-passkey",
"name": "Rename a passkey",
"isSpotlight": true,
"code": "```dart\nfinal Passkey passkey = await supabase.auth.passkey.update(\n passkeyId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',\n friendlyName: 'Work laptop',\n);\n```\n"
}
]
},
{
"id": "auth-passkey-verifyauthentication",
"$ref": "supabase_flutter.verifyAuthentication",
"notes": "Completes a passkey sign in and returns the new session.\n- On success the session is persisted and an `AuthChangeEvent.signedIn` event is fired.\n",
"params": [
{
"name": "challengeId",
"isOptional": false,
"type": "String",
"description": "The challenge ID returned by `passkey.startAuthentication()`."
},
{
"name": "credential",
"isOptional": false,
"type": "Map<String, dynamic>",
"description": "The assertion produced by the platform's passkey API, serialized in the W3C `AuthenticationResponseJSON` format."
}
],
"examples": [
{
"id": "verify-passkey-authentication",
"name": "Verify a passkey sign in",
"isSpotlight": true,
"code": "```dart\nfinal AuthResponse res = await supabase.auth.passkey.verifyAuthentication(\n challengeId: authentication.challengeId,\n credential: credential,\n);\nfinal Session? session = res.session;\nfinal User? user = res.user;\n```\n"
}
]
},
{
"id": "auth-passkey-verifyregistration",
"$ref": "supabase_flutter.verifyRegistration",
"notes": "Completes the registration of a new passkey and returns the stored [`Passkey`](/docs/reference/dart/auth-passkey-api).\n",
"params": [
{
"name": "challengeId",
"isOptional": false,
"type": "String",
"description": "The challenge ID returned by `passkey.startRegistration()`."
},
{
"name": "credential",
"isOptional": false,
"type": "Map<String, dynamic>",
"description": "The credential created by the platform's passkey API, serialized in the W3C `RegistrationResponseJSON` format."
}
],
"examples": [
{
"id": "verify-passkey-registration",
"name": "Verify a passkey registration",
"isSpotlight": true,
"code": "```dart\nfinal Passkey passkey = await supabase.auth.passkey.verifyRegistration(\n challengeId: registration.challengeId,\n credential: credential,\n);\n```\n"
}
]
},
{
"id": "passkey-admin",
"title": "Passkey Admin",
"notes": "Contains passkey administration methods, accessed under the `supabase.auth.admin.passkey` namespace. Requires a `secret` key.\n\nPasskey support is a BETA feature and must be enabled for your project in the Supabase Dashboard under Authentication > Configuration > Passkeys.\n"
},
{
"id": "passkey-admin-deletepasskey",
"$ref": "supabase_flutter.deletePasskey",
"notes": "Deletes a passkey from a user.\n",
"params": [
{
"name": "userId",
"isOptional": false,
"type": "String",
"description": "User ID that owns the passkey."
},
{
"name": "passkeyId",
"isOptional": false,
"type": "String",
"description": "ID of the passkey to delete."
}
],
"examples": [
{
"id": "admin-delete-passkey",
"name": "Delete a user's passkey",
"isSpotlight": true,
"code": "```dart\nawait supabase.auth.admin.passkey.deletePasskey(\n userId: '11111111-1111-1111-1111-111111111111',\n passkeyId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',\n);\n```\n"
}
]
},
{
"id": "passkey-admin-listpasskeys",
"$ref": "supabase_flutter.listPasskeys",
"notes": "Returns the list of passkeys registered to the user with the given ID.\n",
"params": [
{
"name": "userId",
"isOptional": false,
"type": "String",
"description": "User ID whose passkeys should be returned."
}
],
"examples": [
{
"id": "admin-list-passkeys",
"name": "List a user's passkeys",
"isSpotlight": true,
"code": "```dart\nfinal List<Passkey> passkeys = await supabase.auth.admin.passkey.listPasskeys(\n userId: '11111111-1111-1111-1111-111111111111',\n);\n```\n"
}
]
},
{
"id": "functions-invoke",
"$ref": "supabase_flutter.invoke",
"description": "Invokes a Supabase Function. See the [guide](/docs/guides/functions) for details on writing Functions.\n",
"notes": "- Requires an Authorization header.\n- Invoke params generally match the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) spec.\n",
"params": [
{
"name": "functionName",
"isOptional": false,
"type": "String",
"description": "The name of the function to invoke."
},
{
"name": "headers",
"isOptional": true,
"type": "Map<String, String>",
"description": "Custom headers to send with the request."
},
{
"name": "body",
"isOptional": true,
"type": "Map<String, String>",
"description": "The body of the request."
},
{
"name": "method",
"isOptional": true,
"type": "HttpMethod",
"description": "HTTP method of the request. Defaults to POST."
}
],
"examples": [
{
"id": "basic-invocation",
"name": "Basic invocation.",
"isSpotlight": true,
"code": "```dart\nfinal res = await supabase.functions.invoke('hello', body: {'foo': 'baa'});\nfinal data = res.data;\n```\n"
},
{
"id": "parsing-custom-headers",
"name": "Parsing custom headers.",
"description": "Any `headers` will be passed through to the function. A common pattern is to pass a logged-in user's JWT token as an Authorization header.\n",
"isSpotlight": true,
"code": "```dart\nfinal res = await supabase.functions.invoke(\n 'hello',\n body: {'foo': 'baa'},\n headers: {\n 'Authorization': 'Bearer ${supabase.auth.currentSession?.accessToken}'\n },\n);\n```\n"
}
]
},
{
"id": "getchannels",
"$ref": "supabase_flutter.getChannels",
"description": "Returns all Realtime channels.\n",
"examples": [
{
"id": "get-all-channels",
"name": "Get all channels",
"isSpotlight": true,
"code": "```dart\nfinal channels = supabase.getChannels();\n```\n"
}
]
},
{
"id": "removeallchannels",
"$ref": "supabase_flutter.removeAllChannels",
"description": "Unsubscribes and removes all Realtime channels from Realtime client.\n",
"notes": "- Removing channels is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.\n",
"examples": [
{
"id": "remove-all-channels",
"name": "Remove all channels",
"isSpotlight": true,
"code": "```dart\nfinal statuses = await supabase.removeAllChannels();\n```\n"
}
]
},
{
"id": "removechannel",
"$ref": "supabase_flutter.removeChannel",
"description": "Unsubscribes and removes Realtime channel from Realtime client.\n",
"notes": "- Removing a channel is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.\n",
"examples": [
{
"id": "removes-a-channel",
"name": "Remove a channel",
"isSpotlight": true,
"code": "```dart\nfinal status = await supabase.removeChannel(channel);\n```\n"
}
]
},
{
"id": "stream",
"$ref": "supabase_flutter.stream",
"description": "Returns real-time data from your table as a `Stream`.\n",
"notes": "- Realtime is disabled by default for new tables. You can turn it on by [managing replication](/docs/guides/realtime/postgres-changes#replication-setup).\n- `stream()` will emit the initial data as well as any further change on the database as `Stream<List<Map<String, dynamic>>>` by combining Postgrest and Realtime.\n- Takes a list of primary key column names that will be used to update and delete the proper records within the SDK.\n- To use a private Realtime channel, pass `channelOptions: const RealtimeChannelConfig(private: true)` to the `stream()` call.\n- The following filters are available\n - `.eq('column', value)` listens to rows where the column equals the value\n - `.neq('column', value)` listens to rows where the column does not equal the value\n - `.gt('column', value)` listens to rows where the column is greater than the value\n - `.gte('column', value)` listens to rows where the column is greater than or equal to the value\n - `.lt('column', value)` listens to rows where the column is less than the value\n - `.lte('column', value)` listens to rows where the column is less than or equal to the value\n - `.inFilter('column', [val1, val2, val3])` listens to rows where the column is one of the values\n",
"examples": [
{
"id": "listen-to-table",
"name": "Listen to a table",
"isSpotlight": true,
"code": "```dart\nsupabase.from('countries')\n .stream(primaryKey: ['id'])\n .listen((List<Map<String, dynamic>> data) {\n // Do something awesome with the data\n});\n```\n"
},
{
"id": "with-filter-order-limit",
"name": "With filter, order and limit",
"code": "```dart\nsupabase.from('countries')\n .stream(primaryKey: ['id'])\n .eq('id', 120)\n .order('name')\n .limit(10);\n```\n"
},
{
"id": "with-in-filter",
"name": "With an IN filter",
"code": "```dart\nsupabase.from('countries')\n .stream(primaryKey: ['id'])\n .inFilter('id', [1, 2, 3])\n .order('name')\n .limit(10);\n```\n"
},
{
"id": "using-stream-with-stream-builder",
"name": "Using `stream()` with `StreamBuilder`",
"description": "When using `stream()` with a `StreamBuilder` within your Flutter application, make sure to store your stream in a variable to prevent refetching upon rebuilding.\n",
"code": "```dart\nfinal supabase = Supabase.instance.client;\n\nclass MyWidget extends StatefulWidget {\n const MyWidget({Key? key}) : super(key: key);\n\n @override\n State<MyWidget> createState() => _MyWidgetState();\n}\n\nclass _MyWidgetState extends State<MyWidget> {\n // Persist the stream in a local variable to prevent refetching upon rebuilds\n final _stream = supabase.from('countries').stream(primaryKey: ['id']);\n\n @override\n Widget build(BuildContext context) {\n return StreamBuilder(\n stream: _stream,\n builder: (context, snapshot) {\n // Return your widget with the data from the snapshot\n },\n );\n }\n}\n```\n"
}
]
},
{
"id": "subscribe",
"$ref": "supabase_flutter.subscribe",
"description": "Subscribe to realtime changes in your database.\n",
"notes": "- Realtime is disabled by default for new tables. You can turn it on by [managing replication](/docs/guides/realtime/postgres-changes#replication-setup).\n- If you want to receive the \"previous\" data for updates and deletes, you will need to set `REPLICA IDENTITY` to `FULL`, like this: `ALTER TABLE your_table REPLICA IDENTITY FULL;`\n",
"examples": [
{
"id": "listen-to-database-changes",
"name": "Listen to database changes",
"isSpotlight": true,
"code": "```dart\nsupabase\n .channel('public:countries')\n .onPostgresChanges(\n event: PostgresChangeEvent.all,\n schema: 'public',\n table: 'countries',\n callback: (payload) {\n print('Change received: ${payload.toString()}');\n })\n .subscribe();\n```\n"
},
{
"id": "listen-to-inserts",
"name": "Listen to inserts",
"code": "```dart\nsupabase\n .channel('public:countries')\n .onPostgresChanges(\n event: PostgresChangeEvent.insert,\n schema: 'public',\n table: 'countries',\n callback: (payload) {\n print('Change received: ${payload.toString()}');\n })\n .subscribe();\n```\n"
},
{
"id": "listen-to-updates",
"name": "Listen to updates",
"description": "By default, Supabase will send only the updated record. If you want to receive the previous values as well you can\nenable full replication for the table you are listening too:\n\n```sql\nalter table \"your_table\" replica identity full;\n```\n",
"code": "```dart\nsupabase\n .channel('public:countries')\n .onPostgresChanges(\n event: PostgresChangeEvent.update,\n schema: 'public',\n table: 'countries',\n callback: (payload) {\n print('Change received: ${payload.toString()}');\n })\n .subscribe();\n```\n"
},
{
"id": "listen-to-deletes",
"name": "Listen to deletes",
"description": "By default, Supabase does not send deleted records. If you want to receive the deleted record you can\nenable full replication for the table you are listening too:\n\n```sql\nalter table \"your_table\" replica identity full;\n```\n",
"code": "```dart\nsupabase\n .channel('public:countries')\n .onPostgresChanges(\n event: PostgresChangeEvent.delete,\n schema: 'public',\n table: 'countries',\n callback: (payload) {\n print('Change received: ${payload.toString()}');\n })\n .subscribe();\n```\n"
},
{
"id": "listen-to-multiple-events",
"name": "Listen to multiple events",
"description": "You can chain listeners if you want to listen to multiple events for each table.",
"code": "```dart\nsupabase\n .channel('public:countries')\n .onPostgresChanges(\n event: PostgresChangeEvent.insert,\n schema: 'public',\n table: 'countries',\n callback: (payload) {\n print('Insert event received: ${payload.toString()}');\n })\n .onPostgresChanges(\n event: PostgresChangeEvent.delete,\n schema: 'public',\n table: 'countries',\n callback: (payload) {\n print('Delete event received: ${payload.toString()}');\n })\n .subscribe();\n```\n"
},
{
"id": "listening-to-row-level-changes",
"name": "Listen to row level changes",
"description": "You can listen to individual rows by using the `filter` parameter passing a `PostgresChangeFilter` object with `PostgresChangeFilterType.eq` as `type`.",
"code": "```dart\nsupabase\n .channel('public:countries:id=eq.200')\n .onPostgresChanges(\n event: PostgresChangeEvent.delete,\n schema: 'public',\n table: 'countries',\n filter: PostgresChangeFilter(\n type: PostgresChangeFilterType.eq,\n column: 'id',\n value: 200,\n ),\n callback: (payload) {\n print('Change received: ${payload.toString()}');\n })\n .subscribe();\n```\n"
},
{
"id": "listen-to-broadcast",
"name": "Listen to broadcast messages",
"code": "```dart\nsupabase\n .channel('room1')\n .onBroadcast(\n event: 'cursor-pos',\n callback: (payload) {\n print('Cursor position received!: $payload');\n })\n .subscribe();\n```\n"
},
{
"id": "listen-to-presence-events",
"name": "Listen to presence events",
"code": "```dart\nfinal channel = supabase.channel('room1');\n\nchannel.onPresenceSync((payload) {\n print('Synced presence state: ${channel.presenceState()}');\n}).onPresenceJoin((payload) {\n print('Newly joined presences $payload');\n}).onPresenceLeave((payload) {\n print('Newly left presences: $payload');\n}).subscribe((status, error) async {\n if (status == RealtimeSubscribeStatus.subscribed) {\n await channel.track({'online_at': DateTime.now().toIso8601String()});\n }\n});\n```\n"
}
]
},
{
"id": "file-buckets",
"title": "File Buckets",
"notes": "This section contains methods for working with File Buckets.\n"
},
{
"id": "file-buckets-createbucket",
"$ref": "supabase_flutter.createBucket",
"description": "Creates a new Storage bucket\n",
"notes": "- Policy permissions required:\n - `buckets` permissions: `insert`\n - `objects` permissions: none\n- Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works\n",
"params": [
{
"name": "id",
"isOptional": false,
"type": "String",
"description": "A unique identifier for the bucket you are creating."
},
{
"name": "bucketOptions",
"isOptional": true,
"type": "BucketOptions",
"description": "A parameter to optionally make the bucket public.",
"subContent": [
{
"name": "public",
"isOptional": false,
"type": "bool",
"description": "The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations. By default, buckets are private."
},
{
"name": "fileSizeLimit",
"isOptional": true,
"type": "String",
"description": "Specifies the max file size in bytes that can be uploaded to this bucket. The global file size limit takes precedence over this value. The default value is null, which doesn't set a per bucket file size limit."
},
{
"name": "allowedMimeTypes",
"isOptional": true,
"type": "List<String>",
"description": "Specifies the allowed mime types that this bucket can accept during upload. The default value is null, which allows files with all mime types to be uploaded. Each mime type specified can be a wildcard, e.g. image/*, or a specific mime type, e.g. image/png."
}
]
}
],
"examples": [
{
"id": "create-bucket",
"name": "Create bucket",
"isSpotlight": true,
"code": "```dart\nfinal String bucketId = await supabase\n .storage\n .createBucket('avatars');\n```\n",
"response": "```json\n'avatars'\n```\n"
}
]
},
{
"id": "file-buckets-createsignedurl",
"$ref": "supabase_flutter.createSignedUrl",
"description": "Create signed url to download file without requiring permissions. This URL can be valid for a set number of seconds.\n",
"notes": "- Policy permissions required:\n - `buckets` permissions: none\n - `objects` permissions: `select`\n- Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works\n",
"params": [
{
"name": "path",
"isOptional": false,
"type": "String",
"description": "The file path, including the file name. For example folder/image.png."
},
{
"name": "expiresIn",
"isOptional": false,
"type": "int",
"description": "The number of seconds until the signed URL expires. For example, 60 for a URL which is valid for one minute."
},
{
"name": "transform",
"isOptional": true,
"type": "TransformOptions",
"description": "Transform the asset before serving it to the client.",
"subContent": [
{
"name": "width",
"isOptional": true,
"type": "int",
"description": "The width of the image in pixels."
},
{
"name": "height",
"isOptional": true,
"type": "int",
"description": "The height of the image in pixels."
},
{
"name": "resize",
"isOptional": true,
"type": "ResizeMode",
"description": "Specifies how image cropping should be handled when performing image transformations. Defaults to `ResizeMode.cover`."
},
{
"name": "quality",
"isOptional": true,
"type": "int",
"description": "Set the quality of the returned image. A number from 20 to 100, with 100 being the highest quality. Defaults to 80"
},
{
"name": "format",
"isOptional": true,
"type": "RequestImageFormat",
"description": "Specify the format of the image requested. When using 'origin' we force the format to be the same as the original image. When this option is not passed in, images are optimized to modern image formats like Webp."
}
]
}
],
"examples": [
{
"id": "create-signed-url",
"name": "Create Signed URL",
"isSpotlight": true,
"code": "```dart\nfinal String signedUrl = await supabase\n .storage\n .from('avatars')\n .createSignedUrl('avatar1.png', 60);\n```\n"
},
{
"id": "create-signed-url-with-transform",
"name": "With transform",
"code": "```dart\nfinal String signedUrl = await supabase\n .storage\n .from('avatars')\n .createSignedUrl(\n 'avatar1.png',\n 60,\n transform: TransformOptions(\n width: 200,\n height: 200,\n ),\n );\n```\n",
"response": "```json\n'https://example.supabase.co/storage/v1/object/sign/avatars/folder/avatar1.png?token=<TOKEN>''\n```\n"
}
]
},
{
"id": "file-buckets-deletebucket",
"$ref": "supabase_flutter.deleteBucket",
"description": "Deletes an existing bucket. A bucket can't be deleted with existing objects inside it. You must first `empty()` the bucket.\n",
"notes": "- Policy permissions required:\n - `buckets` permissions: `select` and `delete`\n - `objects` permissions: none\n- Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works\n",
"params": [
{
"name": "id",
"isOptional": false,
"type": "String",
"description": "A unique identifier for the bucket you are deleting."
}
],
"examples": [
{
"id": "delete-bucket",
"name": "Delete bucket",
"isSpotlight": true,
"code": "```dart\nfinal String res = await supabase\n .storage\n .deleteBucket('avatars');\n```\n",
"response": "```json\n'Successfully deleted'\n```\n"
}
]
},
{
"id": "file-buckets-download",
"$ref": "supabase_flutter.download",
"description": "Downloads a file.\n",
"notes": "- Policy permissions required:\n - `buckets` permissions: none\n - `objects` permissions: `select`\n- Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works\n",
"params": [
{
"name": "path",
"isOptional": false,
"type": "String",
"description": "The full path and file name of the file to be downloaded. For example folder/image.png."
},
{
"name": "transform",
"isOptional": true,
"type": "TransformOptions",
"description": "Transform the asset before serving it to the client.",
"subContent": [
{
"name": "width",
"isOptional": true,
"type": "int",
"description": "The width of the image in pixels."
},
{
"name": "height",
"isOptional": true,
"type": "int",
"description": "The height of the image in pixels."
},
{
"name": "resize",
"isOptional": true,
"type": "ResizeMode",
"description": "Specifies how image cropping should be handled when performing image transformations. Defaults to `ResizeMode.cover`."
},
{
"name": "quality",
"isOptional": true,
"type": "int",
"description": "Set the quality of the returned image. A number from 20 to 100, with 100 being the highest quality. Defaults to 80"
},
{
"name": "format",
"isOptional": true,
"type": "RequestImageFormat",
"description": "Specify the format of the image requested. When using 'origin' we force the format to be the same as the original image. When this option is not passed in, images are optimized to modern image formats like Webp."
}
]
}
],
"examples": [
{
"id": "download-file",
"name": "Download file",
"isSpotlight": true,
"code": "```dart\nfinal Uint8List file = await supabase\n .storage\n .from('avatars')\n .download('avatar1.png');\n```\n",
"response": "```json\n<Blob>\n```\n"
},
{
"id": "download-file-with-transform",
"name": "With transform",
"isSpotlight": true,
"code": "```dart\nfinal Uint8List file = await supabase\n .storage\n .from('avatars')\n .download(\n 'avatar1.png',\n transform: TransformOptions(\n width: 200,\n height: 200,\n ),\n );\n```\n",
"response": "```json\n<Blob>\n```\n"
}
]
},
{
"id": "file-buckets-emptybucket",
"$ref": "supabase_flutter.emptyBucket",
"description": "Removes all objects inside a single bucket.\n",
"notes": "- Policy permissions required:\n - `buckets` permissions: `select`\n - `objects` permissions: `select` and `delete`\n- Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works\n",
"params": [
{
"name": "id",
"isOptional": false,
"type": "String",
"description": "A unique identifier for the bucket you are emptying."
}
],
"examples": [
{
"id": "empty-bucket",
"name": "Empty bucket",
"isSpotlight": true,
"code": "```dart\nfinal String res = await supabase\n .storage\n .emptyBucket('avatars');\n```\n",
"response": "```json\n'Successfully emptied'\n```\n"
}
]
},
{
"id": "file-buckets-getbucket",
"$ref": "supabase_flutter.getBucket",
"description": "Retrieves the details of an existing Storage bucket.\n",
"notes": "- Policy permissions required:\n - `buckets` permissions: `select`\n - `objects` permissions: none\n- Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works\n",
"params": [
{
"name": "id",
"isOptional": false,
"type": "String",
"description": "The unique identifier of the bucket you would like to retrieve."
}
],
"examples": [
{
"id": "get-bucket",
"name": "Get bucket",
"isSpotlight": true,
"code": "```dart\nfinal Bucket bucket = await supabase\n .storage\n .getBucket('avatars');\n```\n",
"response": "```json\nBucket(\n id: 'avatars',\n name: 'avatars',\n owner: '',\n public: false,\n file_size_limit: 1024,\n allowed_mime_types: [\n 'image/png'\n ],\n created_at: '2024-05-22T22:26:05.100Z',\n updated_at: '2024-05-22T22:26:05.100Z'\n)\n```\n"
}
]
},
{
"id": "file-buckets-getpublicurl",
"$ref": "supabase_flutter.getPublicUrl",
"description": "Retrieve URLs for assets in public buckets\n",
"notes": "- The bucket needs to be set to public, either via [updateBucket()](/docs/reference/dart/storage-updatebucket) or by going to Storage on [supabase.com/dashboard](https://supabase.com/dashboard), clicking the overflow menu on a bucket and choosing \"Make public\"\n- Policy permissions required:\n - `buckets` permissions: none\n - `objects` permissions: none\n- Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works\n",
"params": [
{
"name": "path",
"isOptional": false,
"type": "String",
"description": "The path and name of the file to generate the public URL for. For example folder/image.png."
},
{
"name": "transform",
"isOptional": true,
"type": "TransformOptions",
"description": "Transform the asset before serving it to the client.",
"subContent": [
{
"name": "width",
"isOptional": true,
"type": "int",
"description": "The width of the image in pixels."
},
{
"name": "height",
"isOptional": true,
"type": "int",
"description": "The height of the image in pixels."
},
{
"name": "resize",
"isOptional": true,
"type": "ResizeMode",
"description": "Specifies how image cropping should be handled when performing image transformations. Defaults to `ResizeMode.cover`."
},
{
"name": "quality",
"isOptional": true,
"type": "int",
"description": "Set the quality of the returned image. A number from 20 to 100, with 100 being the highest quality. Defaults to 80"
},
{
"name": "format",
"isOptional": true,
"type": "RequestImageFormat",
"description": "Specify the format of the image requested. When using 'origin' we force the format to be the same as the original image. When this option is not passed in, images are optimized to modern image formats like Webp."
}
]
}
],
"examples": [
{
"id": "returns-the-url-for-an-asset-in-a-public-bucket",
"name": "Returns the URL for an asset in a public bucket",
"isSpotlight": true,
"code": "```dart\nfinal String publicUrl = supabase\n .storage\n .from('public-bucket')\n .getPublicUrl('avatar1.png');\n```\n",
"response": "```json\n'https://example.supabase.co/storage/v1/object/public/public-bucket/folder/avatar1.png'\n```\n"
},
{
"id": "returns-the-url-for-an-asset-in-a-public-bucket-with-transform",
"name": "With transform",
"isSpotlight": true,
"code": "```dart\nfinal String publicUrl = await supabase\n .storage\n .from('public-bucket')\n .getPublicUrl(\n 'avatar1.png',\n transform: TransformOptions(\n width: 200,\n height: 200,\n ),\n );\n```\n",
"response": "```json\n'https://example.supabase.co/storage/v1/object/public/public-bucket/folder/avatar1.png'\n```\n"
}
]
},
{
"id": "file-buckets-list",
"$ref": "supabase_flutter.list",
"description": "Lists all the files within a bucket.\n",
"notes": "- Policy permissions required:\n - `buckets` permissions: none\n - `objects` permissions: `select`\n- Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works\n",
"params": [
{
"name": "path",
"isOptional": false,
"type": "String",
"description": "The folder path."
},
{
"name": "searchOptions",
"isOptional": true,
"type": "SearchOptions",
"description": "Options for the search operations such as limit and offset.",
"subContent": [
{
"name": "limit",
"isOptional": true,
"type": "int",
"description": "The number of files you want to be returned."
},
{
"name": "offset",
"isOptional": true,
"type": "int",
"description": "The starting position."
},
{
"name": "sortBy",
"isOptional": true,
"type": "SortBy",
"description": "The column to sort by. Can be any column inside a FileObject.",
"subContent": [
{
"name": "column",
"isOptional": true,
"type": "String"
},
{
"name": "order",
"isOptional": true,
"type": "String"
}
]
},
{
"name": "search",
"isOptional": true,
"type": "String",
"description": "The search string to filter files by."
}
]
}
],
"examples": [
{
"id": "list-files-in-a-bucket",
"name": "List files in a bucket",
"isSpotlight": true,
"code": "```dart\nfinal List<FileObject> objects = await supabase\n .storage\n .from('avatars')\n .list();\n```\n",
"response": "```json\n[\n FileObject(\n name: 'avatar1.png',\n id: 'e668cf7f-821b-4a2f-9dce-7dfa5dd1cfd2',\n updated_at: '2024-05-22T23:06:05.580Z',\n created_at: '2024-05-22T23:04:34.443Z',\n last_accessed_at: '2024-05-22T23:04:34.443Z',\n metadata: {\n eTag: 'c5e8c553235d9af30ef4f6e280790b92',\n size: 32175,\n mimetype: 'image/png',\n cacheControl: 'max-age=3600',\n lastModified: '2024-05-22T23:06:05.574Z',\n contentLength: 32175,\n httpStatusCode: 200\n ),\n]\n```\n"
}
]
},
{
"id": "file-buckets-listbuckets",
"$ref": "supabase_flutter.listBuckets",
"description": "Retrieves the details of all Storage buckets within an existing product.\n",
"notes": "- Policy permissions required:\n - `buckets` permissions: `select`\n - `objects` permissions: none\n- Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works\n",
"examples": [
{
"id": "list-buckets",
"name": "List buckets",
"isSpotlight": true,
"code": "```dart\nfinal List<Bucket> buckets = await supabase\n .storage\n .listBuckets();\n```\n",
"response": "```json\n[\n Bucket(\n id: 'avatars',\n name: 'avatars',\n owner: '',\n public: false,\n file_size_limit: 1024,\n allowed_mime_types: [\n 'image/png'\n ],\n created_at: '2024-05-22T22:26:05.100Z',\n updated_at: '2024-05-22T22:26:05.100Z'\n ),\n]\n```\n"
}
]
},
{
"id": "file-buckets-move",
"$ref": "supabase_flutter.move",
"description": "Moves an existing file, optionally renaming it at the same time.\n",
"notes": "- Policy permissions required:\n - `buckets` permissions: none\n - `objects` permissions: `update` and `select`\n- Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works\n",
"params": [
{
"name": "fromPath",
"isOptional": false,
"type": "String",
"description": "The original file path, including the current file name. For example folder/image.png."
},
{
"name": "toPath",
"isOptional": false,
"type": "String",
"description": "The new file path, including the new file name. For example folder/image-new.png."
}
],
"examples": [
{
"id": "move-file",
"name": "Move file",
"isSpotlight": true,
"code": "```dart\nfinal String result = await supabase\n .storage\n .from('avatars')\n .move('public/avatar1.png', 'private/avatar2.png');\n```\n",
"response": "```json\n'Successfully moved'\n```\n"
}
]
},
{
"id": "file-buckets-remove",
"$ref": "supabase_flutter.remove",
"description": "Deletes files within the same bucket\n",
"notes": "- Policy permissions required:\n - `buckets` permissions: none\n - `objects` permissions: `delete` and `select`\n- Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works\n",
"params": [
{
"name": "paths",
"isOptional": false,
"type": "List<String>",
"description": "A list of files to delete, including the path and file name. For example ['folder/image.png']."
}
],
"examples": [
{
"id": "delete-file",
"name": "Delete file",
"isSpotlight": true,
"code": "```dart\nfinal List<FileObject> objects = await supabase\n .storage\n .from('avatars')\n .remove(['avatar1.png']);\n```\n",
"response": "```json\n[\n FileObject(\n name: 'avatar1.png',\n id: 'e668cf7f-821b-4a2f-9dce-7dfa5dd1cfd2',\n updated_at: '2024-05-22T23:06:05.580Z',\n created_at: '2024-05-22T23:04:34.443Z',\n last_accessed_at: '2024-05-22T23:04:34.443Z',\n metadata: {\n eTag: 'c5e8c553235d9af30ef4f6e280790b92',\n size: 32175,\n mimetype: 'image/png',\n cacheControl: 'max-age=3600',\n lastModified: '2024-05-22T23:06:05.574Z',\n contentLength: 32175,\n httpStatusCode: 200\n ),\n]\n```\n"
}
]
},
{
"id": "file-buckets-update",
"$ref": "supabase_flutter.update",
"description": "Replaces an existing file at the specified path with a new one.\n",
"notes": "- Policy permissions required:\n - `buckets` permissions: none\n - `objects` permissions: `update` and `select`\n- Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works\n",
"params": [
{
"name": "path",
"isOptional": false,
"type": "String",
"description": "The relative file path. Should be of the format folder/subfolder/filename.png. The bucket must already exist before attempting to update."
},
{
"name": "file",
"isOptional": false,
"type": "File or Uint8List",
"description": "File object to be stored in the bucket."
},
{
"name": "fileOptions",
"isOptional": true,
"type": "FileOptions",
"subContent": [
{
"name": "cacheControl",
"isOptional": true,
"type": "String",
"description": "The number of seconds the asset is cached in the browser and in the Supabase CDN. This is set in the `Cache-Control` header as `max-age=<seconds>`. Defaults to 3600 seconds."
},
{
"name": "upsert",
"isOptional": true,
"type": "bool",
"description": "When upsert is set to true, the file is overwritten if it exists. When set to false, an error is thrown if the object already exists. Defaults to false."
},
{
"name": "contentType",
"isOptional": true,
"type": "String",
"description": "The `Content-Type` header value. Gets parsed with MediaType.parse(mime). Throws a FormatError if the media type is invalid."
}
]
},
{
"name": "retryAttempts",
"isOptional": true,
"type": "int",
"description": "Sets the retryAttempts parameter set across the storage client. Defaults to 10."
},
{
"name": "retryController",
"isOptional": true,
"type": "StorageRetryController",
"description": "Pass a RetryController instance and call `cancel()` to cancel the retry attempts."
}
],
"examples": [
{
"id": "update-file",
"name": "Update file",
"isSpotlight": true,
"code": "```dart\nfinal avatarFile = File('path/to/local/file');\nfinal String path = await supabase.storage.from('avatars').update(\n 'public/avatar1.png',\n avatarFile,\n fileOptions: const FileOptions(cacheControl: '3600', upsert: false),\n );\n```\n",
"response": "```json\n'avatars/public/avatar1.png'\n```\n"
},
{
"id": "update-file-on-web",
"name": "Update file on web",
"code": "```dart\nfinal Uint8List avatarFile = file.bytes;\nfinal String path = await supabase.storage.from('avatars').updateBinary(\n 'public/avatar1.png',\n avatarFile,\n fileOptions: const FileOptions(cacheControl: '3600', upsert: false),\n );\n```\n",
"response": "```json\n'avatars/public/avatar1.png'\n```\n"
}
]
},
{
"id": "file-buckets-updatebucket",
"$ref": "supabase_flutter.updateBucket",
"description": "Updates a new Storage bucket\n",
"notes": "- Policy permissions required:\n - `buckets` permissions: `update`\n - `objects` permissions: none\n- Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works\n",
"params": [
{
"name": "id",
"isOptional": false,
"type": "String",
"description": "A unique identifier for the bucket you are updating."
},
{
"name": "bucketOptions",
"isOptional": false,
"type": "BucketOptions",
"description": "A parameter to optionally make the bucket public.",
"subContent": [
{
"name": "public",
"isOptional": false,
"type": "bool",
"description": "The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations. By default, buckets are private."
},
{
"name": "fileSizeLimit",
"isOptional": true,
"type": "String",
"description": "Specifies the max file size in bytes that can be uploaded to this bucket. The global file size limit takes precedence over this value. The default value is null, which doesn't set a per bucket file size limit."
},
{
"name": "allowedMimeTypes",
"isOptional": true,
"type": "List<String>",
"description": "Specifies the allowed mime types that this bucket can accept during upload. The default value is null, which allows files with all mime types to be uploaded. Each mime type specified can be a wildcard, e.g. image/*, or a specific mime type, e.g. image/png."
}
]
}
],
"examples": [
{
"id": "update-bucket",
"name": "Update bucket",
"isSpotlight": true,
"code": "```dart\nfinal String res = await supabase\n .storage\n .updateBucket('avatars', const BucketOptions(public: false));\n```\n",
"response": "```json\n'Successfully updated'\n```\n"
}
]
},
{
"id": "file-buckets-upload",
"$ref": "supabase_flutter.upload",
"description": "Uploads a file to an existing bucket.\n",
"notes": "- Policy permissions required:\n - `buckets` permissions: none\n - `objects` permissions: `insert`\n- Refer to the [Storage guide](https://supabase.com/docs/guides/storage/security/access-control) on how access control works\n",
"params": [
{
"name": "path",
"isOptional": false,
"type": "String",
"description": "The relative file path. Should be of the format folder/subfolder/filename.png. The bucket must already exist before attempting to update."
},
{
"name": "file",
"isOptional": false,
"type": "File or Uint8List",
"description": "File object to be stored in the bucket."
},
{
"name": "fileOptions",
"isOptional": true,
"type": "FileOptions",
"subContent": [
{
"name": "cacheControl",
"isOptional": true,
"type": "String",
"description": "The number of seconds the asset is cached in the browser and in the Supabase CDN. This is set in the `Cache-Control` header as `max-age=<seconds>`. Defaults to 3600 seconds."
},
{
"name": "upsert",
"isOptional": true,
"type": "bool",
"description": "When upsert is set to true, the file is overwritten if it exists. When set to false, an error is thrown if the object already exists. Defaults to false."
},
{
"name": "contentType",
"isOptional": true,
"type": "String",
"description": "The `Content-Type` header value. Gets parsed with MediaType.parse(mime). Throws a FormatError if the media type is invalid."
}
]
},
{
"name": "retryAttempts",
"isOptional": true,
"type": "int",
"description": "Sets the retryAttempts parameter set across the storage client. Defaults to 10."
},
{
"name": "retryController",
"isOptional": true,
"type": "StorageRetryController",
"description": "Pass a RetryController instance and call `cancel()` to cancel the retry attempts."
}
],
"examples": [
{
"id": "upload-file",
"name": "Upload file",
"isSpotlight": true,
"code": "```dart\nfinal avatarFile = File('path/to/file');\nfinal String fullPath = await supabase.storage.from('avatars').upload(\n 'public/avatar1.png',\n avatarFile,\n fileOptions: const FileOptions(cacheControl: '3600', upsert: false),\n );\n```\n",
"response": "```json\n'avatars/public/avatar1.png'\n```\n"
},
{
"id": "upload-file-on-web",
"name": "Upload file on web",
"code": "```dart\nfinal Uint8List avatarFile = file.bytes;\nfinal String fullPath = await supabase.storage.from('avatars').uploadBinary(\n 'public/avatar1.png',\n avatarFile,\n fileOptions: const FileOptions(cacheControl: '3600', upsert: false),\n );\n```\n",
"response": "```json\n'avatars/public/avatar1.png'\n```\n"
}
]
}
],
"typeSpec": {
"methods": {},
"variables": {}
}
}
Reference in New Issue View Git Blame Copy Permalink