waldit 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8367ecd692940c28ead4bc255173137f7d9f34b9db3df262c15081ab64334ce0
-  data.tar.gz: 84a7c6eeee1b62ff8a3f507e5ae6128759292a80d6e5bd1f1a936ca33c431326
+  metadata.gz: fb7ae260f6d1af42f4e6169084c7ba79de48cea93f44ff47be032f5764df23a6
+  data.tar.gz: 7cf9d0c022ffbb457bcac4380ed635cd65d2df1db24faae5fbd169b50b5aa07c
 SHA512:
-  metadata.gz: 161fafcaba15339898929328f103ff1b659aa17aa89179e7e9124ecb7f7b0487da39d55402711f02f724326203a28c2f7e322ba97a28b3672007663114ac33fd
-  data.tar.gz: cd4cc774d28e9f14732bc807478716c190fa52f6b2f4ec243512655db7fbd3d5aae6c712e7a9a301192702ea5b5a3753e315921ca62c64ea8c7c0119ffa27950
+  metadata.gz: b54045c2265401d420a276efddb20525b7b72e39d27c25e10da6a7a2c357805ea1956aed900d3c265f5cc88096dc402cd53ea52d0989eff8e3dd965d47c2ec75
+  data.tar.gz: 8d86ba10a3c94e7ca87bb90a39957663b305f19b6b5a8bfb7062fdae89879b57c82d230989bfd49b5480738f63ca81bf9db7b1093406b730578498bfc001a862

data/README.md

@@ -1 +1,117 @@
 # Waldit
+
+[![Gem Version](https://badge.fury.io/rb/waldit.svg)](https://badge.fury.io/rb/waldit)
+
+Waldit is a Ruby gem that provides a simple and extensible way to audit changes to your ActiveRecord models. It leverages PostgreSQL's logical replication capabilities to capture changes directly from your database with 100% consistency.
+
+## Features
+
+- **Automatic Auditing:** Automatically track `create`, `update`, and `delete` operations on your models.
+- **Contextual Auditing:** Add custom context to your audit records to understand who made the change and why.
+- **Flexible Configuration:** Configure which tables and columns to watch, and how to store audit information.
+- **High Performance:** Built on top of [`wal`](https://github.com/reu/wal), which uses PostgreSQL's logical replication for minimal overhead.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "waldit"
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install waldit
+
+## Usage
+
+1.  **Configure your database adapter:**
+
+    First step is to configure in your `config/database.yml` and change your adapter to `postgresqlwaldit`, which is a special adapter that allows injecting `waldit` contextual information on your transactions:
+
+    ```yaml
+    default: &default
+      adapter: postgresqlwaldit
+      # ...
+    ```
+
+2.  **Create an audit table:**
+
+    Generate a migration to create the `waldit` table:
+
+    ```bash
+    rails generate migration create_waldit
+    ```
+
+    And then add the following to your migration file:
+
+    ```ruby
+    class CreateWalditTable < ActiveRecord::Migration[7.0]
+      def change
+        create_table :waldit do |t|
+          t.bigint :transaction_id, null: false
+          t.bigint :lsn, null: false
+          t.string :action, null: false
+          t.jsonb :context, default: {}
+          t.string :table_name, null: false
+          t.string :primary_key, null: false
+          t.jsonb :old, default: {}
+          t.jsonb :new, default: {}
+          t.timestamp :commited_at
+
+          t.index [:table_name, :primary_key, :transaction_id], unique: true
+        end
+      end
+    end
+    ```
+
+3.  **Configure Waldit:**
+
+    Create an initializer file at `config/initializers/waldit.rb`:
+
+    ```ruby
+    Waldit.configure do |config|
+      # A callback that returns true if a table should be watched.
+      config.watched_tables = ->(table) { table != "waldit" }
+
+      # A callback that returns an array of columns to ignore for a given table.
+      config.ignored_columns = ->(table) { %w[created_at updated_at] }
+    end
+    ```
+
+4.  **Add context to your changes:**
+
+    Use the `with_context` method to add context to your database operations:
+
+    ```ruby
+    Waldit.with_context(user_id: 1, reason: "User updated their profile") do
+      user.update(name: "New Name")
+    end
+    ```
+
+5.  **Start the watcher:**
+
+    To process the events, you need to start a WAL watcher. The recommended way is to have a config/waldit.yml
+
+    ```yml
+    slots:
+      audit:
+        publications: [waldit_publication]
+        watcher: Waldit::Watcher
+    ```
+
+    And then run:
+
+    ```bash
+    bundle exec wal start config/waldit.yml
+    ```
+
+## How it Works
+
+Waldit uses a custom PostgreSQL adapter to set the `waldit_context` session variable before each transaction. This context is then captured by the logical replication slot and stored in the `waldit` table by the `Waldit::Watcher`.
+
+The `Waldit::Watcher` is a streaming watcher that listens for changes in the logical replication slot and creates audit records in the `waldit` table. It processes events in batches to minimize the number of database transactions.

data/lib/waldit/postgresql_adapter.rb

@@ -27,6 +27,46 @@ module Waldit
       end
     end
 
+    def exec_no_cache(sql, ...)
+      return super if READ_QUERY_REGEXP.match? sql
+      return super if @current_waldit_context == Waldit.context.hash
+
+      if transaction_open?
+        set_waldit_context!
+        super
+
+      elsif Waldit.context
+        # We are trying to execute a query with waldit context while not in a transaction, so we start one
+        transaction do
+          set_waldit_context!
+          super
+        end
+
+      else
+        super
+      end
+    end
+
+    def exec_cache(sql, ...)
+      return super if READ_QUERY_REGEXP.match? sql
+      return super if @current_waldit_context == Waldit.context.hash
+
+      if transaction_open?
+        set_waldit_context!
+        super
+
+      elsif Waldit.context
+        # We are trying to execute a query with waldit context while not in a transaction, so we start one
+        transaction do
+          set_waldit_context!
+          super
+        end
+
+      else
+        super
+      end
+    end
+
     def begin_db_transaction(...)
       @current_waldit_context = nil.hash
       super

data/lib/waldit/version.rb

@@ -2,5 +2,5 @@
 # typed: true
 
 module Waldit
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/waldit/watcher.rb

@@ -60,7 +60,7 @@ module Waldit
         else
           # Finally the most common case: just deleting a record not created or updated on this transaction
           record.upsert(
-            audit.merge(action: "delete", old:),
+            audit.merge(action: "delete", old: event.old),
             unique_by:,
             on_duplicate: :update,
           )

data/rbi/waldit.rbi

@@ -2,7 +2,7 @@
 module Waldit
   extend T::Sig
   extend Waldit::Context
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 
   class << self
     sig { returns(String) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: waldit
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Rodrigo Navarro