active_record_mysql_repl 0.1.3 → 0.1.5

data/README.md

@@ -1,38 +1,754 @@
 # ActiveRecordMysqlRepl
 
-TODO: Delete this and the text below, and describe your gem
+## Prerequisites
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/active_record_mysql_repl`. To experiment with that code, run `bin/console` for an interactive prompt.
+### Ruby version 3.0.0 or higher
 
-## Installation
+e.g) Using rbenv
+
+```bash
+$ rbenv install 3.3.6
+```
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+### mysql-client 8.0
 
-Install the gem and add to the application's Gemfile by executing:
+e.g) on macOS
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+$ brew install mysql-client@8.0
+$ gem install mysql2 -v 0.5.6 -- --with-ldflags=-L$(brew --prefix zstd)/lib --with-mysql-dir=/opt/homebrew/opt/mysql-client@8.4
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## Installation
+
+Just by installing the gem, you can use the `army` command.
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+$ gem install active_record_mysql_repl
+Successfully installed active_record_mysql_repl-x.x.x
+Parsing documentation for active_record_mysql_repl-x.x.x
+Installing ri documentation for active_record_mysql_repl-x.x.x
+Done installing documentation for active_record_mysql_repl after 0 seconds
+1 gem installed
+```
+
+```
+$ army
+ActiveRecordMysqlRepl Version: x.x.x
+```
+
+If you want to use the zsh completion, you can add the following line to your `.zshrc` file.
+
+```sh
+$ eval "$(army --zsh-completion)"
+```
+
+Then you can use the completion feature like below.
+
+```sh
+$ army [TAB]
+option
+-c  -- path to .armyrc file
+-d  -- Database name
+-e  -- output erd
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+### Sample Configurations
 
-## Development
+From the following link, you can Download the sample configuration files
+https://github.com/nogahighland/active_record_mysql_repl/tree/main/sample_config
+
+Also you can try with sample database on your local MySQL server
+https://github.com/nogahighland/active_record_mysql_repl/blob/main/sample_config/sample_db.sql
+
+### Sample Database
+
+```sql
+CREATE DATABASE test;
+```
+
+The sample configuration assumes the sample database is running on
+127.0.0.1:3306/test (user: root, password: root)
+
+```
+$ mysql -u root -p test < sample_db.sql
+```
+
+![image](https://github.com/user-attachments/assets/ddc59020-42db-4240-91db-76dae560fdf5)
+
+This ER Diagram can be generated by the following command
+
+```sh
+army -c sample_config/.army.sample.yml -d test -e erd
+```
+
+### Showcases
+
+```sh
+army -c /path/to/sample_config/.army.sample.yml -d test
+Ensureing connection to test on port 127.0.0.1:33060
+Loading tables
+Loading custom extensions from /path/to/sample_config/./.army.sample/extensions
+```
+
+Now you can access to the table classes as `User` if the table name is `users`.
+
+```rb
+[1] test(main)> User.all
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-12T12:57:38.581127 #2816] DEBUG -- :   User Load (10.5ms)  SELECT `users`.* FROM `users`
+[
+  [0] #<User:0x0000000123188de0> {
+    :id         => "1",
+    :login_id   => "user1",
+    :profile_id => 1
+  }
+]
+```
+
+</details>
+
+---
+
+`.d` method shows the schema of the table. Let's see the `Order` table schema.
+
+```rb
+[8] test(main)> Order.d
+```
+
+<details><summary>output:</summary>
+
+```
+D, [2024-12-12T12:32:20.100309 #2816] DEBUG -- :    (10.6ms)  DESCRIBE orders
+D, [2024-12-12T12:32:20.107976 #2816] DEBUG -- :    (6.9ms)  SHOW INDEX FROM orders
+# orders
++---------+-------------+------+-----+---------+-------+
+| Field   | Type        | Null | Key | Default | Extra |
++---------+-------------+------+-----+---------+-------+
+| id      | varchar(64) | NO   | PRI |         |       |
+| user_id | varchar(64) | NO   |     |         |       |
+| item_id | varchar(64) | NO   |     |         |       |
++---------+-------------+------+-----+---------+-------+
++--------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+| Table  | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | Visible | Expression |
++--------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+| orders | 0          | PRIMARY  | 1            | id          | A         | 1           |          |        |      | BTREE      |         |               | YES     |            |
++--------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+```
+
+</details>
+
+---
+
+`.ddl` method shows the DDL of the table.
+
+```rb
+[9] test(main)> Order.ddl
+```
+
+<details><summary>output:</summary>
+
+```
+D, [2024-12-12T12:32:21.878444 #2816] DEBUG -- :    (8.7ms)  SHOW CREATE TABLE orders
+CREATE TABLE `orders` (
+  `id` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL,
+  `user_id` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL,
+  `item_id` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL,
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin
+```
+
+</details>
+
+---
+
+`models` is globally defined to get and array of all the table classes. By `.map(&:d)` you can see the schema of all the tables.
+
+https://github.com/nogahighland/active_record_mysql_repl/blob/main/lib/active_record_mysql_repl/extensions/global.rb#L10-L12
+
+```rb
+[6] test(main)> puts models.map(&:d)
+```
+
+<details><summary>output:</summary>
+
+```
+D, [2024-12-12T01:26:36.677988 #25446] DEBUG -- :   Brand Load (2.1ms)  SELECT `brands`.* FROM `brands`
+D, [2024-12-12T01:26:36.681307 #25446] DEBUG -- :   Category Load (2.8ms)  SELECT `categories`.* FROM `categories`
+D, [2024-12-12T01:26:36.683967 #25446] DEBUG -- :   Item Load (2.0ms)  SELECT `items`.* FROM `items`
+D, [2024-12-12T01:26:36.687282 #25446] DEBUG -- :   Order Load (3.0ms)  SELECT `orders`.* FROM `orders`
+D, [2024-12-12T01:26:36.691204 #25446] DEBUG -- :   UserProfile Load (3.6ms)  SELECT `user_profiles`.* FROM `user_profiles`
+D, [2024-12-12T01:26:36.694081 #25446] DEBUG -- :   User Load (2.2ms)  SELECT `users`.* FROM `users`
+# users
++------------+-------------+------+-----+---------+-------+
+| Field      | Type        | Null | Key | Default | Extra |
++------------+-------------+------+-----+---------+-------+
+| id         | varchar(64) | NO   | PRI |         |       |
+| login_id   | varchar(64) | NO   |     |         |       |
+| profile_id | int         | YES  |     |         |       |
++------------+-------------+------+-----+---------+-------+
++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | Visible | Expression |
++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+| users | 0          | PRIMARY  | 1            | id          | A         | 1           |          |        |      | BTREE      |         |               | YES     |            |
++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+# user_profiles
++-------+-------------+------+-----+---------+-------+
+| Field | Type        | Null | Key | Default | Extra |
++-------+-------------+------+-----+---------+-------+
+| id    | varchar(64) | NO   | PRI |         |       |
+| name  | varchar(64) | NO   |     |         |       |
++-------+-------------+------+-----+---------+-------+
++---------------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+| Table         | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | Visible | Expression |
++---------------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+| user_profiles | 0          | PRIMARY  | 1            | id          | A         | 1           |          |        |      | BTREE      |         |               | YES     |            |
++---------------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+# orders
++---------+-------------+------+-----+---------+-------+
+| Field   | Type        | Null | Key | Default | Extra |
++---------+-------------+------+-----+---------+-------+
+| id      | varchar(64) | NO   | PRI |         |       |
+| user_id | varchar(64) | NO   |     |         |       |
+| item_id | varchar(64) | NO   |     |         |       |
++---------+-------------+------+-----+---------+-------+
++--------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+| Table  | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | Visible | Expression |
++--------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+| orders | 0          | PRIMARY  | 1            | id          | A         | 1           |          |        |      | BTREE      |         |               | YES     |            |
++--------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+# items
++-------------+-------------+------+-----+---------+-------+
+| Field       | Type        | Null | Key | Default | Extra |
++-------------+-------------+------+-----+---------+-------+
+| id          | varchar(64) | NO   | PRI |         |       |
+| category_id | varchar(64) | NO   |     |         |       |
+| brand_id    | varchar(64) | NO   |     |         |       |
++-------------+-------------+------+-----+---------+-------+
++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+| Table | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | Visible | Expression |
++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+| items | 0          | PRIMARY  | 1            | id          | A         | 1           |          |        |      | BTREE      |         |               | YES     |            |
++-------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+# categories
++-----------+-------------+------+-----+---------+-------+
+| Field     | Type        | Null | Key | Default | Extra |
++-----------+-------------+------+-----+---------+-------+
+| id        | varchar(64) | NO   | PRI |         |       |
+| name      | varchar(64) | NO   |     |         |       |
+| parent_id | varchar(64) | NO   |     |         |       |
++-----------+-------------+------+-----+---------+-------+
++------------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+| Table      | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | Visible | Expression |
++------------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+| categories | 0          | PRIMARY  | 1            | id          | A         | 2           |          |        |      | BTREE      |         |               | YES     |            |
++------------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+# brands
++-------+-------------+------+-----+---------+-------+
+| Field | Type        | Null | Key | Default | Extra |
++-------+-------------+------+-----+---------+-------+
+| id    | varchar(64) | NO   | PRI |         |       |
+| name  | varchar(64) | NO   |     |         |       |
++-------+-------------+------+-----+---------+-------+
++--------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+| Table  | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment | Visible | Expression |
++--------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+| brands | 0          | PRIMARY  | 1            | id          | A         | 1           |          |        |      | BTREE      |         |               | YES     |            |
++--------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+---------+------------+
+```
+
+</details>
+
+---
+
+To get the last record of order,
+
+```rb
+[1] test(main)> Order.last
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-11T23:45:49.743857 #96076] DEBUG -- :   Order Load (5.5ms)  SELECT `orders`.* FROM `orders` ORDER BY `orders`.`id` DESC LIMIT 1
+#<Order:0x00000001293677c8> {
+  :id      => "1",
+  :user_id => "1",
+  :item_id => "1"
+}
+```
+
+</details>
+
+---
+
+You can get the last order's user because `user_id` column exists on `orders` table. For the same reason you can get the order's item and its category too.
+All the associations are chainable by the native functionality of ActiveRecord.
+
+```rb
+[5] test(main)> Order.last.user
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-11T23:46:11.154678 #96076] DEBUG -- :   Order Load (6.9ms)  SELECT `orders`.* FROM `orders` ORDER BY `orders`.`id` DESC LIMIT 1
+D, [2024-12-11T23:46:11.176424 #96076] DEBUG -- :   User Load (2.9ms)  SELECT `users`.* FROM `users` WHERE `users`.`id` = '1' LIMIT 1
+#<User:0x000000012961fda8> {
+  :id         => "1",
+  :login_id   => "user1",
+  :profile_id => 1
+}
+```
+
+</details>
+
+```rb
+[7] test(main)> Order.last.item
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-11T23:46:17.098874 #96076] DEBUG -- :   Order Load (3.5ms)  SELECT `orders`.* FROM `orders` ORDER BY `orders`.`id` DESC LIMIT 1
+D, [2024-12-11T23:46:17.112940 #96076] DEBUG -- :   Item Load (2.2ms)  SELECT `items`.* FROM `items` WHERE `items`.`id` = '1' LIMIT 1
+#<Item:0x000000012a416c40> {
+  :id          => "1",
+  :category_id => "2",
+  :brand_id    => "1"
+}
+```
+
+</details>
+
+```rb
+[8] test(main)> Order.last.item.category
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-11T23:46:21.104696 #96076] DEBUG -- :   Order Load (2.1ms)  SELECT `orders`.* FROM `orders` ORDER BY `orders`.`id` DESC LIMIT 1
+D, [2024-12-11T23:46:21.106696 #96076] DEBUG -- :   Item Load (1.5ms)  SELECT `items`.* FROM `items` WHERE `items`.`id` = '1' LIMIT 1
+D, [2024-12-11T23:46:21.117169 #96076] DEBUG -- :   Category Load (2.5ms)  SELECT `categories`.* FROM `categories` WHERE `categories`.`id` = '2' LIMIT 1
+#<Category:0x000000012a5d7b38> {
+  :id        => "2",
+  :name      => "category2",
+  :parent_id => "1"
+}
+```
+
+</details>
+
+---
+
+A category's parent is fetched from the same table because `parent_id`'s `parent` is treated by `ActiveRecordMysqlRepl` as inplicitly pointing to the same table.
+
+```rb
+[9] test(main)> Order.last.item.category.parent
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-11T23:46:23.553443 #96076] DEBUG -- :   Order Load (2.0ms)  SELECT `orders`.* FROM `orders` ORDER BY `orders`.`id` DESC LIMIT 1
+D, [2024-12-11T23:46:23.555918 #96076] DEBUG -- :   Item Load (2.1ms)  SELECT `items`.* FROM `items` WHERE `items`.`id` = '1' LIMIT 1
+D, [2024-12-11T23:46:23.560142 #96076] DEBUG -- :   Category Load (3.8ms)  SELECT `categories`.* FROM `categories` WHERE `categories`.`id` = '2' LIMIT 1
+D, [2024-12-11T23:46:23.562496 #96076] DEBUG -- :   Category Load (1.3ms)  SELECT `categories`.* FROM `categories` WHERE `categories`.`id` = '1' LIMIT 1
+#<Category:0x000000012a73dd60> {
+  :id        => "1",
+  :name      => "category1",
+  :parent_id => ""
+}
+```
+
+</details>
+
+---
+
+You can get user's profile by `.profile` because the custom association is defined here
+
+https://github.com/nogahighland/active_record_mysql_repl/blob/main/sample_config/.army.sample/associations.sample.yml#L4-L8
+
+```rb
+[6] test(main)> Order.last.user.profile
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-12T18:23:41.382606 #2816] DEBUG -- :   Order Load (8.6ms)  SELECT `orders`.* FROM `orders` ORDER BY `orders`.`id` DESC LIMIT 1
+D, [2024-12-12T18:23:41.389954 #2816] DEBUG -- :   User Load (2.4ms)  SELECT `users`.* FROM `users` WHERE `users`.`id` = '1' LIMIT 1
+D, [2024-12-12T18:23:41.392060 #2816] DEBUG -- :   UserProfile Load (1.8ms)  SELECT `user_profiles`.* FROM `user_profiles` WHERE `user_profiles`.`id` = '1' LIMIT 1
+#<UserProfile:0x000000012330a010> {
+  :id   => "1",
+  :name => "user1"
+}
+```
+
+</details>
+
+---
+
+Even though `users.login_id` column exists, because the column is not an external key it should be ignored from the association.
+The column is ignored because the custom association is defined here and `User#login` causes a `NoMethodError`
+
+https://github.com/nogahighland/active_record_mysql_repl/blob/f52f04770425723f632220bb8031bf4b402020a6/sample_config/.army.sample/associations.sample.yml#L10-L13
+
+```rb
+[1] test(main)> User.last.login
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-12T22:17:49.291618 #37808] DEBUG -- :   User Load (2.5ms)  SELECT `users`.* FROM `users` ORDER BY `users`.`id` DESC LIMIT 1
+NoMethodError: undefined method `login' for an instance of User
+from /Users/hiroki.kishi/develop/private/active_record_mysql_repl/vendor/bundle/ruby/3.3.0/gems/activemodel-7.2.2/lib/active_model/attribute_methods.rb:512:in `method_missing'
+```
+
+</details>
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+---
+
+You can use transaction by globally defined `transaction`.
+
+```rb
+[7] test(main)> u2 = User.new(id:2, profile_id: up2, login_id: 'login2')
+[9] test(main)> up2 = UserProfile.new(id:2, name: 'user2');
+[10] test(main)> transaction { [u2, up2].map(&:save) }
+```
+
+<details><summary>output:</summary>
+
+```sql
+[9] test(main)> up2 = UserProfile.new(id:2, name: 'user2');
+[10] test(main)> transaction { [u2, up2].map(&:save) }
+D, [2024-12-12T22:25:32.266790 #37808] DEBUG -- :   TRANSACTION (2.2ms)  BEGIN
+D, [2024-12-12T22:25:32.272857 #37808] DEBUG -- :   User Create (8.3ms)  INSERT INTO `users` (`id`, `login_id`) VALUES ('2', 'login2')
+D, [2024-12-12T22:25:32.275213 #37808] DEBUG -- :   UserProfile Create (2.1ms)  INSERT INTO `user_profiles` (`id`, `name`) VALUES ('2', 'user2')
+D, [2024-12-12T22:25:32.281765 #37808] DEBUG -- :   TRANSACTION (6.4ms)  COMMIT
+[
+  [0] true,
+  [1] true
+]
+```
+
+</details>
+
+---
+
+The following example shows the following steps:
+
+1. Find the users with id 1 and 2
+2. Change the login_id of the users
+3. Show the changes
+4. Save the changes in a transaction
+
+```rb
+[11] test(main)> u1, u2 = User.find([1, 2])
+```
+
+<details><summary>Output:</summary>
+
+```rb
+D, [2024-12-12T22:27:55.979311 #37808] DEBUG -- :   User Load (11.7ms)  SELECT `users`.* FROM `users` WHERE `users`.`id` IN ('1', '2')
+[
+  [0] #<User:0x0000000144b325a0> {
+    :id         => "1",
+    :login_id   => "user1",
+    :profile_id => 1
+  },
+  [1] #<User:0x0000000144b32460> {
+    :id         => "2",
+    :login_id   => "login2",
+    :profile_id => nil
+  }
+]
+```
+
+</details>
+
+```rb
+[12] test(main)> [u1, u2].each { |u| u.login_id = "login_id#{u.id}" }
+```
+
+<details><summary>Output:</summary>
+
+```rb
+[
+  [0] #<User:0x0000000144b325a0> {
+    :id         => "1",
+    :login_id   => "login_id1",
+    :profile_id => 1
+  },
+  [1] #<User:0x0000000144b32460> {
+    :id         => "2",
+    :login_id   => "login_id2",
+    :profile_id => nil
+  }
+]
+```
+
+</details>
+
+```rb
+[13] test(main)> [u1, u2].map(&:changes)
+```
+
+<details><summary>Output:</summary>
+
+```rb
+[
+  [0] {
+    "login_id" => [
+      [0] "user1",
+      [1] "login_id1"
+    ]
+  },
+  [1] {
+    "login_id" => [
+      [0] "login2",
+      [1] "login_id2"
+    ]
+  }
+]
+```
+
+</details>
+
+```rb
+[14] test(main)> transaction { [u1, u2].map(&:save)  }
+```
+
+<details><summary>Output:</summary>
+
+```rb
+D, [2024-12-12T22:29:14.179176 #37808] DEBUG -- :   TRANSACTION (1.2ms)  BEGIN
+D, [2024-12-12T22:29:14.188392 #37808] DEBUG -- :   User Update (9.1ms)  UPDATE `users` SET `users`.`login_id` = 'login_id1' WHERE `users`.`id` = '1'
+D, [2024-12-12T22:29:14.191429 #37808] DEBUG -- :   User Update (2.6ms)  UPDATE `users` SET `users`.`login_id` = 'login_id2' WHERE `users`.`id` = '2'
+D, [2024-12-12T22:29:14.196802 #37808] DEBUG -- :   TRANSACTION (5.2ms)  COMMIT
+[
+  [0] true,
+  [1] true
+]
+```
+
+</details>
+
+---
+
+By `tab` (an alias to `tabulate`), the filtered records are shown in a table format. `.tab(orientation)` accepts the `:h(orizontal)` (default when <5 columns), and `:v(ertival)` (default when >=5 columns)
+
+https://github.com/nogahighland/active_record_mysql_repl/blob/9f7c91774b176e1204ed434dad2867721982c660/lib/active_record_mysql_repl/extensions/object.rb#L11
+
+```rb
+[3] test(main)> Order.all.tab
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-11T23:48:46.013935 #96381] DEBUG -- :   Order Load (2.2ms)  SELECT `orders`.* FROM `orders`
++----+---------+---------+
+| id | user_id | item_id |
++----+---------+---------+
+| 1  | 1       | 1       |
++----+---------+---------+
+```
+
+</details>
+
+---
+
+```rb
+[4] test(main)> Order.all.tab(:v)
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-11T23:48:49.461243 #96381] DEBUG -- :   Order Load (3.2ms)  SELECT `orders`.* FROM `orders`
++---------+-------+
+| Name    | Value |
++---------+-------+
+| id      | 1     |
+| user_id | 1     |
+| item_id | 1     |
++---------+-------+
+```
+
+</details>
+
+---
+
+`.j` is aliased to `.to_json` and `.jp` is defined to generate pretty json.
+
+https://github.com/nogahighland/active_record_mysql_repl/blob/9f7c91774b176e1204ed434dad2867721982c660/lib/active_record_mysql_repl/extensions/object.rb#L128-L132
+
+```rb
+[5] test(main)> Order.all.j
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-11T23:48:55.267761 #96381] DEBUG -- :   Order Load (4.4ms)  SELECT `orders`.* FROM `orders`
+[{"id":"1","user_id":"1","item_id":"1"}]
+```
+
+</details>
+
+```rb
+[6] test(main)> Order.all.jp
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-11T23:48:57.250492 #96381] DEBUG -- :   Order Load (1.8ms)  SELECT `orders`.* FROM `orders`
+[
+  {
+    "id": "1",
+    "user_id": "1",
+    "item_id": "1"
+  }
+]
+```
+
+</details>
+
+---
+
+`.csv(orientation)` is defined to generate csv format. The default orientation is same as `.tab`.
+
+https://github.com/nogahighland/active_record_mysql_repl/blob/9f7c91774b176e1204ed434dad2867721982c660/lib/active_record_mysql_repl/extensions/object.rb#L71
+
+```rb
+[1] test(main)> Order.all.csv
+```
+
+<details><summary>output:</summary>
+
+```
+D, [2024-12-12T01:29:12.844339 #26252] DEBUG -- :   Order Load (2.7ms)  SELECT `orders`.* FROM `orders`
+id,user_id,item_id
+1,1,1
+```
+
+</details>
+
+---
+
+`.cp` is defined to copy to clipboard the receiver object's `.to_s` representation.
+
+```rb
+[7] test(main)> Order.all.jp.cp
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-11T23:48:59.443202 #96381] DEBUG -- :   Order Load (2.0ms)  SELECT `orders`.* FROM `orders`
+true
+```
+
+</details>
+
+---
+
+`.exec_sql` is defined to execute the sql query and return the result as an array of hash.
+
+```rb
+[8] test(main)> exec_sql('select 1')
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-11T23:49:15.879841 #96381] DEBUG -- :    (1.2ms)  select 1
+[
+  [0] {
+    "1" => 1
+  }
+]
+```
+
+</details>
+
+---
+
+```rb
+[9] test(main)> exec_sql('select 1').tab
+```
+
+<details><summary>output:</summary>
+
+```rb
+D, [2024-12-11T23:49:17.187358 #96381] DEBUG -- :    (2.1ms)  select 1
++---+
+| 1 |
++---+
+| 1 |
++---+
+```
+
+</details>
+
+---
+
+```rb
+[10] test(main)> exec_sql('select 1 as num').tab
+```
+
+<details><summary>output:</summary>
+
+```
+D, [2024-12-11T23:49:22.406631 #96381] DEBUG -- :    (1.3ms)  select 1 as num
++-----+
+| num |
++-----+
+| 1   |
++-----+
+```
+
+</details>
+
+---
+
+You can define your own extension script. For example `.upcase_name` is defined on `UserProfile` by the sample extension which is specified in the `.army.sample.yml` file.
+
+- https://github.com/nogahighland/active_record_mysql_repl/blob/9f7c91774b176e1204ed434dad2867721982c660/sample_config/.army.sample.yml#L5
+- https://github.com/nogahighland/active_record_mysql_repl/blob/acaa44684ea4fd135225580431417d6ccd41a988/sample_config/.army.sample/extensions/hello.rb#L1-L9
+
+```rb
+[3] test(main)> UserProfile.last.upcase_name
+```
+
+<details><summary>output:</summary>
+
+```
+D, [2024-12-12T12:09:10.987656 #60808] DEBUG -- :   UserProfile Load (1.7ms)  SELECT `user_profiles`.* FROM `user_profiles` ORDER BY `user_profiles`.`id` DESC LIMIT 1
+USER1
+```
+
+</details>
+
+---
+
+## Development
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+TODO
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/active_record_mysql_repl. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/active_record_mysql_repl/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/nogahifhland/active_record_mysql_repl. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/nogahighland/active_record_mysql_repl/blob/main/CODE_OF_CONDUCT.md).
 
 ## License