diff --git a/docs/docs/changelog.md b/docs/docs/changelog.md index 8a728b3..80ae0ee 100644 --- a/docs/docs/changelog.md +++ b/docs/docs/changelog.md @@ -13,15 +13,24 @@ keywords: ['Bemi Changelog', 'Bemi New Features', 'Postgres Audit Trails', 'Chan * Platform * Enable tracking changes from non-`public` PostgreSQL schemas - * Allow setting ignore-change column rules across all tables (e.g., `*.updatedAt`) + * Allow setting ignore-change column rules across all tables, such as `*.updatedAt` + * Automatically delete old changes beyond the retention period + * Add comprehensive ingestion monitoring +* [Bemi Core](https://github.com/BemiHQ/bemi) + * Run type checks via CI/CD +* [Bemi Supabase JS](https://github.com/BemiHQ/bemi-supabase-js) + * Create a new Supabase JS package to allow passing application context with data changes * [Bemi SQLAlchemy](https://github.com/BemiHQ/bemi-sqlalchemy) * Create a new Python package to allow passing application context with data changes +* Integrations + * [Neon](https://neon.tech/docs/guides/bemi): new integration guide ## 2024-05 * Dashboard * Allow copying change values as an SQL query statement to be able to rollback * Improve Browser UI performance for custom views with associations + * Disable autocomplete for inputs by default * Platform * Upgrade infrastructure to support IPv6 (dual stack) * [Bemi Core](https://github.com/BemiHQ/bemi) diff --git a/docs/docs/home.md b/docs/docs/home.md index a8cf6b2..d6af9fa 100644 --- a/docs/docs/home.md +++ b/docs/docs/home.md @@ -53,6 +53,7 @@ This allows automatically enhancing low-level database changes with application- #### Node.js * **[Prisma](/orms/prisma)** +* **[Supabase JS](/orms/supabase-js)** * **[TypeORM](/orms/typeorm)** #### Ruby diff --git a/docs/docs/orms/sqlalchemy.md b/docs/docs/orms/sqlalchemy.md index 03c7744..a1e68fd 100644 --- a/docs/docs/orms/sqlalchemy.md +++ b/docs/docs/orms/sqlalchemy.md @@ -3,7 +3,7 @@ title: Bemi SQLAlchemy Integration - Automate Context-Aware Audit Trails with Po sidebar_label: SQLAlchemy hide_title: true description: Discover how Bemi integrates with SQLAlchemy and PostgreSQL to automatically track database changes, providing robust audit trails for your applications. Learn how to install and use the Bemi SQLAlchemy Python package for enhanced data tracking. -image: 'img/bemi-sqlalchemy.png' +image: 'img/social-card.png' keywords: [Bemi, SQLAlchemy, PostgreSQL, database auditing, data tracking, context-aware audit, application context, audit log, audit trail, data versioning] --- @@ -74,7 +74,7 @@ with engine.connect() as connection: Application context: -* Is bound to the current database session execution context. +* Is bound to the current execution thread within an HTTP request. * Is used only with `INSERT`, `UPDATE`, `DELETE` SQL queries performed via SQLAlchemy. Otherwise, it is a no-op. * Is passed directly into PG [Write-Ahead Log](https://www.postgresql.org/docs/current/wal-intro.html) with data changes without affecting the structure of the database and SQL queries. @@ -102,7 +102,7 @@ app.add_middleware( ## Database connection -Connect your PostgreSQL source database on [bemi.io](https://bemi.io) to start ingesting and storing all data changes stitched together with application-specific context. The database connection details can be securely configured through the [dashboard UI](https://dashboard.bemi.io/log-in?ref=prisma) in a few seconds. +Connect your PostgreSQL source database on [bemi.io](https://bemi.io) to start ingesting and storing all data changes stitched together with application-specific context. The database connection details can be securely configured through the [dashboard UI](https://dashboard.bemi.io/log-in?ref=sqlalchemy) in a few seconds. ![dashboard](/img/dashboard.png) @@ -124,6 +124,6 @@ See [Destination Database](/postgresql/destination-database) for more details. ## License -Distributed under the terms of the [LGPL-3.0](https://github.com/BemiHQ/bemi-prisma/blob/main/LICENSE). +Distributed under the terms of the [LGPL-3.0](https://github.com/BemiHQ/bemi-sqlalchemy/blob/main/LICENSE). If you need to modify and distribute the code, please release it to contribute back to the open-source community. hide_title: true diff --git a/docs/docs/orms/supabase-js.md b/docs/docs/orms/supabase-js.md new file mode 100644 index 0000000..d6741b0 --- /dev/null +++ b/docs/docs/orms/supabase-js.md @@ -0,0 +1,99 @@ +--- +title: Bemi Supabase JS Integration - Automate Context-Aware Audit Trails with PostgreSQL +sidebar_label: Supabase JS +hide_title: true +description: Discover how Bemi integrates with Supabase JS and PostgreSQL to automatically track database changes, providing robust audit trails for your applications. Learn how to install and use the Bemi Supabase JS package for enhanced data tracking. +image: 'img/social-card.png' +keywords: [Bemi, Supabase, PostgreSQL, database auditing, data tracking, context-aware audit, application context, audit log, audit trail, data versioning] +--- + +# Supabase JS + +BemiHQ/bemi-supabase-js +
+
+ +[Bemi](https://bemi.io) plugs into [Supabase JS](https://github.com/supabase/supabase-js) and PostgreSQL to track database changes automatically. It unlocks robust context-aware audit trails and time travel querying inside your application. + +This package is a recommended Supabase JS integration, enabling you to pass application-specific context when performing database changes. This can include context such as the 'where' (API endpoint, worker, etc.), 'who' (user, cron job, etc.), and 'how' behind a change, thereby enriching the information captured by Bemi. + +See this [example repo](https://github.com/BemiHQ/bemi-supabase-js-example) as an Todo app example with Supabase JS that automatically tracks and contextualizes all changes. + +## Prerequisites + +- Supabase JS + +## Installation + +1. Install the NPM package + +```sh +npm install @bemi-db/supabase-js +``` + +2. Generate a Supabase JS migration file to add a [Database Function](https://supabase.com/docs/guides/database/functions) for passing application context with all data changes into PostgreSQL replication log + +```sh +npx bemi migration new +``` + +3. Run the Supabase JS migration + +```sh +npx supabase migration up +``` + +## Usage + +Now you can easily specify custom application context that will be automatically passed with all data changes by calling `setContext` in your [Supabase Edge Function](https://supabase.com/docs/guides/functions): + +```ts +import { setContext } from 'https://esm.sh/@bemi-db/supabase-js@0.1.0' +import { createClient } from 'https://esm.sh/@supabase/supabase-js@2.43.5' + +Deno.serve(async (req) => { + const supabase = createClient(...) + const { method, url } = req + const endpoint = `/${url.split('/')[3]}` + const payload = method === 'POST' ? await req.json() : {} + + // Customizable context + await setContext(supabase, { method, endpoint, payload }) + + // Your code that performs data changes +}) +``` + + +Application context: + +* Is bound to the current database session within an HTTP request. +* Is used only with `INSERT`, `UPDATE`, `DELETE` SQL queries performed via Supabase JS. +* Is passed directly into PG [Write-Ahead Log](https://www.postgresql.org/docs/current/wal-intro.html) with data changes without affecting the structure of the database and SQL queries. + +## Database connection + +Connect your PostgreSQL source database on [bemi.io](https://bemi.io) to start ingesting and storing all data changes stitched together with application-specific context. The database connection details can be securely configured through the [dashboard UI](https://dashboard.bemi.io/log-in?ref=supabase-js) in a few seconds. + +![dashboard](/img/dashboard.png) + +Once your destination PostgreSQL database has been fully provisioned, you'll see a "Connected" status. You can now test the connection after making database changes in your connected source database: + +``` +psql postgres://[USERNAME]:[PASSWORD]@[HOSTNAME]:5432/[DATABASE] -c 'SELECT "primary_key", "table", "operation", "before", "after", "context", "committed_at" FROM changes;' + + primary_key | table | operation | before | after | context | committed_at +-------------+-------+-----------+---------------------------------------------------+----------------------------------------------------+-----------------------------------------------------------------------------------------------+------------------------ + 26 | todo | CREATE | {} | {"id": 26, "task": "Sleep", "isCompleted": false} | {"method": "POST", "endpoint": "/todos", "payload": {"task": "Sleep", "isCompleted": false} | 2023-12-11 17:09:09+00 + 27 | todo | CREATE | {} | {"id": 27, "task": "Eat", "isCompleted": false} | {"method": "POST", "endpoint": "/todos", "payload": {"task": "Eat", "isCompleted": false}} | 2023-12-11 17:09:11+00 + 28 | todo | CREATE | {} | {"id": 28, "task": "Repeat", "isCompleted": false} | {"method": "POST", "endpoint": "/todos", "payload": {"task": "Repeat", "isCompleted": false}} | 2023-12-11 17:09:13+00 + 26 | todo | UPDATE | {"id": 26, "task": "Sleep", "isCompleted": false} | {"id": 26, "task": "Sleep", "isCompleted": true} | {"method": "PUT", "endpoint": "/todos/26/complete", "payload": {}} | 2023-12-11 17:09:15+00 + 27 | todo | DELETE | {"id": 27, "task": "Eat", "isCompleted": false} | {} | {"method": "DELETE", "endpoint": "/todos/27", "payload": {}} | 2023-12-11 17:09:18+00 +``` + +See [Destination Database](/postgresql/destination-database) for more details. + +## License + +Distributed under the terms of the [LGPL-3.0](https://github.com/BemiHQ/bemi-supabase-js/blob/main/LICENSE). +If you need to modify and distribute the code, please release it to contribute back to the open-source community. diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 041ddd1..0cdb9e5 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -99,6 +99,10 @@ const config: Config = { label: "Prisma", href: "https://github.com/BemiHQ/bemi-prisma", }, + { + label: "Supabase JS", + href: "https://github.com/BemiHQ/supabase-js", + }, { label: "TypeORM", href: "https://github.com/BemiHQ/bemi-typeorm", diff --git a/docs/sidebars.ts b/docs/sidebars.ts index 237eb59..868340c 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -29,6 +29,7 @@ const sidebars: SidebarsConfig = { collapsed: false, items: [ 'orms/prisma', + 'orms/supabase-js', 'orms/typeorm', 'orms/rails', 'orms/sqlalchemy',