Add docs about the new package for MikroORM

docs/docs/changelog.md

@@ -17,6 +17,8 @@ keywords: ['Bemi Changelog', 'Bemi New Features', 'Postgres Audit Trails', 'Chan
 * [Bemi Core](https://github.com/BemiHQ/bemi)
   * Insert records in batches sequentially to avoid overloading the database at scale
   * Update local Docker image path
+* [Bemi MikroORM](https://github.com/BemiHQ/bemi-mikro-orm)
+  * Create a new JS/TS package to allow passing application context with data changes
 
 ## 2024-08
 
@@ -101,7 +103,6 @@ keywords: ['Bemi Changelog', 'Bemi New Features', 'Postgres Audit Trails', 'Chan
   * Automatically include an original SQL query in the application context
   * Add support for Next.js actions
 * [Bemi Rails](https://github.com/BemiHQ/bemi-rails)
-  * Automatically include an original SQL query in the application context
   * Allow filtering out changes by a record, values, and operations
   * Add new helper methods for diffing and sorting changes
   * Filter out sensitive logs

docs/docs/home.md

@@ -78,4 +78,4 @@ Bemi workers then stitch the low-level data with the application context and sto
 
 ![bemi-architechture](/img/architecture.png)
 
-The cloud solution includes worker ingesters, queues for fault tolerance, and an automatically scalable cloud-hosted PostgreSQL. Bemi currently doesn't support a self hosted option, but [contact us](mailto:[email protected]) if this is required.
+The cloud solution includes worker ingesters, queues for fault tolerance, and an automatically scalable cloud-hosted PostgreSQL.

docs/docs/orms/mikro-orm.md

@@ -0,0 +1,99 @@
+---
+title: Bemi MikroORM Integration - Automatic Database Change Tracking for PostgreSQL
+sidebar_label: MikroORM
+hide_title: true
+description: Discover how Bemi integrates with MikroORM and PostgreSQL to automatically track database changes. This guide covers the installation and use of Bemi with MikroORM to enable context-aware audit trails in your application.
+image: 'img/social-card.png'
+keywords: [Bemi, MikroORM integration, PostgreSQL change tracking, database auditing, application context, audit trails, MikroORM PostgreSQL, database change monitoring]
+---
+
+# MikroORM
+
+<a class="github-button" href="https://github.com/BemiHQ/bemi-mikro-orm" data-size="large" data-show-count="true" aria-label="Star BemiHQ/bemi-mikro-orm on GitHub">BemiHQ/bemi-mikro-orm</a>
+<br />
+<br />
+
+[Bemi](https://bemi.io/) plugs into [MikroORM](https://github.com/mikro-orm/mikro-orm) 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 MikroORM 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-mikro-orm-example) as an Todo app example with MikroORM that automatically tracks and contextualizes all changes.
+
+## Prerequisites
+
+- PostgreSQL 14+
+- MikroORM
+
+## Installation
+
+1. Install the NPM package
+
+```sh
+npm install @bemi-db/mikro-orm
+```
+
+2. Generate a MikroORM migration file to add lightweight [PostgreSQL triggers](https://www.postgresql.org/docs/current/plpgsql-trigger.html) for passing application context with all data changes into PostgreSQL replication log
+
+```sh
+npx bemi migration:create --path src/migrations
+```
+
+3. Run pending MikroORM migrations
+
+```sh
+npx mikro-orm-esm migration:up
+```
+
+## Usage
+
+Add an [Express](https://expressjs.com/) middleware to pass application context with all underlying data changes within an HTTP request:
+
+```ts title="src/index.ts"
+import { setContext } from "@bemi-db/mikro-orm";
+import express, { Request } from "express";
+
+const app = express();
+
+// This is where you set any information that should be stored as context with all data changes
+app.use(
+  setContext((req: Request) => ({
+    endpoint: req.url,
+    params: req.body,
+    userId: req.user?.id,
+  }))
+);
+```
+
+Application context:
+
+* Is bound to the current asynchronous runtime execution context, for example, an HTTP request.
+* Is used only with `INSERT`, `UPDATE`, `DELETE` SQL queries performed via MikroORM. 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.
+
+## 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=mikro-orm) 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}  | {"userId": 187234, "endpoint": "/todo", "params": {"task": "Sleep", "isCompleted": false}}  | 2023-12-11 17:09:09+00
+ 27          | todo  | CREATE    | {}                                                | {"id": 27, "task": "Eat", "isCompleted": false}    | {"userId": 187234, "endpoint": "/todo", "params": {"task": "Eat", "isCompleted": false}}    | 2023-12-11 17:09:11+00
+ 28          | todo  | CREATE    | {}                                                | {"id": 28, "task": "Repeat", "isCompleted": false} | {"userId": 187234, "endpoint": "/todo", "params": {"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}   | {"userId": 187234, "endpoint": "/todo/complete", "params": {"id": 26}}                      | 2023-12-11 17:09:15+00
+ 27          | todo  | DELETE    | {"id": 27, "task": "Eat", "isCompleted": false}   | {}                                                 | {"userId": 187234, "endpoint": "/todo/27", "params": {"id": 27}}                            | 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-mikro-orm/blob/main/LICENSE).
+If you need to modify and distribute the code, please release it to contribute back to the open-source community.

docs/docs/postgresql/destination-database.md

@@ -19,7 +19,7 @@ You have full control over this database which comes with additional features:
 * Standard cloud support
 * Control plane and monitoring through Bemi Dashboard (coming soon)
 
-The infrastructure is automatically provisioned in the `us-west-1` region. If you have specific data residency requirements, please [contact us](mailto:hi@bemi.io).
+The infrastructure is automatically provisioned in the `us-west-1` region. If you have specific data residency requirements, please [contact us](https://bemi.io/contact-us).
 
 ## Data Structure
 

docs/docs/postgresql/source-database.md

@@ -364,7 +364,7 @@ Run the following SQL command to change the WAL level from `replica` to `logical
 ALTER SYSTEM SET wal_level = logical;
 ```
 
-If you have issues in other PostgreSQL hosting environments, please [reach out](mailto:hi@bemi.io) to us and we will send you detailed instructions on how to set it up.
+If you have issues in other PostgreSQL hosting environments, please [contact us](https://bemi.io/contact-us), and we will send you detailed instructions on how to set it up.
 
 ## Selective tracking
 
@@ -374,7 +374,7 @@ During the Source Database connection setup or any time after, you can configure
 
 ![](/img/tracked-tables.png)
 
-Bemi automatically tracks changes in the default `public` schema. If you would like to enable tracking for other schemas in your Bemi organization, please [contact us](mailto:hi@bemi.io).
+Bemi automatically tracks changes in the default `public` schema. If you would like to enable tracking for other schemas in your Bemi organization, please [contact us](https://bemi.io/contact-us).
 
 ### Ignoring by Columns
 
@@ -402,7 +402,7 @@ If you need a public SSH Key before you know the SSH host address, just specify
 
 ## Bemi Static IPs
 
-If you restrict access to your databases by IP addresses, [contact us](mailto:hi@bemi.io). We will share our static IP addresses, which you can add to an allowlist, so we can connect to your Source PostgreSQL database.
+If you restrict access to your databases by IP addresses, [contact us](https://bemi.io/contact-us). We will share our static IP addresses, which you can add to an allowlist, so we can connect to your Source PostgreSQL database.
 
 ## Disconnecting
 

docs/docs/self-hosting.md

@@ -13,7 +13,7 @@ keywords: ['Open source', 'Database Tracking', 'Postgres Audit Trails', 'Change
 <br />
 <br />
 
-When self-hosting Bemi, your data never leaves your premises.  
+When self-hosting Bemi, your data never leaves your premises.
 
 ![Bemi Worker Architecture](/img/worker.png)
 
@@ -23,22 +23,33 @@ Bemi consists of three main parts:
 2. [NATS JetStream](https://github.com/nats-io/nats-server), a cloud-native messaging system written in Go. Debezium is historically designed to send data to Kafka, but it can be also re-configured to send data to NATS JetStream. It is much more lightweight and easy to manage while being very performant and having over 45 clients for different programming languages.
 3. Bemi Worker, a process responsible for stitching data change with app context sent via our open-source [ORM packages](https://docs.bemi.io/#supported-orms) and storing data changes. It is written in TypeScript and uses the [`core`](https://github.com/BemiHQ/bemi) that we rely on for our [Bemi](https://bemi.io/) cloud platform.
 
-If you want to self-host our solution in a production environment, please [contact us](https://bemi.io/contact-us),
-and we'll be happy to provide you with a Docker image and assist with configuring the system in exchange for your feedback :)
+You can try it out locally by using a Docker image:
+
+```sh
+docker run \
+  -e DB_HOST=host.docker.internal \
+  -e DB_PORT=5434 \
+  -e DB_NAME=bemi_dev_source \
+  -e DB_USER=postgres \
+  -e DB_PASSWORD=postgres \
+  public.ecr.aws/bemi/dev:latest
+```
+
+`DB_HOST` pointing to `host.docker.internal` allows accessing `127.0.0.1` on your host machine if you run PostgreSQL outside Docker. See [github.com/BemiHQ/bemi](https://github.com/BemiHQ/bemi) for more information.
 
-## Self-Hosting (OSS) vs Bemi Cloud
 |                                   | Self-Hosting (OSS)  | Bemi Cloud  |
 | --------------------------------- | ------------------- | ----------- |
 | PostgreSQL source database        | ✅                  | ✅          |
 | Automatic data change tracking    | ✅                  | ✅          |
 | Automatic application context     | ✅                  | ✅          |
-| Included support                  | ✅                  | ✅          |
+| Audit Trail UI                    | ❌                  | ✅          |
+| Priority support                  | ❌                  | ✅          |
 | Automatic table partitioning      | ❌                  | ✅          |
 | Automatic data retention          | ❌                  | ✅          |
 | Autoscaling and high availability | ❌                  | ✅          |
+| Column-based filter rules         | ❌                  | ✅          |
+| Automatic updates and backups     | ❌                  | ✅          |
 | Control plane and monitoring      | ❌                  | ✅          |
-| Automatic updates                 | ❌                  | ✅          |
-| Activity Log UI                   | ❌                  | ✅          |
 
 ## Self-Hosting Enterprise
 

docs/docusaurus.config.ts

@@ -88,7 +88,7 @@ const config: Config = {
             },
             {
               label: "Contact us",
-              href: "mailto:hi@bemi.io",
+              href: "https://bemi.io/contact-us",
             },
           ],
         },
@@ -100,21 +100,25 @@ const config: Config = {
               href: "https://github.com/BemiHQ/bemi-prisma",
             },
             {
-              label: "Supabase JS",
-              href: "https://github.com/BemiHQ/supabase-js",
+              label: "Ruby on Rails",
+              href: "https://github.com/BemiHQ/bemi-rails",
             },
             {
               label: "TypeORM",
               href: "https://github.com/BemiHQ/bemi-typeorm",
             },
-            {
-              label: "Ruby on Rails",
-              href: "https://github.com/BemiHQ/bemi-rails",
-            },
             {
               label: "SQLAlchemy",
               href: "https://github.com/BemiHQ/bemi-sqlalchemy",
             },
+            {
+              label: "Supabase JS",
+              href: "https://github.com/BemiHQ/bemi-supabase-js",
+            },
+            {
+              label: "MikroORM",
+              href: "https://github.com/BemiHQ/bemi-mikro-orm",
+            },
           ],
         },
         {

docs/sidebars.ts

@@ -29,10 +29,11 @@ const sidebars: SidebarsConfig = {
       collapsed: false,
       items: [
         'orms/prisma',
-        'orms/supabase-js',
-        'orms/typeorm',
         'orms/rails',
+        'orms/typeorm',
         'orms/sqlalchemy',
+        'orms/supabase-js',
+        'orms/mikro-orm',
       ],
     },
     'alternatives',