Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sarub0b0/trabox
Transactional outbox pattern for Rails
https://github.com/sarub0b0/trabox
microservice rails trabox transactional-outbox
Last synced: 2 months ago
JSON representation
Transactional outbox pattern for Rails
- Host: GitHub
- URL: https://github.com/sarub0b0/trabox
- Owner: sarub0b0
- License: mit
- Created: 2022-11-13T15:38:54.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-11-22T02:15:15.000Z (2 months ago)
- Last Synced: 2024-11-22T03:20:03.014Z (2 months ago)
- Topics: microservice, rails, trabox, transactional-outbox
- Language: Ruby
- Homepage: https://rubygems.org/gems/trabox
- Size: 457 KB
- Stars: 8
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.ja.md
- License: MIT-LICENSE
Awesome Lists containing this project
README
# Trabox
\[[Japanese](README.ja.md)]\[[English](README.md)]
Transactional-Outbox for Rails.
![](./docs/images/architecture.jpg)
## 機能
- Transactional-Outbox パターンでのイベントデータ公開
- 複数のデータベース・Outbox テーブルに対応
- `publish/subscribe`メソッドをもつ自作の publisher/subscriber を使用可能
- dogstatsd ベースのメトリクス
- 受信するメッセージの順序を維持する**サポートしている publisher**
- Google Cloud Pub/Sub
## 必要条件
- Ruby 2.6+
- Rails 6.0+## インストール
`Gemfile`に下記を追記
```ruby
gem 'trabox'
```下記コマンドを実行
```bash
bundle install
bin/rails g trabox:configure
```これで、`config/initializers/trabox.rb`ファイルが生成されます。
**オプション**
```bash
bundle binstubs trabox
```## 使い方
### outbox テーブルの作成
下記コマンドで outbox モデルのファイルが作成されます。
`bin/rails g model`のオプションを使えるので、必要に応じて変更してください。```bash
# generate model
bin/rails g trabox:model# Help
$ bin/rails g trabox:model --help
Usage:
rails generate trabox:model NAME [field[:type][:index] field[:type][:index]] [options]
...
```**追加のオプション: --polymorphic=\** オプションをつけると`references`カラムが追加されます。
このオプションはイミュータブルデータモデルに基づいた設計のときにイベントデータと outbox データを関連づけるのに使用します。例:`bin/rails g trabox:model event --polymorphic=event`
```ruby
class CreateEvents < ActiveRecord::Migration[6.1]
def change
create_table :events do |t|
t.references :event, polymorphic: true, null: false # --polymorphicオプションで生成されたカラム
t.binary :event_data
t.string :message_id
t.datetime :published_att.timestamps
end
end
end
```### Event データの登録
Publish するイベントデータを作成した outbox テーブルに登録します。
```ruby
# Your rails application
ActiveRecord::Base.transaction do
user = User.create! name: 'hoge'Event.create! event_data:
end
```### Relayer 実行
```bash
bin/trabox relay# Help
bin/trabox relay -h
Usage: trabox relay [OPTIONS]Overwrite configuration
-l, --limit NUM
-i, --interval SEC
-L, --[no-]lock
--log-level LEVEL```
#### Subscriber 実行
```bash
bin/trabox subscribe# Help
bin/trabox subscribe -h
Usage: trabox subscribe [OPTIONS]Overwrite configuration
--log-level LEVEL
```## メトリクス
メトリクスの名前空間の初期値は`trabox`です。
名前空間は`TRABOX_METRIC_NAMESPACE`環境変数で変更可能です。| 名前 | 説明 |
| ------------------------------- | ------------------------------------------------ |
| unpublished_event_count | パブリッシュするイベント数 |
| published_event_count | パブリッシュしたイベント数 |
| find_events_error_count | パブリッシュするイベントの取得に失敗した数 |
| publish_event_error_count | イベントのパブリッシュに失敗した数 |
| update_event_record_error_count | パブリッシュしたイベントのカラム更新に失敗した数 |### Health check
| command | metric name |
| --------- | ----------------------- |
| relay | relay.service.check |
| subscribe | subscribe.service.check |## Sequence diagram
![](./docs/images/sequence-diagram.svg)
## Contributing
Bug reports and pull requests are welcome.
## Development
### Install gems
```bash
bundle install
```### Start mysql / pubsub emulator
```bash
docker-compose up
```**setup db**
```bash
cd spec/rails_app
bin/rails db:setup
```**create topic / subscribe**
```bash
rake trabox:pubsub_setup
```### Test
```bash
bin/rspec
```## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).