defmodule Supabase do
@moduledoc """
The main entrypoint for the Supabase SDK library.
## Installation
The package can be installed by adding `supabase` to your list of dependencies in `mix.exs`:
def deps do
[
{:supabase_potion, "~> 0.1"}
]
end
## Usage
After installing `:supabase_potion`, you can easily and dynamically manage different `Supabase.Client` and their `Supabase.Connection`. That means you can have multiple Supabase clients that manage multiple Supabase connections.
### Clients vs Connections
A `Supabase.Client` is an Agent that holds general information about Supabase, that can be used to intereact with any of the children integrations, for example: `Supabase.Storage` or `Supabase.UI`.
Also a `Supabase.Client` holds a list of `Supabase.Connection` that can be used to perform operations on different buckets, for example.
`Supabase.Client` is defined as:
- `:name` - the name of the client, started by `start_link/1`
- `:connections` - a list of `%{conn_alias => conn_name}`, where `conn_alias` is the alias of the connection and `conn_name` is the name of the connection.
- `:db` - default database options
- `:schema` - default schema to use, defaults to `"public"`
- `:global` - global options config
- `:headers` - additional headers to use on each request
- `:auth` - authentication options
- `:auto_refresh_token` - automatically refresh the token when it expires, defaults to `true`
- `:debug` - enable debug mode, defaults to `false`
- `:detect_session_in_url` - detect session in URL, defaults to `true`
- `:flow_type` - authentication flow type, defaults to `"web"`
- `:persist_session` - persist session, defaults to `true`
- `:storage` - storage type
- `:storage_key` - storage key
On the other side, a `Supabase.Connection` is an Agent that holds the connection information and the current bucket, being defined as:
- `:base_url` - The base url of the Supabase API, it is usually in the form `https://<app-name>.supabase.io`.
- `:api_key` - The API key used to authenticate requests to the Supabase API.
- `:access_token` - Token with specific permissions to access the Supabase API, it is usually the same as the API key.
- `:name` - Simple field to track the name of the connection, started by `start_link/1`.
- `:alias` - Field to easily manage multiple connections on a `Supabase.Client` Agent.
- `:bucket` - The current bucket to perform operations on.
In simple words, a `Supabase.Client` is a container for multiple `Supabase.Connection`, and each `Supabase.Connection` is a container for a single bucket.
## Starting a Connection
To start a new Connection you need to call `Supabase.Connection.start_link/1`:
iex> Supabase.Connection.start_link(name: :my_conn, conn_info: %{base_url: "https://myapp.supabase.io", api_key: "my_api_key"})
{:ok, #PID<0.123.0>}
But usually you would start a Connection using a higher level API, defined in `Supabase` module, using the `Supabase.init_connection/1` function:
iex> Supabase.init_connection(%{base_url: "https://myapp.supabase.io", api_key: "my_api_key", name: :my_conn, alias: :conn1})
{:ok, #PID<0.123.0>}
## Starting a Client
After starting some Connections, you then can start a Client calling `Supabase.Client.start_link/1`:
iex> Supabase.Client.start_link(name: :my_client, client_info: %{db: %{schema: "public"}})
{:ok, #PID<0.123.0>}
Notice that this way to start a Client is not recommended, since you will need to manage the `Supabase.Client` manually. Instead, you can use `Supabase.init_client/2`, passing the Client options, and also a list of connections that the Client will manage:
iex> Supabase.Client.init_client(%{db: %{schema: "public"}}, conn_list)
{:ok, #PID<0.123.0>}
## Acknowledgements
This package represents the complete SDK for Supabase. That means
that it includes all of the functionality of the Supabase client integrations, as:
- `supabase-storage` - [Hex documentation](https://hex.pm/packages/supabase_storage)
- `supabase-postgrest` - [Hex documentation](https://hex.pm/packages/supabase_postgrest)
- `supabase-realtime` - [Hex documentation](https://hex.pm/packages/supabase_realtime)
- `supabase-auth` - [Hex documentation](https://hex.pm/packages/supabase_auth)
- `supabase-ui` - [Hex documentation](https://hex.pm/packages/supabase_ui)
- `supabase-fetcher` - [Hex documentation](https://hex.pm/packages/supabase_fetcher)
Of course, if you would like to use only a specific functionality, you can use the following a desired number of packages, example:
defp deps do
[
{:supabase_storage, "~> 0.1"},
{:supabase_realtime, "~> 0.1"},
]
end
Notice that if you prefer to install only a specific package, you will need to manage a `Supabase.Connection` manually. More documentation can be found in [supabase_connection documentation](https://hexdocs.pm/supabase_connection).
### Supabase Storage
Supabase Storage is a service for developers to store large objects like images, videos, and other files. It is a hosted object storage service, like AWS S3, but with a simple API and strong consistency.
### Supabase PostgREST
PostgREST is a web server that turns your PostgreSQL database directly into a RESTful API. The structural constraints and permissions in the database determine the API endpoints and operations.
### Supabase Realtime
Supabase Realtime provides a realtime websocket API powered by PostgreSQL notifications. It allows you to listen to changes in your database, and instantly receive updates as soon as they happen.
### Supabase Auth
Supabase Auth is a feature-complete user authentication system. It provides email & password sign in, email verification, password recovery, session management, and more, out of the box.
### Supabase UI
Supabase UI is a set of UI components that help you quickly build Supabase-powered applications. It is built on top of Tailwind CSS and Headless UI, and is fully customizable. The package provides `Phoenix.LiveView` components!
### Supabase Fetcher
Supabase Fetcher is a customized HTTP client for Supabase. Mainly used in Supabase Potion. If you want a complete control on how to make requests to any Supabase API, you would use this package directly.
"""
alias Supabase.Client
alias Supabase.ClientOptions
alias Supabase.ClientSupervisor
alias Supabase.Connection
alias Supabase.ConnectionOptions
alias Supabase.ConnectionSupervisor
@typep changeset :: Ecto.Changeset.t()
@spec init_client(params, list(Connection.t())) ::
{:ok, pid} | {:error, changeset} | {:error, {atom, changeset}}
when params: ClientOptions.t()
def init_client(%{} = opts, connections) do
with {:ok, opts} <- ClientOptions.parse(opts),
client_opts = ClientOptions.to_client_info(opts, connections),
{:ok, pid} <- ClientSupervisor.start_child({Client, client_opts}) do
{:ok, Client.retrieve_client(pid)}
end
end
@spec init_connection(params) ::
{:ok, %{pid: pid, name: atom, alias: atom | String.t()}} | {:error, changeset}
when params: ConnectionOptions.t()
def init_connection(%{} = opts) do
with {:ok, opts} <- ConnectionOptions.parse(opts),
conn_params = ConnectionOptions.to_connection_info(opts),
{:ok, pid} <- ConnectionSupervisor.start_child({Connection, conn_params}) do
{:ok, Connection.retrieve_connection(pid)}
end
end
end
