{"id":22312985,"url":"https://github.com/supabase-community/supabase-ex","last_synced_at":"2025-05-16T13:06:54.737Z","repository":{"id":192718756,"uuid":"686773153","full_name":"supabase-community/supabase-ex","owner":"supabase-community","description":"A complete Toolkit to interact with Supabase APIs from Elixir","archived":false,"fork":false,"pushed_at":"2025-05-02T14:26:52.000Z","size":2146,"stargazers_count":138,"open_issues_count":6,"forks_count":7,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-05T01:43:11.101Z","etag":null,"topics":["hacktoberfest","sdk-elixir","supabase","supabase-elixir"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/supabase_potion","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/supabase-community.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-03T22:18:52.000Z","updated_at":"2025-05-02T14:24:53.000Z","dependencies_parsed_at":null,"dependency_job_id":"7be3ced5-65c0-41ba-a49c-ef404c2e998a","html_url":"https://github.com/supabase-community/supabase-ex","commit_stats":{"total_commits":34,"total_committers":3,"mean_commits":"11.333333333333334","dds":0.05882352941176472,"last_synced_commit":"b7bfe786a62f9a0ac1b5676ea4f1aa390116818b"},"previous_names":["zoedsoupe/supabase","supabase-community/supabase-ex","zoedsoupe/supabase-ex"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supabase-community%2Fsupabase-ex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supabase-community%2Fsupabase-ex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supabase-community%2Fsupabase-ex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supabase-community%2Fsupabase-ex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/supabase-community","download_url":"https://codeload.github.com/supabase-community/supabase-ex/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252425280,"owners_count":21745848,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","sdk-elixir","supabase","supabase-elixir"],"created_at":"2024-12-03T22:01:00.689Z","updated_at":"2025-05-16T13:06:54.731Z","avatar_url":"https://github.com/supabase-community.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Supabase Potion\n\nWhere the magic starts!\n\n\u003e [!WARNING]\n\u003e This project is still in high development, expect breaking changes and unexpected behaviour.\n\n## Getting Started\n\n### Examples\n\nThis repository contains a few examples with sample apps to help you get started and showcase each usage of the client implementations:\n\n#### Gotrue/Auth examples\n\nTODO\n\n\u003c!--\n- [Plug based auth](https://github.com/zoedsoupe/supabase-ex/tree/main/examples/auth/plug)\n- [Phoenix LiveView based auth](https://github.com/zoedsoupe/supabase-ex/tree/main/examples/auth/phoenix_live_view)\n- [User management](https://github.com/zoedsoupe/supabase-ex/tree/main/examples/auth/user_management)\n--\u003e\n\n#### Storage examples\n\nTODO\n\n\u003c!--\n- [Plug based upload](https://github.com/zoedsoupe/supabase-ex/tree/main/examples/storage/plug)\n- [Phoenix LiveView upload](https://github.com/zoedsoupe/supabase-ex/tree/main/examples/storage/phoenix_live_view)\n--\u003e\n\n### Installation\n\nTo install the base SDK:\n\n```elixir\ndef deps do\n  [\n    {:supabase_potion, \"~\u003e 0.5\"}\n  ]\nend\n```\n\n### General usage\n\nThis library per si is the base foundation to user Supabase services from Elixir, so to integrate with specific services you need to add each client library you want to use.\n\nAvailable client services are:\n- [PostgREST](https://github.com/supabase-community/postgres-ex)\n- [Storage](https://github.com/supabase-community/storage-ex)\n- [Auth/GoTrue](https://github.com/supabase-community/auth-ex)\n\nSo if you wanna use the Storage and Auth/GoTrue services, your `mix.exs` should look like that:\n\n```elixir\ndef deps do\n  [\n    {:supabase_potion, \"~\u003e 0.6\"}, # base SDK\n    {:supabase_storage, \"~\u003e 0.4\"}, # storage integration\n    {:supabase_gotrue, \"~\u003e 0.4\"}, # auth integration\n    {:supabase_postgrest, \"~\u003e 1.0\"}, # postgrest integration\n  ]\nend\n```\n\n\n### Clients\n\nA `Supabase.Client` holds general information about Supabase, that can be used to intereact with any of the children integrations, for example: `Supabase.Storage` or `Supabase.UI`.\n\n`Supabase.Client` is defined as:\n\n- `:base_url` - The base url of the Supabase API, it is usually in the form `https://\u003capp-name\u003e.supabase.io`.\n- `:api_key` - The API key used to authenticate requests to the Supabase API.\n- `:access_token` - Token with specific permissions to access the Supabase API, it is usually the same as the API key.\n- `:db` - default database options\n    - `:schema` - default schema to use, defaults to `\"public\"`\n- `:global` - global options config\n    - `:headers` - additional headers to use on each request\n- `:auth` - authentication options\n    - `:auto_refresh_token` - automatically refresh the token when it expires, defaults to `true`\n    - `:debug` - enable debug mode, defaults to `false`\n    - `:detect_session_in_url` - detect session in URL, defaults to `true`\n    - `:flow_type` - authentication flow type, defaults to `\"web\"`\n    - `:persist_session` - persist session, defaults to `true`\n    - `:storage_key` - storage key\n\n### Usage\n\nThere are two ways to create a `Supabase.Client`:\n1. one off clients\n2. self managed clients\n\n#### One off clients\n\nOne off clients are clients that are created and managed by your application. They are useful for quick interactions with the Supabase API.\n\n```elixir\niex\u003e Supabase.init_client(\"https://\u003csupabase-url\u003e\", \"\u003csupabase-api-key\u003e\")\niex\u003e {:ok, %Supabase.Client{}}\n```\n\nAny additional config can be passed as the third argument as an [Enumerable](https://hexdocs.pm/elixir/Enumerable.html):\n\n```elixir\niex\u003e Supabase.init_client(\"https://\u003csupabase-url\u003e\", \"\u003csupabase-api-key\u003e\",\n  db: [schema: \"another\"],\n  auth: [flow_type: :pkce],\n  global: [headers: %{\"custom-header\" =\u003e \"custom-value\"}]\n)\niex\u003e {:ok, %Supabase.Client{}}\n```\n\n\u003e Note that one off clients are just raw elixir structs and therefore don't manage any state\n\nFor more information on the available options, see the [Supabase.Client](https://hexdocs.pm/supabase_potion/Supabase.Client.html) module documentation.\n\n\u003e There's also a bang version of `Supabase.init_client/3` that will raise an error if the client can't be created.\n\nYou can also define a module that will centralize the client initialization:\n\n```elixir\ndefmodule MyApp.Supabase.Client do\n  @behaviour Supabase.Client.Behaviour\n\n  @impl true\n  def init do\n    # your client initialization\n    # you should return {:ok, client} or {:error, reason}\n    # you probably want to use `Supabase.init_client/3` here\n    # but get the base_url and api_key from anywhere you want\n  end\n\n  @impl true\n  def get_client do\n    # your client retrieval\n    # you should return the client\n    # the management of the client state is up to you\n  end\nend\n```\n\nFor self managed clients, check the [next section](#self-managed-clients).\n\n#### Self managed clients\n\nSelf managed clients are clients that are created and managed by a separate process on your application. They are useful for long running applications that need to interact with the Supabase API.\n\nIf you don't have experience with processes or is a Elixir begginner, you should take a deep look into the Elixir official getting started section about processes, concurrency and distribution before to proceed.\n- [Processes](https://hexdocs.pm/elixir/processes.html)\n- [Agent getting started](https://hexdocs.pm/elixir/agents.html)\n- [GenServer getting started](https://hexdocs.pm/elixir/genservers.html)\n- [Supervison trees getting started](https://hexdocs.pm/elixir/supervisor-and-application.html)\n\nSo, to define a self managed client, you need to define a module that will hold the client state and the client process as an [Agent](https://hexdocs.pm/elixir/Agent.html).\n\n```elixir\ndefmodule MyApp.Supabase.Client do\n  use Supabase.Client, otp_app: :my_app\nend\n```\n\nFor that to work, you also need to configure the client in your app configuration, it can be a compile-time config on `config.exs` or a runtime config in `runtime.exs`:\n\n```elixir\nimport Config\n\n# `:my_app` here is the same `otp_app` option you passed\nconfig :my_app, MyApp.Supabase.Client,\n  base_url: \"https://\u003csupabase-url\u003e\", # required\n  api_key: \"\u003csupabase-api-key\u003e\", # required\n  access_token: \"\u003csupabase-token\u003e\", # optional\n   # additional options\n  db: [schema: \"another\"],\n  auth: [flow_type: :implicit, debug: true],\n  global: [headers: %{\"custom-header\" =\u003e \"custom-value\"}]\n```\n\nThen, you can start the client process in your application supervision tree, generally in your `application.ex` module:\n\n```elixir\ndefmodule MyApp.Application do\n  use Application\n\n  def start(_type, _args) do\n    children = [\n      MyApp.Supabase.Client\n    ]\n\n    opts = [strategy: :one_for_one, name: MyApp.Supervisor]\n    Supervisor.start_link(children, opts)\n  end\nend\n```\n\n\u003e Of course, you can spawn as many clients you wanna, with different configurations if you need\n\nNow you can interact with the client process:\n\n```elixir\niex\u003e {:ok, %Supabase.Client{} = client} = MyApp.Supabase.Client.get_client()\niex\u003e Supabase.GoTrue.sign_in_with_password(client, email: \"\", password: \"\")\n```\n\nYou can also update the `access_token` for it:\n\n```elixir\niex\u003e {:ok, %Supabase.Client{} = client} = MyApp.Supabase.Client.get_client()\niex\u003e client.access_token == client.api_key\niex\u003e :ok = MyApp.Supabase.Client.set_auth(\"new-access-token\")\niex\u003e {:ok, %Supabase.Client{} = client} = MyApp.Supabase.Client.get_client()\niex\u003e client.access_token == \"new-access-token\"\n```\n\nFor more examples on how to use the client, check clients implementations docs:\n- [Supabase.GoTrue](https://hexdocs.pm/supabase_gotrue)\n- [Supabase.Storage](https://hexdocs.pm/supabase_storage)\n- [Supabase.PostgREST](https://hexdocs.pm/supabase_postgrest)\n\n### How to find my Supabase base URL?\n\nYou can find your Supabase base URL in the Settings page of your project.\nFirstly select your project from the initial Dashboard.\nOn the left sidebar, click on the Settings icon, then select API.\nThe base URL is the first field on the page.\n\n### How to find my Supabase API Key?\n\nYou can find your Supabase API key in the Settings page of your project.\nFirstly select your project from the initial Dashboard.\nOn the left sidebar, click on the Settings icon, then select API.\nThe API key is the second field on the page.\n\nThere two types of API keys, the public and the private. The last one\nbypass any Row Level Security (RLS) rules you have set up.\nSo you shouldn't use it in your frontend application.\n\nIf you don't know what RLS is, you can read more about it here:\nhttps://supabase.com/docs/guides/auth/row-level-security\n\nFor most cases you should prefer to use the public \"anon\" Key.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupabase-community%2Fsupabase-ex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupabase-community%2Fsupabase-ex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupabase-community%2Fsupabase-ex/lists"}