supabase/dbdev

Database Package Registry for Postgres

Supabase

Supabase is an open source Firebase alternative. We're building the features of Firebase using enterprise-grade open source tools.

• Hosted Postgres Database. Docs
• Authentication and Authorization. Docs
• Auto-generated APIs.
  • REST. Docs
  • GraphQL. Docs
  • Realtime subscriptions. Docs
• Functions.
  • Database Functions. Docs
  • Edge Functions Docs
• File Storage. Docs
• AI + Vector/Embeddings Toolkit. Docs
• Dashboard

Watch "releases" of this repo to get notified of major updates.

Documentation

For full documentation, visit supabase.com/docs

To see how to Contribute, visit Getting Started

Community & Support

• Community Forum. Best for: help with building, discussion about database best practices.
• GitHub Issues. Best for: bugs and errors you encounter using Supabase.
• Email Support. Best for: problems with your database or infrastructure.
• Discord. Best for: sharing your applications and hanging out with the community.

How it works

Supabase is a combination of open source tools. We’re building the features of Firebase using enterprise-grade, open source products. If the tools and communities exist, with an MIT, Apache 2, or equivalent open license, we will use and support that tool. If the tool doesn't exist, we build and open source it ourselves. Supabase is not a 1-to-1 mapping of Firebase. Our aim is to give developers a Firebase-like developer experience using open source tools.

Architecture

Supabase is a hosted platform. You can sign up and start using Supabase without installing anything. You can also self-host and develop locally.

• Postgres is an object-relational database system with over 30 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance.
• Realtime is an Elixir server that allows you to listen to PostgreSQL inserts, updates, and deletes using websockets. Realtime polls Postgres' built-in replication functionality for database changes, converts changes to JSON, then broadcasts the JSON over websockets to authorized clients.
• PostgREST is a web server that turns your PostgreSQL database directly into a RESTful API
• GoTrue is a JWT based API for managing users and issuing JWT tokens.
• Storage provides a RESTful interface for managing Files stored in S3, using Postgres to manage permissions.
• pg_graphql a PostgreSQL extension that exposes a GraphQL API
• postgres-meta is a RESTful API for managing your Postgres, allowing you to fetch tables, add roles, and run queries, etc.
• Kong is a cloud-native API gateway.

Client libraries

Our approach for client libraries is modular. Each sub-library is a standalone implementation for a single external system. This is one of the ways we support existing tools.

Language	Client	Feature-Clients (bundled in Supabase client)
	Supabase	PostgREST	GoTrue	Realtime	Storage	Functions
⚡️ Official ⚡️
JavaScript (TypeScript)	supabase-js	postgrest-js	gotrue-js	realtime-js	storage-js	functions-js
Flutter	supabase-flutter	postgrest-dart	gotrue-dart	realtime-dart	storage-dart	functions-dart
Swift	supabase-swift	postgrest-swift	auth-swift	realtime-swift	storage-swift	functions-swift
💚 Community 💚
C#	supabase-csharp	postgrest-csharp	gotrue-csharp	realtime-csharp	storage-csharp	functions-csharp
Go	-	postgrest-go	gotrue-go	-	storage-go	functions-go
Java	-	-	gotrue-java	-	storage-java	-
Kotlin	supabase-kt	postgrest-kt	gotrue-kt	realtime-kt	storage-kt	functions-kt
Python	supabase-py	postgrest-py	gotrue-py	realtime-py	storage-py	functions-py
Ruby	supabase-rb	postgrest-rb	-	-	-	-
Rust	-	postgrest-rs	-	-	-	-
Godot Engine (GDScript)	supabase-gdscript	postgrest-gdscript	gotrue-gdscript	realtime-gdscript	storage-gdscript	functions-gdscript

Badges

[![Made with Supabase](https://supabase.com/badge-made-with-supabase.svg)](https://supabase.com)

<a href="https://supabase.com">
  <img
    width="168"
    height="30"
    src="https://supabase.com/badge-made-with-supabase.svg"
    alt="Made with Supabase"
  />
</a>

[![Made with Supabase](https://supabase.com/badge-made-with-supabase-dark.svg)](https://supabase.com)

<a href="https://supabase.com">
  <img
    width="168"
    height="30"
    src="https://supabase.com/badge-made-with-supabase-dark.svg"
    alt="Made with Supabase"
  />
</a>

Translations

• Arabic | العربية
• Albanian / Shqip
• Bangla / বাংলা
• Bulgarian / Български
• Catalan / Català
• Czech / čeština
• Danish / Dansk
• Dutch / Nederlands
• English
• Estonian / eesti keel
• Finnish / Suomalainen
• French / Français
• German / Deutsch
• Greek / Ελληνικά
• Gujarati / ગુજરાતી
• Hebrew / עברית
• Hindi / हिंदी
• Hungarian / Magyar
• Nepali / नेपाली
• Indonesian / Bahasa Indonesia
• Italiano / Italian
• Japanese / 日本語
• Korean / 한국어
• Lithuanian / lietuvių
• Latvian / latviski
• Malay / Bahasa Malaysia
• Norwegian (Bokmål) / Norsk (Bokmål)
• Persian / فارسی
• Polish / Polski
• Portuguese / Português
• Portuguese (Brazilian) / Português Brasileiro
• Romanian / Română
• Russian / Pусский
• Serbian / Srpski
• Sinhala / සිංහල
• Slovak / slovenský
• Slovenian / Slovenščina
• Spanish / Español
• Simplified Chinese / 简体中文
• Swedish / Svenska
• Thai / ไทย
• Traditional Chinese / 繁體中文
• Turkish / Türkçe
• Ukrainian / Українська
• Vietnamese / Tiếng Việt
• List of translations

dbdev's Issues

Applying local migration - ERROR: extension "supabase-dbdev" is not available (SQLSTATE 0A000)

I am unable to apply a local migration.

ERROR: extension "supabase-dbdev" is not available (SQLSTATE 0A000)

To Reproduce

Steps to reproduce the behavior, please provide code snippets or a repository:

1. Update DB on supabase.com, install dbdev, install (in my case) supabase_rbac
2. Pull DB on local machine supabase db pull
3. Reset DB supabase db reset
4. See error

Expected behavior

Migration applied, incl extension.

Additional context

I tried to run all the install commands locally first (from here) but this did not help.

Migration file example:

SET statement_timeout = 0;
SET lock_timeout = 0;
SET idle_in_transaction_session_timeout = 0;
SET client_encoding = 'UTF8';
SET standard_conforming_strings = on;
SELECT pg_catalog.set_config('search_path', '', false);
SET check_function_bodies = false;
SET xmloption = content;
SET client_min_messages = warning;
SET row_security = off;

CREATE EXTENSION IF NOT EXISTS "pg_tle" WITH SCHEMA "pgtle";

CREATE EXTENSION IF NOT EXISTS "supabase-dbdev" WITH SCHEMA "public";

CREATE EXTENSION IF NOT EXISTS "pgsodium" WITH SCHEMA "pgsodium";

CREATE SCHEMA IF NOT EXISTS "supabase_migrations";

ALTER SCHEMA "supabase_migrations" OWNER TO "postgres";

CREATE EXTENSION IF NOT EXISTS "http" WITH SCHEMA "extensions";

CREATE EXTENSION IF NOT EXISTS "pg_graphql" WITH SCHEMA "graphql";

CREATE EXTENSION IF NOT EXISTS "pg_stat_statements" WITH SCHEMA "extensions";

CREATE EXTENSION IF NOT EXISTS "pgcrypto" WITH SCHEMA "extensions";

CREATE EXTENSION IF NOT EXISTS "pgjwt" WITH SCHEMA "extensions";

CREATE EXTENSION IF NOT EXISTS "pointsource-supabase_rbac" WITH SCHEMA "public";

CREATE EXTENSION IF NOT EXISTS "supabase_vault" WITH SCHEMA "vault";

CREATE EXTENSION IF NOT EXISTS "uuid-ossp" WITH SCHEMA "extensions";

What is the way to move from remote to local, incl the extensions?

docs: add some docs describing how to use "dbdev install" via the CLI

Chore

Describe the chore

the current doc only describes how to do it using SQL

Additional context

example:

dbdev install --connection postgres://postgres:postgres@localhost:54322/postgres --path ./pg_idkit

Add UTMs to the links to supabase.com

Low contrast for table cells in Dark Mode

Improve documentation

Link

• Example (adminpack)

Describe the problem

When in dark mode, text in table cells has extremely low contrast.

Describe the improvement

Text should not have extremely low contrast. 🙂

Additional context

how does dbdev compare to pgxn?

Improve documentation by explaining the difference with pgxn.

Link

Page which needs improvement: README.md.

Describe the problem

When I hear npm for pg, I immediately think about pgxn. I think It'd be useful to explain how these tools differ, what different use case they help with.

Describe the improvement

From my perspective, pgxn seems oriented towards extensions, while dbdev is more about regular piece of sql? Pgxn ships source code and gives an easy way to compile them. You'd need a shell access to the machine, and probably be superuser. Dbdev seems to be usable by user with less privilege?

Install script fails on pg_tle extension

Bug report

• I confirm this is a bug with Supabase, not with my own application.
• I confirm I have searched the Docs, GitHub Discussions, and Discord.

Describe the bug

Running the install script for dbdev locally via npx supabase db reset results in an error.

Resetting database...
Initialising schema...
Applying migration 00000000000000_setup_test_environment.sql...
Error: ERROR: extension "pg_tle" is not available (SQLSTATE 0A000)
At statement 2: create extension if not exists pg_tle
Try rerunning the command with --debug to troubleshoot the error.
 ELIFECYCLE  Command failed with exit code 1.

To Reproduce

Create a migration using the install script and run the db reset to initialise the DB.

Expected behavior

It appears to work fine in the hosted version when doing npx supabase db push, but running it locally doesn't work for some reason.

System information

• OS: macOS Ventura Version 13.3.1 (a)
• Version of supabase-js: 1.38.6
• Version of Node.js: 18.15.0

Design a way to update the readme without having to push a new version

Chore

Describe the chore

I accidentally pushed a package without a readme:

https://database.dev/kiwicopple/countries

I wanted to update just the readme, so I edited the file on my computer then ran dbdev publish --path .

I got this back: Nothing to publish

This makes sense, but it could be nice to have a way to update the readme without needing to bump the version (i don't know if NPM allows this though)

Unable to publish second version of an extension

Bug report

Describe the bug

Running dbdev install locally to test the plugin will correctly install one version of the extension correctly, but fail if there is a second version available. removing all but one version works as expected. I thought it might be aws/pg_tle#186, but that appears to be included in the version of pg_tle shipped with supabase already.

This might be user error, but I'm unable to find a path around it.

To Reproduce

Steps to reproduce the behavior, please provide code snippets or a repository:

1. Have an extension with 2 versions available (included below)
2. Make sure your extension is uninstalled by running SELECT pgtle.uninstall_extension_if_exists('supabase_test_helpers');
3. Confirm it's no longer installed by running SELECT * FROM pgtle.available_extension_versions();
4. With supabase running locally, run dbdev install --connection postgresql://postgres:postgres@localhost:54322/postgres --path .

Here's my current PR with the changes: usebasejump/supabase-test-helpers#13

Expected behavior

I'd expect both 0.0.1 and 0.0.2 to be correctly installed through pg_tle. It appears to be installing 0.0.2 correctly and then failing on 0.0.1 saying it already exists

Screenshots

System information

• OS: MacOS
• dbdev: 0.1.2

How do I un-publish a TLE?

Not really a bug, but don't think documentation tag either.

Once a TLE is published can I remove it?
I did a test TLE that is useless but can't find a way to remove it.
I understand that could be an issue if people have installed and may be why it does not exist.

Just want to confirm I'm not missing something.

Use default_version information from control file

Currently the default_version from control files is not tracked

We recommend that users always specify a version number when enabling an extension but this argument should be added to the top level package table and updated on dbdev publish because it has an impact on pg_dump/pg_restore projects.

Note, there are 3 components to this:

• tracking default_version in the database
• (if needed) create a new release of the dbdev in-database client that respects the value
• (if needed) update the dbdev CLI to respect the value

Naming Fail :|

Bug report

• I confirm this is a bug with Supabase, not with my own application.
• I confirm I have searched the Docs, GitHub Discussions, and Discord.

Describe the bug

psql:_install.sql:43: ERROR:  invalid extension name: "supabase@dbdev"
DETAIL:  Extension names must only contain alphanumeric characters or valid separators.

To Reproduce

Just try to run the long bootstrap script in the Readme on a new db.

Expected behavior

It not to fail.

Screenshots

psql:_install.sql:43: ERROR:  invalid extension name: "supabase@dbdev"
DETAIL:  Extension names must only contain alphanumeric characters or valid separators.

System information

• OS: [e.g. macOS, Windows]
• Browser (if applies) [e.g. chrome, safari]
• Version of supabase-js: [e.g. 6.0.2]
• Version of Node.js: [e.g. 10.10.0]

Additional context

Add any other context about the problem here.

Once a use signs up there is no need to redirect to the sign-in page

Bug report

• I confirm this is a bug with Supabase, not with my own application.
• I confirm I have searched the Docs, GitHub Discussions, and Discord.

Describe the bug

After a user signs up they are redirected to the sign-in page, but this is not needed as the user is already logged in. So, the user should be either redirected to the home page or whichever page they were on before the sign-up page.

To Reproduce

Steps to reproduce the behavior, please provide code snippets or a repository:

1. Go to the sign-up page and sign up as a new user.
2. Once you finish signing up you will be taken to the log-in page.
3. Go to the home page and click the user avatar next to the search bar at the top.
4. Notice that it shows you are logged in.

Expected behavior

The user can be taken directly to the home page after they sign-up.

Screenshots

N/A

System information

N/A

Additional context

N/A

Installing a new pg_tle extension version which requires following an upgrade path doesnt' work

Bug report

I have 2 files for my extension.

basejump_core--2.0.1.sql
basejump_core--2.0.1--2.1.0.sql

Default version set to 2.1.0.

On a clean install, running create extension "basejump_core" version '2.1.0'; will fail with the following error:

ERROR:  could not find sql function "basejump_core--2.1.0.sql" for extension basejump_core in schema pgtle

Based on the pg_tle docs, this appears like it should work by first installing 2.0.1 and then following the 2.1.0 path - but doesn't seem to.

To Reproduce

Here's a PR with the upgrade I'm working on which doesn't work: usebasejump/basejump#57

Expected behavior

I expect the extension to be installable to 2.1.0 without having a dedicated basejump_core--2.1.0.sql extension file

Make `.control` file parsing more robust

Chore

Describe the chore

The current code to parse .control files in the models.rs is primitive. Use a parser that matches the logic in the GUC parser in postgres.

Additional context

N/A

Enable custom SMTP

Currently password reset mail are sent from @mail.app.supabase.io domain. Change this so that emails are sent from database.dev domain.

Link to package author documentation in README/website

Improve documentation

Currently we don't link to the author documentation

this task is for adding references to the author documentation prominently in the main repo README.md + on the database.dev website homepage.

Publishing a new package version does nothing?

Bug report

• I confirm this is a bug with Supabase, not with my own application.
• I confirm I have searched the Docs, GitHub Discussions, and Discord.

Describe the bug

When calling dbdev publish on an already-published package, I get a success message:
Published package uuidv7 upgrade from 1.0.1 to 1.0.2
I have previously done the same with an upgrade from 1.0.0 to 1.0.1, which was just a readme change. But the package version on database.dev is still 1.0.0.

To Reproduce

What I did, and I'm not going to reproduce it myself as I don't want to spam the server with broken test packages, especially since I can't delete them afterward:

1. Create a new package with a package--1.0.0.sql script.
2. Run dbdev publish.
3. Change something in the readme.
4. Run dbdev publish again.
5. Nothing happens. Find out from a different issue that that's the intended behavior.
6. Create a package--1.0.0--1.0.1.sql script that is empty.
7. Run dbdev publish again. There's a success message.
8. Check the package on https://database.dev. It's still 1.0.0.
9. Create a package--1.0.1--1.0.2.sql script that actually does something, hoping that that would change something (and actually also fixing a bug).
10. Run dbdev publish again, get a success message, nothing happens.
11. File a bug report.

Expected behavior

When I get the message Published package uuidv7 upgrade from 1.0.1 to 1.0.2, I expect database.dev to list that version.

System information

• OS: Windows
• dbdev: 0.1.6

Additional information

The current version of my control file:

# uuidv7 extension
comment = 'UUIDv7 extension'
default_version = '1.0.2'
relocatable = false
superuser = false

Confirmation email redirects to localhost

Bug report

Describe the bug

The confirmation email link redirects to http://localhost:3000

To Reproduce

1. Register in database.dev
2. Click on confirmation email link
3. See error when redirected to localhost

Expected behavior

Confirmation email link redirects to https://database.dev

Screenshots

typo: pacakges

Visiting database.dev/<user> shows a profile page for <user> even if the user doesn't exist

Bug report

• I confirm this is a bug with Supabase, not with my own application.
• I confirm I have searched the Docs, GitHub Discussions, and Discord.

Describe the bug

Profile pages for non-existent users is shown.

To Reproduce

Steps to reproduce the behavior, please provide code snippets or a repository:

1. Visit https://database.dev/cat. cat can be replaced with any non-existent user.
2. See the profile page for user cat.

Expected behavior

An error about user not existing should be displayed.

Screenshots

System information

• OS: macOS
• Browser (if applies) brave

Additional context

N/A

`public.packages` view should take `app.package_upgrades` into account as well for its latest_version column.

Currently the public.packages view is defined like this:

create or replace view public.packages as
    select
        pa.id,
        pa.package_name,
        pa.handle,
        pa.partial_name,
        newest_ver.version as latest_version,
        newest_ver.description_md,
        pa.control_description,
        pa.control_requires,
        pa.created_at,
        pa.default_version
    from
        app.packages pa,
        lateral (
            select *
            from app.package_versions pv
            where pv.package_id = pa.id
            order by pv.version_struct desc
            limit 1
        ) newest_ver;

Notice how in the lateral clause only app.package_versions are read but there's no app.package_upgrades. This results in the latest version being returned as less if there is one base version with an upgrade.

To reproduce publish an extension with my_ext--1.0.0.sql and my_ext--1.0.0--2.0.0.sql files and notice how the latest version reported is 1.0.0.

To fix, the view should take the maximum version from among the app.package_versions's version column and app.package_upgrade's to_version column.

`dbdev ls --connection=xxxx` command to list installed TLEs

Bug report

create dbdev ls command to list available and installed TLEs

Included in output

• TLE names
• Available full install script versions
• Available upgrade script versions

Use a logo at the bottom saying Built by Supabase (linking to supabase.com)

Repository information for package

Describe the bug

Unable to see the repository information (and/or source code) for the pglet.

All package managers generally have them on the package page.

Expected behavior

Expect to see repository information.

Improve documentation about TLE upgrades

Improve documentation

I do not see a page which addresses or explains how TLE updates are supposed to be written and applied

Describe the problem

As a developer, I cannot figure out how to safely write a new version:

1. Do I have to assume that the users may already have a previous version installed? This means using defensive statements like "create table if not exists" and "create or replace view". What if I have multiple previous versions? Do I need to account for all of these? (this would be increasingly unmaintainable over time)
2. What if my users have data that they have stored in tables my extension has created? How can I know the right way to migrate such data? Is there some way I can warn users before "resetting" things?
3. What if the new version tries to modify something that is restricted? For instance, a constraint/primary key that needs modifying may have to be dropped before being recreated but cannot be done while there is data that references it. In this case, I have no way to modify the constraint other than to drop table data.

As a user, I cannot tell how to upgrade a TLE or what to expect when I do. For example:

1. Do I have to update in sequence or can I skip versions and jump from 1.0 to 6.0 and let dbdev figure it out?
2. Is any of my data at risk? What if the TLE created tables when I first installed it? Will those table persist or be destroyed/recreated? Is this up to the author? If so, how do I protect myself from bad updates?

Describe the improvement

I would like extensive documentation and examples of how devs are expecting to write and provide TLE updates. I would also like a list of best practices, warnings, errors, and dangers that could result from not following the guidelines. Overall this system currently feels opaque and risky for both devs and users.

Additional context

I was asked if I could provide my package as a TLE, which I did but I am now unsure how to update it. I asked a while ago but didn't get a response and now my users are asking me. I also have an update I'd like to push. This also overlaps the user-focused issue here.

docs: add some docs showing how to update the CLI

this page only describes the steps to install

https://supabase.github.io/dbdev/install-cli/

How are TLE migration handled

Describe the problem

I would like to install a TLE into my project, but I'm wondering about the maintainability and did not find any information about how the TLE should provide update.

Describe the improvement

It would be great to have a section about how to handle version migrations as a package maintainer as well as a user.
For sure dbdev is not responsible for the content of the packages, but providing guidelines would encourage adoption.

Add metadata field for home repository so users can contribute

We don't currently display the home repository of a package so users of the package can suggest improvements/open PRs/issues etc

Task is to add a field for it and display it on the website

Level 3 Markdown Headers not visible in dark mode

Bug report

level 3 markdown headers i.e. ### Some Header

are not visible in dark mode

Example

Notice that the "### Standard Usage" header is not visible in dark mode

Light Mode

Dark Mode

Prevent TLEs from referencing other TLEs in `requires`

Description

We don't currently have dependency resolution in dbdev.

Currently, authors might specify requires in their control file to depend on other dbdev TLEs expecting that to work. It would be nice if we could detect and reject those projects on upload with a useful error message.

In the future, if we implement dependency resolutions, we can loosen that restriction.

Note: we still want to allow authors to define dependencies against native extensions (pgvector, hypopg, etc)

Setup GA4

feat: add a "dbdev create" command

Chore

Describe the chore

(This one is up for debate but I think it would be useful especially for testing environments like GH actions)

The "dbdev install" command adds the TLE to the database but doesn't "enable" the extension. It could be useful to have a command like dbdev create pg_idkit --connection " which essentially runs:

CREATE EXTENSION pg_idkit;

Additional context

Add any other context or screenshots that help clarify the task.

Issue creation options

Describe the chore

The types, links and texts when creating a new issue in this repo is for supabase product and not database.dev. They need to be fixed.

Additional context

FAQ page takes you to the profile of faq

The FAQ page (https://database.dev/faq) shows the profile page (AFAIK, I was just taking a look at the site, I'm not a user) of a user named faq (created today, presumably now() is a default value?)

Names can be longer than "popular package" boxes allow

Names can be longer than "popular package" boxes allow which causes the version number to push beyond the box edges

CLI Distribution brew + linux

Installing the author CLI currently requires a local rust toolchain.

This task is for publishing (at minimum) brew installable releases

linux + windows can wait until after LW if they're problematic since installing from source is always an option but would be great to include if its a light lift

Add OG image

In review by design team

docs: support github markdown

Chore

Describe the chore

dbdev deoesn't support all of gh flavored markdown:

Additional context

https://database.dev/kiwicopple/supa_audit

from this extension:

https://github.com/supabase/supa_audit