Home

Getting Started

The Supabase C# library is a wrapper around the various REST APIs provided by Supabase and the various server components (e.g. GoTrue, Realtime, etc.).

Video Options

If you prefer video format: @Milan Jovanović has created a video crash course to get started!

Getting Oriented

At the most basic level, Supabase provides services based on the Postgres database and the supporting ecosystem. You can use the online, hosted version of Supabase, run it locally via CLI and Docker images, or some other combination (e.g. hosted yourself on another cloud service).

One option for .NET developers, of course, is to just treat it as any other RDBMS package. You can create a project, grab the .NET connection string, and use it as you would any other database.

However, Supabase also provides a number of other services that are useful for building applications and services. These include:

• Authentication (GoTrue) is provided by GoTrue, which is a JWT-based authentication service. It provides a number of features, including email/password authentication, OAuth, password resets, email verification, and more. In addition, you can use it to handle the native Sign in With Apple and Sign in With Google authentication systems.
• PostgREST (REST API) is a REST API that is automatically generated from your database schema. It provides a number of features, including filtering, sorting, and more.
• Realtime is a service that provides realtime updates to your database. It is based on Postgres LISTEN/NOTIFY and WebSockets.
• Storage is a service that provides a simple interface for storing files. It is based on Postgres and provides a number of features, including file versioning, metadata, and more.
• Edge Functions is a service that provides a way to run serverless functions on the edge.

The Supabase C# library provides a wrapper around the various REST APIs provided by Supabase and the various server components (e.g. GoTrue, Realtime, etc.). It also provides a number of convenience methods and classes - for example, utilities to make the native Sign in with Apple flow easier.

Care has been taken to mirror, as much as possible, the Javascript Supabase API. As this is an unofficial client, there are times where this client lags behind the offical client. If there are missing features, please open an issue or pull request!

Considerations

There are two main ways to access your Supabase instance - either via an "untrusted" client (e.g. Unity or some other mobile/desktop client) or a "trusted" client (e.g. a server-side application).

The untrusted clients have two key factors - first, you'll likely want to manage the user state (e.g. login, logout, etc.) and second, you'll be using the anonymous/public API key to access those services. The user is expected to use some kind of credentials (e.g. email/password, OAuth, or a JWT from a native sign-in dialog, etc.) to access the services. The Supabase session (a JWT issued by GoTrue) serves as the authentication token for the various services.

Tip: If you aren't familiar with JWTs, you can read more about them here. You can also use this site to decode the JWTs issued by GoTrue, which you may find helpful when learning about Supabase Auth. If you are a traditional server-side dev, you might find it helpful to think of the JWT as a session cookie, except that it is cryptographically signed (proving that it was "minted" by GoTrue). You can use standard JWT libraries to decode the token, access the details, and verify the signature.

Trusted, server-side code is usually best managed as a stateless system, where each request is managed independently. In this scenario, you will often want to use the library in conjunction with the private API key.

Remember - the public key is designed to be used in untrusted clients, while the private key is designed to be used in trusted clients ONLY.

To use this library on the Supabase Hosted service but separately from the supabase-csharp, you'll need to specify your url and public key like so:

var auth = new Supabase.Gotrue.Client(new ClientOptions<Session>
{
    Url = "https://PROJECT_ID.supabase.co/auth/v1",
    Headers = new Dictionary<string, string>
    {
        { "apikey", SUPABASE_PUBLIC_KEY }
    }
})

Otherwise, using it this library with a local instance:

var options = new ClientOptions { Url = "https://example.com/api" };
var client = new Client(options);
var user = await client.SignUp("[email protected]");

// Alternatively, you can use a StatelessClient and do API interactions that way
var options = new StatelessClientOptions { Url = "https://example.com/api" }
await new StatelessClient().SignUp("[email protected]", options);

Using the Client

As for actually using the client, each service is listed as a property on Supabase.Client. Some services have helpers to make interactions easier. Properties are provided for every client in the event that advanced customization of the client is needed.

1. Supabase.Postgrest
   • Is better accessed using supabase.From<ModelName>() as it provides a wrapper class with some helpful accessors (see below)
2. Supabase.Realtime
   • If used for listening to postgres_changes can be accessed using: supabase.From<ModelName>().On(listenerType, (sender, response) => {})
   • Otherwise, use Supabase.Realtime.Channel("channel_name") for Broadcast and Presence listeners.

// Get the Auth Client
var auth = supabase.Auth;

// Get the Postgrest Client for a Model
var table = supabase.From<TModel>();

// Invoke an RPC Call
await supabase.Rpc("hello_world", null);

// Invoke a Supabase Function
await supabase.Functions.Invoke("custom_function");

// Get the Storage Client
var storageBucket = supabase.Storage.From("bucket_name");

// Use syntax for broadcast, presence, and postgres_changes
var realtime = supabase.Realtime.Channel("room_1");

// Alternatively, shortcut syntax for postgres_changes
await supabase.From<TModel>().On(ListenType.All, (sender, response) =>
{
    switch (response.Event)
    {
        case Constants.EventType.Insert:
            break;
        case Constants.EventType.Update:
            break;
        case Constants.EventType.Delete:
            break;
    }

    Debug.WriteLine($"[{response.Event}]:{response.Topic}:{response.Payload.Data}");
});

Next Steps

Given that the configuration is pretty different depending on the scenario, we'll cover each of the scenarios separately.

• Unity
• Desktop Clients
• Server-Side Applications

More Tips

• Take time to review your options. Which can be found in Supabase.SupabaseOptions.
• Be aware that many of the supabase features require permissions for proper access from a client. This is especially true for realtime, postgres, and storage. If you are having problems getting the client to pull data, verify that you have proper permissions for the logged in user.
• Connection to Supabase.Realtime is, by default, not enabled automatically, this can be changed in options.
• When logging in using the Supabase.Auth (Gotrue) client, state is managed internally. The currently logged in user's token will be passed to all the Supabase features automatically (via header injection).
• Token refresh enabled by default and is handled by a timer on the Gotrue client.
• Client libraries listed above have additional information in their readme files.
• The brave may find generated api documentation from the xml comments useful.