whodunit-chronicles 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddd2ff0c636f7842e53659f39138f326f14eb69227688c0fc5170e8db4868f10
-  data.tar.gz: f8d7514ce651c0bb7431740897940083488c0ed24c2e896d54d509677b2cbbd1
+  metadata.gz: fa4438fb3140657b7b9d92db2988c0ca511c9fc0138ba42cfad061ab91dc0ac4
+  data.tar.gz: e3c5339e3ecce1b882be854bc906f9e1644bc812eb16302266d7b8ef68ba0f12
 SHA512:
-  metadata.gz: 7654d23d4e932046c0408c513a18e68f0e4c46856b0aed507f48eea3ed9744838b49ce0b19a4ff0b1853ff156cea64f8ffefa55af5b1e788bce597d8c662be11
-  data.tar.gz: d5a62ae1a2893b65593aa93216377c0d3f6fbbdc28b90362acc9cf8ceeec159e296335014efb3fa77e645a4cc9d5cf8392e81991613fcb27a8ffc9d953f57f64
+  metadata.gz: '03590c69049ab8670411b6beb0e5bbb8d3fcf0989b163541fa606be5fc1c7b41f20c4e6cb5160632ed411b056664f16aa153499c947cd24c612912ff58504354'
+  data.tar.gz: 26d9cbc11e8efbf0aa716034b9ec46604d5bb78e066584f3e9674ef00732daf60fc7ba6a5506c3f9524b0ad216fcfb52e4418b2452451787b6c4498e84bab08a

data/.codeclimate.yml

@@ -0,0 +1,50 @@
+version: "2"
+checks:
+  argument-count:
+    config:
+      threshold: 4
+  complex-logic:
+    config:
+      threshold: 4
+  file-lines:
+    config:
+      threshold: 250
+  method-complexity:
+    config:
+      threshold: 5
+  method-count:
+    config:
+      threshold: 20
+  method-lines:
+    config:
+      threshold: 25
+  nested-control-flow:
+    config:
+      threshold: 4
+  return-statements:
+    config:
+      threshold: 4
+  similar-code:
+    config:
+      threshold: # language-specific defaults. an integer indicates the minimum number of lines within a block of similar code.
+  identical-code:
+    config:
+      threshold: # language-specific defaults. an integer indicates the minimum number of lines within a block of identical code.
+plugins:
+  rubocop:
+    enabled: true
+    config:
+      file: .rubocop.yml
+exclude_patterns:
+- "config/"
+- "db/"
+- "dist/"
+- "features/"
+- "**/node_modules/"
+- "script/"
+- "**/spec/"
+- "**/test/"
+- "**/tests/"
+- "**/vendor/"
+- "**/*_test.rb"
+- "**/*_spec.rb"

data/.rubocop.yml

@@ -1,6 +1,6 @@
 # Ruby version
 AllCops:
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.2
   NewCops: enable
   Exclude:
     - 'vendor/**/*'
@@ -54,8 +54,8 @@ Style/FrozenStringLiteralComment:
   Enabled: true
   EnforcedStyle: always
 
-Style/StringLiterals:
-  EnforcedStyle: single_quotes
+# Style/StringLiterals:
+#   EnforcedStyle: double_quotes
 
 Style/HashSyntax:
   EnforcedStyle: ruby19

data/.yardopts

@@ -1,12 +1,14 @@
 --markup markdown
 --markup-provider kramdown
---output-dir docs
---exclude spec/
---exclude vendor/
 --main README.md
---title "Whodunit API Documentation"
---charset utf-8
+--output-dir docs
+--protected
+--private
+--title "Whodunit Chronicles API Documentation"
+--readme README.md
+--files CHANGELOG.md,LICENSE
 lib/**/*.rb
 -
 README.md
 CHANGELOG.md
+LICENSE

data/CHANGELOG.md

@@ -5,6 +5,130 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
+## [0.3.0] - 2026-05-17
+
+### Added
+
+- **`CompositeProcessor`** — fans out a single change event to multiple processors
+  in sequence, enabling pipeline architectures (e.g. simultaneously storing audit
+  records, streaming to Grafana, and triggering alerts) without coupling processors
+  to each other. Fail-open by default: if one processor raises, the error is logged
+  and the remaining processors still execute. Set `fail_fast: true` to halt the
+  chain on the first error.
+- **Typed error hierarchy** — base `Whodunit::Chronicles::Error` class with typed
+  subclasses: `ConfigurationError`, `AdapterLoadError`, `ConnectionError`,
+  `ProcessingError`, `PersistenceError`. Callers can now rescue the base class to
+  catch all gem errors, or rescue specific subclasses for targeted handling.
+- **Lazy adapter loading** — `pg` and `trilogy` are now required only when the
+  matching adapter is actually used. A friendly `AdapterLoadError` with install
+  instructions is raised if the gem is missing, instead of a cryptic `LoadError`.
+- **`bin/console`** — loads the gem with a sane test config and drops into Pry
+  for interactive development.
+- **Docker Compose test environment** — spins up PostgreSQL 16 (`wal_level=logical`),
+  MySQL 8, and MariaDB 11 with matching audit databases, init SQL scripts, test
+  tables, publication setup, and replication role grants.
+- Development environment setup guide added to docs.
+
+### Fixed
+
+- Gemspec `homepage_uri` metadata corrected.
+- `pg`, `trilogy`, and `bigdecimal` moved from runtime to `add_development_dependency`
+  — consuming apps are no longer forced to install database adapters they don't use.
+- `rubocop-rake` and `rubocop-thread_safety` added to development dependencies.
+
+### Chore
+
+- `Gemfile.lock` removed from repo.
+- `.gitignore` updated with recommended exclusions.
+
+### Docs
+
+- Broken links in README fixed.
+- Development environment setup guide added.
+
+### ⚠️ Breaking Changes
+
+- `pg`, `trilogy`, and `bigdecimal` are no longer runtime dependencies. If your
+  application relies on them being pulled in transitively via `whodunit-chronicles`,
+  add them explicitly to your own Gemfile.
+- remove ruby@3.1 from the supported versions of Ruby
+
+## [0.2.0] - 2025-01-28
+
+### Added
+
+- **MySQL/MariaDB Support**: Complete multi-database adapter architecture
+  - MySQL adapter using trilogy gem for high-performance connections
+  - Binary log streaming support for MySQL change capture
+  - Cross-database compatibility testing
+- **Enhanced Testing Suite**: Comprehensive test coverage improvements
+  - New test files: `table_test.rb`, `connection_test.rb`, `persistence_test.rb`
+  - Enhanced PostgreSQL adapter tests with connection and replication scenarios
+  - Increased line coverage from 91.28% to 97.29% (+6.01 percentage points)
+  - 227 tests with 552 assertions providing robust validation
+- **Ruby 3.4+ Compatibility**: Forward compatibility improvements
+  - Added `bigdecimal` dependency for Ruby 3.4+ support
+  - Explicit dependency management for removed stdlib components
+- **CI/CD Enhancements**: Improved automation and quality gates
+  - Matrix testing across PostgreSQL and MySQL databases
+  - Enhanced MySQL integration testing with proper connection handling
+  - Security scanning integration and automated dependency updates
+
+### Changed
+
+- **Architecture Refactoring**: Modular component extraction
+  - Extracted AuditProcessor into separate, focused components
+  - Improved service layer with multi-adapter support patterns
+  - Enhanced configuration system supporting both PostgreSQL and MySQL
+- **Database Adapter Pattern**: Extensible multi-database support
+  - Abstract adapter base class for consistent interface
+  - Database-specific implementations with optimized performance
+  - Unified change event system across different database types
+- **Test Infrastructure**: Comprehensive testing improvements
+  - Enhanced mock-based testing for complex database operations
+  - Improved test organization with better separation of concerns
+  - Integration test scenarios for real-world usage patterns
+
+### Fixed
+
+- **MySQL CI Integration**: Resolved connection and setup issues
+  - Fixed MySQL container configuration and health checks  
+  - Improved database readiness detection and timeout handling
+  - Enhanced error reporting and debugging for CI environments
+- **Dependency Management**: Ruby version compatibility
+  - Added explicit `bigdecimal ~> 3.1` dependency for Ruby 3.4+
+  - Resolved trilogy gem loading issues in newer Ruby versions
+  - Improved gem specification with proper version constraints
+
+### Technical Improvements
+
+- **Code Coverage**: Significant testing improvements
+  - Line coverage: 97.29% (647/665 lines covered)
+  - Branch coverage: 83.6% (158/189 branches covered)
+  - Comprehensive unit tests for all core modules
+- **Performance Optimizations**: Multi-adapter efficiency
+  - Database-specific SQL generation and parameter binding
+  - Optimized connection management across different adapters
+  - Efficient batch processing for both PostgreSQL and MySQL
+- **Error Handling**: Enhanced resilience and debugging
+  - Improved error messages and stack trace reporting
+  - Better handling of database-specific error conditions
+  - Enhanced logging for troubleshooting and monitoring
+
+### Development Experience
+
+- **Documentation**: Enhanced developer resources
+  - Updated README with MySQL/MariaDB configuration examples
+  - Improved inline documentation for multi-adapter usage
+  - Better error messages and troubleshooting guides
+- **Testing Framework**: Improved development workflow
+  - Faster test execution with better mock strategies
+  - More reliable CI/CD pipeline with matrix testing
+  - Enhanced debugging capabilities for test failures
+
+## [0.1.0] - 2025-01-21
+
 ### Added
 
 - Comprehensive GitHub Actions CI/CD pipeline with multi-Ruby testing
@@ -30,7 +154,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Core Architecture**: Complete zero-latency audit streaming implementation
 - **PostgreSQL Adapter**: Logical replication streaming with WAL decoding
 - **ChangeEvent System**: Unified change representation across database adapters
-- **AuditProcessor**: Intelligent transformation of changes into audit records
+- **Processor**: Intelligent transformation of changes into audit records
 - **Configuration Management**: Comprehensive settings with validation using dry-configurable
 - **Service Orchestration**: Thread-safe service with error handling and retry logic
 - **Abstract Adapter Pattern**: Extensible design supporting multiple database systems

data/CONTRIBUTING.md

@@ -0,0 +1,186 @@
+# Contributing to Whodunit Chronicles
+
+Thank you for your interest in contributing! This document walks you through getting a working development environment set up, running the test suite, and submitting a pull request.
+
+---
+
+## Table of Contents
+
+1. [Prerequisites](#prerequisites)
+2. [Setting Up Your Environment](#setting-up-your-environment)
+3. [Database Setup](#database-setup)
+4. [Running the Tests](#running-the-tests)
+5. [Code Style](#code-style)
+6. [Opening a Pull Request](#opening-a-pull-request)
+7. [Contributing Custom Processors](#contributing-custom-processors)
+
+---
+
+## Prerequisites
+
+| Tool | Minimum Version | Notes |
+|------|----------------|-------|
+| Ruby | 3.1.0 | `rbenv` or `asdf` recommended |
+| Docker | 24+ | For running test databases |
+| Docker Compose | v2 plugin | Bundled with Docker Desktop |
+| Git | Any recent | |
+
+---
+
+## Setting Up Your Environment
+
+```bash
+git clone https://github.com/kanutocd/whodunit-chronicles.git
+cd whodunit-chronicles
+
+# Install dependencies
+bundle install
+
+# Verify the console works
+bundle exec bin/console
+```
+
+---
+
+## Database Setup
+
+Chronicles streams directly from PostgreSQL logical replication and MySQL/MariaDB binary logs. The test suite needs real database processes — no SQLite or in-memory substitute.
+
+**Start all test databases with Docker Compose:**
+
+```bash
+docker compose up -d
+```
+
+This starts:
+
+| Service | Port | Purpose |
+|---------|------|---------|
+| PostgreSQL 16 (wal_level=logical) | 5432 | Source DB for pg tests |
+| PostgreSQL 16 (audit store) | 5433 | Audit DB for pg tests |
+| MySQL 8.0 (binlog ROW format) | 3306 | Source DB for MySQL tests |
+| MySQL 8.0 (audit store) | 3307 | Audit DB for MySQL tests |
+| MariaDB 11 (binlog ROW format) | 3308 | Source DB for MariaDB tests |
+
+Wait for all services to be healthy before running tests:
+
+```bash
+docker compose ps   # all should show "(healthy)"
+```
+
+### PostgreSQL — enabling logical replication
+
+The Docker image is pre-configured (`wal_level=logical`). If you're using a system Postgres instead, add to `postgresql.conf`:
+
+```
+wal_level = logical
+max_replication_slots = 10
+max_wal_senders = 10
+```
+
+Then restart Postgres and grant the replication role to your user:
+
+```sql
+ALTER ROLE your_user WITH REPLICATION;
+```
+
+### MySQL — enabling binary logging
+
+The Docker image launches with `--binlog-format=ROW --binlog-row-image=FULL`. If using a system MySQL, add to `my.cnf`:
+
+```ini
+[mysqld]
+server-id       = 1
+log-bin         = mysql-bin
+binlog-format   = ROW
+binlog-row-image = FULL
+```
+
+---
+
+## Running the Tests
+
+```bash
+# Full suite
+bundle exec rake test
+
+# Single file
+bundle exec ruby test/whodunit/chronicles/composite_processor_test.rb
+
+# With coverage report
+bundle exec rake test
+open coverage/index.html
+
+# Code style
+bundle exec rubocop
+
+# Security scan
+bundle exec bundler-audit check --update
+bundle exec brakeman
+```
+
+### Environment variables for test databases
+
+The test suite reads these environment variables (defaults match the Docker Compose setup):
+
+| Variable | Default |
+|----------|---------|
+| `CHRONICLES_PG_URL` | `postgresql://chronicles:chronicles@localhost/chronicles_test` |
+| `CHRONICLES_PG_AUDIT_URL` | `postgresql://chronicles:chronicles@localhost:5433/chronicles_audit_test` |
+| `CHRONICLES_MYSQL_URL` | `mysql://chronicles:chronicles@localhost:3306/chronicles_test` |
+| `CHRONICLES_MYSQL_AUDIT_URL` | `mysql://chronicles:chronicles@localhost:3307/chronicles_audit_test` |
+
+---
+
+## Code Style
+
+- All files must have `# frozen_string_literal: true`
+- Public methods require YARD documentation
+- Follow the existing RuboCop configuration (`.rubocop.yml`)
+- Tests live in `test/` and use Minitest
+
+---
+
+## Opening a Pull Request
+
+1. Fork the repository and create a feature branch:
+   ```bash
+   git checkout -b feature/my-improvement
+   ```
+
+2. Make your changes with tests. Coverage should not drop below 90%.
+
+3. Run the full quality check before pushing:
+   ```bash
+   bundle exec rake test
+   bundle exec rubocop
+   bundle exec bundler-audit check --update
+   ```
+
+4. Push and open a PR with:
+   - A clear description of what changed and why
+   - Any migration steps if you changed configuration
+   - A note on which databases you tested against
+
+---
+
+## Contributing Custom Processors
+
+The best contributions are custom processors for real-world domains. Here are domains we'd love to see:
+
+- **E-commerce** — order tracking, inventory changes, cart events
+- **Financial services** — transaction monitoring, compliance audit trails
+- **Healthcare** — patient record changes, HIPAA-relevant audit events
+- **SaaS** — feature flag changes, subscription events, seat management
+- **Education** — student progress, grade changes, enrollment events
+
+A good processor contribution includes:
+
+1. The processor class in `lib/whodunit/chronicles/processors/`
+2. Tests in `test/whodunit/chronicles/processors/`
+3. A usage example in `examples/`
+4. An entry in `CHANGELOG.md`
+
+---
+
+Questions? Open an issue or start a discussion on GitHub.

data/README.md

@@ -1,4 +1,4 @@
-# 📚 Whodunit Chronicles
+# 📜 Whodunit Chronicles
 
 [![Gem Version](https://badge.fury.io/rb/whodunit-chronicles.svg)](https://badge.fury.io/rb/whodunit-chronicles)
 [![CI](https://github.com/kanutocd/whodunit-chronicles/workflows/CI/badge.svg)](https://github.com/kanutocd/whodunit-chronicles/actions)
@@ -14,9 +14,9 @@ While [Whodunit](https://github.com/kanutocd/whodunit) tracks _who_ made changes
 
 ## ✨ Features
 
-- **🚄 Zero-Latency Streaming**: PostgreSQL logical replication
+- **🚄 Zero-Latency Streaming**: PostgreSQL logical replication + MySQL/MariaDB binary log streaming
 - **🔄 Zero Application Overhead**: No Rails callbacks or Active Record hooks required
-- **🏗️ Database Agnostic**: Abstract adapter pattern supports PostgreSQL (TODO: MySQL/MariaDB support)
+- **🏗️ Database Agnostic**: Abstract adapter pattern supports PostgreSQL and MySQL/MariaDB
 - **⚡ Thread-Safe**: Concurrent processing with configurable thread pools
 - **🛡️ Resilient**: Built-in error handling, retry logic, and monitoring
 - **📊 Complete Audit Trail**: Captures INSERT, UPDATE, DELETE with full before/after data
@@ -36,7 +36,7 @@ Perfect for applications that need comprehensive change tracking alongside Whodu
 
 ```ruby
 # Basic setup for user activity tracking
-class BasicAuditProcessor < Whodunit::Chronicles::AuditProcessor
+class BasicProcessor < Whodunit::Chronicles::Processor
   def build_chronicles_record(change_event)
     super.tap do |record|
       # Add basic business context
@@ -66,7 +66,7 @@ Sophisticated business intelligence for talent acquisition platforms:
 
 ```ruby
 # Advanced processor for recruitment metrics
-class RecruitmentAnalyticsProcessor < Whodunit::Chronicles::AuditProcessor
+class RecruitmentAnalyticsProcessor < Whodunit::Chronicles::Processor
   def build_chronicles_record(change_event)
     super.tap do |record|
       # Add recruitment-specific business metrics
@@ -151,19 +151,19 @@ The recruitment analytics processor creates comprehensive Grafana dashboards for
 <a href="examples/images/campaign-performance-analytics.png" title="Click to view full size image">
 <img src="examples/images/campaign-performance-analytics.png" width="300" />
 </a>
-*Track campaign ROI, cost-per-hire by channel, and conversion rates across marketing sources*
+_Track campaign ROI, cost-per-hire by channel, and conversion rates across marketing sources_
 
-**Candidate Journey Analytics** 
+**Candidate Journey Analytics**
 <a href="examples/images/candidate-journey-analytics.png" title="Click to view full size image">
 <img src="examples/images/candidate-journey-analytics.png" width="300" />
 </a>
-*Monitor candidate engagement, funnel conversion rates, and application completion patterns*
+_Monitor candidate engagement, funnel conversion rates, and application completion patterns_
 
 **Recruitment Funnel Analytics**
 <a href="examples/images/recruitment-funnel-analytics.png" title="Click to view full size image">
 <img src="examples/images/recruitment-funnel-analytics.png" width="300" />
 </a>
-*Analyze hiring pipeline progression, department performance, and time-series trends*
+_Analyze hiring pipeline progression, department performance, and time-series trends_
 
 </div>
 
@@ -188,7 +188,9 @@ gem install whodunit-chronicles
 ```ruby
 require 'whodunit/chronicles'
 
-# PostgreSQL Configuration
+# Database Configuration
+
+## PostgreSQL Configuration
 Whodunit::Chronicles.configure do |config|
   config.adapter = :postgresql
   config.database_url = 'postgresql://localhost/myapp_production'
@@ -197,6 +199,14 @@ Whodunit::Chronicles.configure do |config|
   config.replication_slot_name = 'myapp_chronicles_slot'
 end
 
+## MySQL/MariaDB Configuration
+Whodunit::Chronicles.configure do |config|
+  config.adapter = :mysql
+  config.database_url = 'mysql://user:password@localhost/myapp_production'
+  config.audit_database_url = 'mysql://user:password@localhost/myapp_audit'
+  config.mysql_server_id = 1001  # Unique server ID for replication
+end
+
 # Create and start the service
 service = Whodunit::Chronicles.service
 service.setup!  # Create publication/replication setup
@@ -212,7 +222,7 @@ service.teardown!  # Clean up database objects
 
 ## 🏗️ Architecture
 
-Chronicles uses **PostgreSQL logical replication** (TODO: **MySQL/MariaDB binary log streaming**) to capture database changes without impacting your application:
+Chronicles uses **PostgreSQL logical replication** and **MySQL/MariaDB binary log streaming** to capture database changes without impacting your application:
 
 ```
 ┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
@@ -233,9 +243,9 @@ Chronicles uses **PostgreSQL logical replication** (TODO: **MySQL/MariaDB binary
 
 ### Core Components
 
-- **StreamAdapter**: Database-specific change streaming (PostgreSQL, MySQL/MariaDB)
+- **StreamAdapter**: Database-specific change streaming (PostgreSQL logical replication, MySQL/MariaDB binary log streaming)
 - **ChangeEvent**: Unified change representation across adapters
-- **AuditProcessor**: Transforms changes into searchable audit records
+- **Processor**: Transforms changes into searchable audit records
 - **Service**: Orchestrates streaming with error handling and retry logic
 
 ## ⚙️ Configuration
@@ -311,7 +321,7 @@ Transform database changes into actionable business intelligence with features l
 #### Analytics-Focused Processor
 
 ```ruby
-class AnalyticsProcessor < Whodunit::Chronicles::AuditProcessor
+class AnalyticsProcessor < Whodunit::Chronicles::Processor
   def build_chronicles_record(change_event)
     super.tap do |record|
       # Add business metrics
@@ -365,7 +375,7 @@ end
 #### Grafana Dashboard Ready
 
 ```ruby
-class GrafanaProcessor < Whodunit::Chronicles::AuditProcessor
+class GrafanaProcessor < Whodunit::Chronicles::Processor
   def build_chronicles_record(change_event)
     {
       # Core metrics for Grafana time series
@@ -399,7 +409,7 @@ end
 #### Real-Time Alerts Processor
 
 ```ruby
-class AlertingProcessor < Whodunit::Chronicles::AuditProcessor
+class AlertingProcessor < Whodunit::Chronicles::Processor
   def process(change_event)
     record = build_chronicles_record(change_event)
 
@@ -436,7 +446,7 @@ end
 # Chain multiple processors for different purposes
 service = Whodunit::Chronicles::Service.new(
   adapter: Adapters::PostgreSQL.new,
-  processor: CompositeProcessor.new([
+  processor: Whodunit::Chronicles::CompositeProcessor.new([
     AnalyticsProcessor.new,     # For business intelligence
     AlertingProcessor.new,      # For real-time monitoring
     ComplianceProcessor.new,    # For regulatory requirements
@@ -615,13 +625,14 @@ We especially welcome custom processors for different business domains. Consider
 
 - **Ruby**: 3.1.0 or higher
 - **PostgreSQL**: 10.0 or higher (with logical replication enabled)
+- **MySQL/MariaDB**: 5.6+ (with binary logging enabled)
 
 ## 🗺️ Roadmap
 
 - [ ] **Prometheus Metrics**: Production monitoring integration (with complete codebase included in examples/)
 - [ ] **Advanced Example Apps**: Real-world use cases with complete monitoring stack (with complete codebase included in examples/)
 - [ ] **Custom Analytics Processors**: Business intelligence and real-time monitoring (with complete codebase included in examples/)
-- [ ] **MySQL/MariaDB Support**: MySQL/MariaDB databases binlog streaming adapter
+- [x] **MySQL/MariaDB Support**: MySQL/MariaDB databases binlog streaming adapter
 - [ ] **Redis Streams**: Alternative lightweight streaming backend
 - [ ] **Compression**: Optional audit record compression
 - [ ] **Retention Policies**: Automated audit record cleanup
@@ -630,10 +641,11 @@ We especially welcome custom processors for different business domains. Consider
 ## 📚 Documentation
 
 - **[API Documentation](https://kanutocd.github.io/whodunit-chronicles/)**
-- **[Configuration Guide](docs/configuration-todo.md)**
-- **[Architecture Deep Dive](docs/architecture-todo.md)**
-- **[PostgreSQL Setup](docs/postgresql-setup-todo.md)**
-- **[Production Deployment](docs/production-todo.md)**
+- [ ] TODO: **Configuration Guide** _(docs/configuration-todo.md)_
+- [ ] TODO: **Architecture Deep Dive** _(docs/architecture-todo.md)_
+- [ ] TODO: **PostgreSQL Setup** _(docs/postgresql-setup-todo.md)_
+- [ ] TODO: **MySQL/MariaDB Setup** _(docs/mysql-setup.md)_
+- [ ] TODO: **Production Deployment** _(docs/production-todo.md)_
 
 ## 📄 License
 

data/docker/mysql/init.sql

@@ -0,0 +1,33 @@
+-- docker/mysql/init.sql
+-- Run once when the MySQL/MariaDB container is first created.
+
+USE chronicles_test;
+
+CREATE TABLE IF NOT EXISTS users (
+  id         INT AUTO_INCREMENT PRIMARY KEY,
+  name       VARCHAR(255) NOT NULL,
+  email      VARCHAR(255) NOT NULL UNIQUE,
+  creator_id INT          DEFAULT NULL,
+  updater_id INT          DEFAULT NULL,
+  deleter_id INT          DEFAULT NULL,
+  created_at DATETIME(6)  NOT NULL DEFAULT NOW(6),
+  updated_at DATETIME(6)  NOT NULL DEFAULT NOW(6) ON UPDATE NOW(6)
+);
+
+CREATE TABLE IF NOT EXISTS posts (
+  id         INT AUTO_INCREMENT PRIMARY KEY,
+  user_id    INT          NOT NULL,
+  title      VARCHAR(500) NOT NULL,
+  body       TEXT,
+  status     VARCHAR(50)  DEFAULT 'draft',
+  creator_id INT          DEFAULT NULL,
+  updater_id INT          DEFAULT NULL,
+  deleter_id INT          DEFAULT NULL,
+  created_at DATETIME(6)  NOT NULL DEFAULT NOW(6),
+  updated_at DATETIME(6)  NOT NULL DEFAULT NOW(6) ON UPDATE NOW(6),
+  FOREIGN KEY (user_id) REFERENCES users (id)
+);
+
+-- Grant replication privileges to the chronicles user
+GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'chronicles'@'%';
+FLUSH PRIVILEGES;

data/docker/postgres/init.sql

@@ -0,0 +1,40 @@
+-- docker/postgres/init.sql
+-- Run once when the container is first created.
+-- Sets up the replication role and test tables used by the test suite.
+
+-- Allow the chronicles user to create replication slots and use logical replication
+ALTER ROLE chronicles WITH REPLICATION;
+
+-- Grant superuser for test convenience (never do this in production)
+-- Remove this line and grant only necessary permissions for a tighter setup.
+ALTER ROLE chronicles WITH SUPERUSER;
+
+-- Create the test tables Chronicles will stream from
+\c chronicles_test
+
+CREATE TABLE IF NOT EXISTS users (
+  id           SERIAL PRIMARY KEY,
+  name         VARCHAR(255) NOT NULL,
+  email        VARCHAR(255) NOT NULL UNIQUE,
+  creator_id   INTEGER,
+  updater_id   INTEGER,
+  deleter_id   INTEGER,
+  created_at   TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  updated_at   TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS posts (
+  id           SERIAL PRIMARY KEY,
+  user_id      INTEGER NOT NULL REFERENCES users(id),
+  title        VARCHAR(500) NOT NULL,
+  body         TEXT,
+  status       VARCHAR(50) DEFAULT 'draft',
+  creator_id   INTEGER,
+  updater_id   INTEGER,
+  deleter_id   INTEGER,
+  created_at   TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  updated_at   TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+-- Publication used by the Chronicles PostgreSQL adapter
+CREATE PUBLICATION chronicles_test_pub FOR TABLE users, posts;