Home

Python Client Library

@supabase-community/supabase-py

This reference documents every object and method available in the supabase-py library from the Supabase community. You can use supabase-py to test with your Postgres database, listen to database changes, invoke Deno Edge Functions, build login and user management functionality, and manage large files.

The Python client library is created and maintained by the Supabase community, and is not an official library. Please be tolerant of areas where the library is still being developed, and — as with all the libraries — feel free to contribute wherever you find issues.

Huge thanks to official maintainers, anand2312, dreinon, J0, and Leynier.

Shoutout to timkpaine for maintaining our Conda libraries as well.

Installing

Install with PyPi#

You can install supabase-py via the terminal. (for > Python 3.7)

Terminal

_10
pip install supabase

Initializing

You can initialize a new Supabase client using the create_client() method.

The Supabase client is your entrypoint to the rest of the Supabase functionality and is the easiest way to interact with everything we offer within the Supabase ecosystem.


import os
from supabase import create_client, Client

url: str = os.environ.get("SUPABASE_URL")
key: str = os.environ.get("SUPABASE_KEY")
supabase: Client = create_client(url, key)

Fetch data

  • By default, Supabase projects return a maximum of 1,000 rows. This setting can be changed in your project's API settings. It's recommended that you keep it low to limit the payload size of accidental or malicious requests.
  • apikey is a reserved keyword if you're using the Supabase Platform and should be avoided as a column name.

response = supabase.table('countries').select("*").execute()

Insert data


data, count = supabase.table('countries')
  .insert({"id": 1, "name": "Denmark"})
  .execute()

Update data

  • update() should always be combined with Filters to target the item(s) you wish to update.

data, count = supabase.table('countries')
  .update({'name': 'Austrailia'})
  .eq('id', 1)
  .execute()

Upsert data

  • Primary keys must be included in the values dict to use upsert.

data, count = supabase.table('countries')
  .upsert({'id': 1, 'name': 'Austrailia'})
  .execute()

Delete data

  • delete() should always be combined with filters to target the item(s) you wish to delete.
  • 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.

data, count = supabase.table('countries')
  .delete()
  .eq('id', 1)
  .execute()

Using filters

Filters allow you to only return rows that match certain conditions.

Filters can be used on select(), update(), upsert(), and delete() queries.

If a Postgres function returns a table response, you can also apply filters.


# Correct
data, count = supabase.from('cities')
  .select('name, country_id')
  .eq('name', 'The Shire')
  .execute()

# Incorrect
data, count = supabase.table('cities')
  .eq('name', 'The Shire')
  .select('name, country_id')
  .execute()

Column is equal to a value


data, count = supabase.table('countries')
  .select('*')
  .eq('name', 'Albania')
  .execute()

Column is not equal to a value


  data, count = supabase.table('countries')
    .select('*')
    .neq('name', 'Albania')
    .execute()

Column is greater than a value


data, count = supabase.table('countries')
    .select('*')
    .gt('id', 2)
    .execute()

Column is greater than or equal to a value


data, count = supabase.table('countries')
  .select('*')
  .gte('id', 2)
  .execute()

Column is less than a value


data, count = supabase.table('countries')
  .select('*')
  .lt('id', 2)
  .execute()

Column is less than or equal to a value


data, count = supabase.table('countries')
  .select('*')
  .lte('id', 2)
  .execute()

Column matches a pattern


data, count = supabase.table('countries')
  .select('*')
  .like('name', '%Alba%')
  .execute()

Column matches a case-insensitive pattern


data, count = supabase.table('countries')
    .select('*')
    .ilike('name', '%alba%')
    .execute()

Column is a value


data, count = supabase.table('countries')
  .select('*')
  .is_('name', 'null')
  .execute()

Column is in an array


data, count = supabase.table('countries')
    .select('*')
    .in_('name', ['Albania', 'Algeria'])
    .execute()

Column contains every element in a value


  data, count = supabase.table('issues')
    .select('*')
    .contains('tags', ['is:open', 'priority:low'])
    .execute()

Contained by value


data, count = supabase.table('classes')
  .select('name')
  .contained_by('days', ['monday', 'tuesday', 'wednesday', 'friday'])
  .execute()

Match an associated value


data, count = supabase.table('countries')
    .select('*')
    .match({'id': 2, 'name': 'Albania'})
    .execute()

Don't match the filter


data, count = supabase.table('countries')
    .select('*')
    .not_.is_('name', 'null')
    .execute()

Match the filter

filter() expects you to use the raw PostgREST syntax for the filter values.


data, count = supabase.table('countries')
    .select('*')
    .filter('name', 'in', '("Algeria","Japan")')
    .execute()

Using modifiers

Filters work on the row level—they allow you to return rows that only match certain conditions without changing the shape of the rows. Modifiers are everything that don't fit that definition—allowing you to change the format of the response (e.g., returning a CSV string).

Modifiers must be specified after filters. Some modifiers only apply for queries that return rows (e.g., select() or rpc() on a function that returns a table response).

Order the results


data, count = supabase.table('countries')
  .select('*')
  .order('name', desc=True)
  .execute()

Limit the number of rows returned


data, count = supabase.table('countries')
  .select('*')
  .limit(1)
  .execute()

Retrieve one row of data


data, count = supabase.table('countries')
  .select('name')
  .limit(1)
  .single()
  .execute()

Retrieve zero or one row of data


data, count = supabase.table('countries')
  .select('*')
  .eq('name', 'Albania')
  .maybe_single()
  .execute()

Create a new user

  • By default, the user needs to verify their email address before logging in. To turn this off, disable Confirm email in your project.
  • Confirm email determines if users need to confirm their email address after signing up.
    • If Confirm email is enabled, a user is returned but session is null.
    • If Confirm email is disabled, both a user and a session are returned.
  • By default, when the user confirms their email address, they are redirected to the SITE_URL. You can modify your SITE_URL or add additional redirect URLs in your project.
  • If sign_up() is called for an existing confirmed user:
    • If Confirm email is enabled in your project, an obfuscated/fake user object is returned.
    • If Confirm email is disabled, the error message, User already registered is returned.
  • To fetch the currently logged-in user, refer to getUser().

res = supabase.auth.sign_up({
  "email": 'example@email.com',
  "password": 'example-password',
})

Sign in a user

  • Requires either an email and password or a phone number and password.

data = supabase.auth.sign_in_with_password({"email": "j0@supabase.io", "password": "testsupabasenow"})

Sign in a user through OTP

  • Requires either an email or phone number.
  • This method is used for passwordless sign-ins where a OTP is sent to the user's email or phone number.
  • If the user doesn't exist, sign_in_with_otp() will signup the user instead. To restrict this behavior, you can set should_create_user in SignInWithPasswordlessCredentials.options to false.
  • If you're using an email, you can configure whether you want the user to receive a magiclink or a OTP.
  • If you're using phone, you can configure whether you want the user to receive a OTP.
  • The magic link's destination URL is determined by the SITE_URL.
  • See redirect URLs and wildcards to add additional redirect URLs to your project.
  • Magic links and OTPs share the same implementation. To send users a one-time code instead of a magic link, modify the magic link email template to include {{ .Token }} instead of {{ .ConfirmationURL }}.

data = supabase.auth.sign_in_with_otp({
  "email": 'example@email.com',
  "options": {
    "email_redirect_to": 'https://example.com/welcome'
  }
})

Sign in a user through OAuth

  • This method is used for signing in using a third-party provider.
  • Supabase supports many different third-party providers.

data = supabase.auth.sign_in_with_oauth({
  "provider": 'github'
})

Sign out a user

  • In order to use the signOut() method, the user needs to be signed in first.

res = supabase.auth.sign_out()

Verify and log in through OTP

  • The verify_otp 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: signup, magiclink, recovery, invite or email_change.
  • The verification type used should be determined based on the corresponding auth method called before verify_otp to sign up / sign-in a user.

res = supabase.auth.verify_otp(phone, token)

Retrieve a session


res = supabase.auth.get_session()

Retrieve a new session

  • This method will refresh the session whether the current one is expired or not.
  • Both examples destructure user and session from data. This is not required; so const { data, error } = is also valid.

res = supabase.auth.refresh_session()

Retrieve a user

  • This method gets the user object from the current session.
  • Fetches the user object from the database instead of local session.

data = supabase.auth.get_user()

Set the session data

  • setSession() takes in a refresh token and uses it to get a new session.
  • The refresh token can only be used once to obtain a new session.
  • Refresh token rotation is enabled by default on all projects to guard against replay attacks.
  • You can configure the 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.
  • If you are using React Native, you will need to install a Buffer polyfill via a library such as rn-nodeify to properly use the library.

res = supabase.auth.set_session(access_token, refresh_token)

Invokes a Supabase Edge Function.

Invoke a Supabase Function.

  • Requires an Authorization header.
  • When you pass in a body to your function, we automatically attach the Content-Type header for Blob, ArrayBuffer, File, FormData and String. If it doesn't match any of these types we assume the payload is json, serialise it and attach the Content-Type header as application/json. You can override this behaviour by passing in a Content-Type header of your own.

resp = supabase.functions.invoke(
  "hello-world",
  invoke_options={
    "body": { "foo": "bar" }
  },
)

Create a bucket

  • RLS policy permissions required:
    • buckets table permissions: insert
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

res = supabase.storage.create_bucket(name)

Retrieve a bucket

  • RLS policy permissions required:
    • buckets table permissions: select
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

res = supabase.storage.get_bucket(name)

List all buckets

  • RLS policy permissions required:
    • buckets table permissions: select
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

res = supabase.storage.list_buckets()

Delete a bucket

  • RLS policy permissions required:
    • buckets table permissions: select and delete
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

res = supabase.storage.delete_bucket(name)

Empty a bucket

  • RLS policy permissions required:
    • buckets table permissions: select
    • objects table permissions: select and delete
  • Refer to the Storage guide on how access control works

res = supabase.storage.empty_bucket(name)

Upload a file

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: insert
  • Refer to the Storage guide on how access control works
  • Please specify the appropriate content MIME type if you are uploading images or audio. If no file_options are specified, the MIME type defaults to text/html.

with open(filepath, 'rb') as f:
    supabase.storage.from_("testbucket").upload(file=f,path=path_on_supastorage, file_options={"content-type": "audio/mpeg"})

Download a file

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: select
  • Refer to the Storage guide on how access control works

with open(destination, 'wb+') as f:
  res = supabase.storage.from_('bucket_name').download(source)
  f.write(res)

List all files in a bucket

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: select
  • Refer to the Storage guide on how access control works

res = supabase.storage.from_('bucket_name').list()

Replace an existing file

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: update and select
  • Refer to the Storage guide on how access control works

with open(filepath, 'rb') as f:
  supabase.storage.from_("bucket_name").update(file=f, path=path_on_supastorage, file_options={"cache-control": "3600", "upsert": "true"})

Move an existing file

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: update and select
  • Refer to the Storage guide on how access control works

res = supabase.storage.from_('bucket_name').move('public/avatar1.png', 'private/avatar2.png')

Delete files in a bucket

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: delete and select
  • Refer to the Storage guide on how access control works

res = supabase.storage.from_('bucket_name').remove('test.jpg')

Create a signed URL

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: select
  • Refer to the Storage guide on how access control works

res = supabase.storage.from_('bucket_name').create_signed_url(filepath, expiry_duration)

Retrieve public URL

  • The bucket needs to be set to public, either via updateBucket() or by going to Storage on supabase.com/dashboard, clicking the overflow menu on a bucket and choosing "Make public"
  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

res = supabase.storage.from_('bucket_name').get_public_url('test/avatar1.jpg')

Release Notes

The community is actively working on the library and we will be upgrading the Authentication library, gotrue-py, to mirror the Supabase-js v2 lib.

Storage Transformations#

We currently support image transformations in our storage library.

© Supabase Inc—ContributingAuthor StyleguideOpen SourceSupaSquad