tblsを使ってみたい

用意した雑な環境

tree                                                                                                          main
.
├── LICENSE
├── Makefile
├── dbdocs
└── migrations
    └── 1_init.sql

3 directories, 3 files

CONTAINER_NAME = tbls-gettingstarted
MYSQL_ROOT_PASSWORD = rootpassword
MYSQL_DATABASE = ecsite-sample-shops
MYSQL_USER = user
MYSQL_PASSWORD = password
MYSQL_IMAGE = mysql:8.0

TBLS=tbls

.PHONY: start stop clean

start: clean
	docker run --name $(CONTAINER_NAME) \
		-e MYSQL_ROOT_PASSWORD=$(MYSQL_ROOT_PASSWORD) \
		-e MYSQL_DATABASE=$(MYSQL_DATABASE) \
		-e MYSQL_USER=$(MYSQL_USER) \
		-e MYSQL_PASSWORD=$(MYSQL_PASSWORD) \
		-v $(PWD)/migrations:/docker-entrypoint-initdb.d \
		-p 3306:3306 $(MYSQL_IMAGE)

stop:
	docker stop $(CONTAINER_NAME)

clean: stop
	docker rm $(CONTAINER_NAME)

mysqlcli:
	docker exec -it $(CONTAINER_NAME) mysql -u$(MYSQL_USER) -p$(MYSQL_PASSWORD) $(MYSQL_DATABASE)

tbls-docs:
	TBLS_DSN="mysql://$(MYSQL_USER):$(MYSQL_PASSWORD)@127.0.0.1:3306/$(MYSQL_DATABASE)" tbls doc ./dbdocs

CREATE TABLE items (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    price DECIMAL(10, 2) NOT NULL,
    stock INT DEFAULT 0
);

CREATE TABLE users (
    id INT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(255) NOT NULL UNIQUE,
    email VARCHAR(255) NOT NULL UNIQUE,
    password_hash VARCHAR(255) NOT NULL
);

CREATE TABLE current_cart (
    id INT AUTO_INCREMENT PRIMARY KEY,
    user_id INT NOT NULL UNIQUE,
    item_id INT NOT NULL,
    quantity INT NOT NULL DEFAULT 1,
    FOREIGN KEY (user_id) REFERENCES users(id),
    FOREIGN KEY (item_id) REFERENCES items(id)
);

CREATE TABLE orders (
    id INT AUTO_INCREMENT PRIMARY KEY,
    user_id INT NOT NULL,
    order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    total_amount DECIMAL(10, 2) NOT NULL,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

CREATE TABLE ordered_items (
    id INT AUTO_INCREMENT PRIMARY KEY,
    order_id INT NOT NULL,
    item_id INT NOT NULL,
    quantity INT NOT NULL,
    price_at_purchase DECIMAL(10, 2) NOT NULL,
    FOREIGN KEY (order_id) REFERENCES orders(id),
    FOREIGN KEY (item_id) REFERENCES items(id)
);

ara_ta3

dockerのtbls使うならdocker-composeが良さそうかなー

ara_ta3

brew installしたら依存のインストールに時間がかかったのでgo installしてる

 go install github.com/k1LoW/tbls@latest

ara_ta3

TBLS_DSN="mysql://user:password@127.0.0.1:3306/ecsite-sample-shops" tbls doc /path/to/tbls-getting-started/dbdocs
dial unix /path/to/tbls-getting-started/dbdocs/.s.PGSQL.5432: connect: no such file or directory
make: *** [Makefile:31: tbls-docs] Error 1

🤔

ara_ta3

環境変数への渡し方がおかしかったかな

ara_ta3

tbls.ymlに書いたら動いた

dsn: mysql://user:password@127.0.0.1:3306/ecsite-sample-shops
docPath: dbdocs

ara_ta3

生成したのがこれ

ara_ta3

こんなのを自動生成してくれるので、何もドキュメントがないとかだと今のをdumpするだけでも嬉しさありそうだな

ara_ta3

viewpointsの機能を使いたい

ara_ta3

これがchatgptに生成してもらったviewpointの設定ファイル
viewpoints.yml

viewpoints:
  - name: "business"
    description: "ビジネスロジックに関する観点"
    tables:
      items:
        description: "商品に関する情報を管理するテーブル"
        labels: ["重要", "参照頻度高"]
        columns:
          price:
            description: "商品の価格。変動する可能性があるため注意が必要"
            labels: ["価格", "注意"]

      orders:
        description: "注文情報を管理するテーブル"
        labels: ["重要"]
        columns:
          order_date:
            description: "注文が行われた日時"
            labels: ["タイムスタンプ", "集計対象"]

ara_ta3

全然違ったので古いのを参照していた可能性がある

が、動かない

めちゃくちゃ眠いので一旦やめてまた今度

設定のymlを分ける必要がなかった

dsn: mysql://user:password@127.0.0.1:3306/ecsite-sample-shops
docPath: dbdocs
viewpoints:
  - name: "business"
    desc: "hoge"
    tables:
      - orders
      - ordered_items
      - current_cart
    groups:
      - name: 注文関連
        desc: "fuga"
        tables: 
          - orders
          - ordered_items
          - current_cart

ara_ta3

viewpoints.ymlでviewpointsだけ分けていたのが必要なかったの意図

ara_ta3

groupsを追加するといいのかなと思ったけど、groupsに追加する場合同じテーブルは参照できないので別のviewpointを生やすほうがよかった

groupsに追加しようとしたら

tbls doc --config tbls.yml --rm-dist
viewpoint group '購入前' has duplicate tables [items]
make: *** [Makefile:31: tbls-docs] Error 1
zsh: exit 2     make tbls-docs

と怒られた
結果設定はこうなった

dsn: mysql://user:password@127.0.0.1:3306/ecsite-samples
docPath: dbdocs
viewpoints:
  - name: 注文
    desc: 注文した商品
    tables:
      - orders
      - ordered_items
      - items
      - users
    groups:
      - name: 注文
        desc: 注文した商品
        tables: 
          - orders
          - ordered_items
          - items
  - name: 購入前
    desc: 購入前の商品
    tables:
      - items
      - users
      - current_cart
    groups:
      - name: 購入前
        desc: 購入前の商品一覧
        tables:
          - current_cart
          - items
          - users
  - name: ユーザ
    desc: ユーザ一覧
    tables:
      - users
    groups:
      - name: ユーザ
        desc: ユーザ一覧
        tables:
          - users

ara_ta3

lintについて

lint:
  requireViewpoints:
    enabled: true

を追加してviewpointsのtableからcurrent_cartを削除すると↓のように怒られる

tbls lint
注文 orders
注文 ordered_items
注文 items
注文 users
購入前 items
購入前 users
ユーザ users
current_cart: table `current_cart` is not included in any viewpoints.

1 detected

ara_ta3

envからdnsを生成出来るらしい

./env

MYSQL_USER=user
MYSQL_PASSWORD=password
MYSQL_HOST=127.0.0.1

CONTAINER_NAME = tbls-gettingstarted
MYSQL_ROOT_PASSWORD = rootpassword
MYSQL_DATABASE = ecsite-samples
MYSQL_USER = user
MYSQL_PASSWORD = password
MYSQL_IMAGE = mysql:8.0

TBLS=set -o allexport && . ./env && tbls

include: ./env

.PHONY: start stop clean

start: clean
	docker run --name $(CONTAINER_NAME) \
		-e MYSQL_ROOT_PASSWORD=$(MYSQL_ROOT_PASSWORD) \
		-e MYSQL_DATABASE=$(MYSQL_DATABASE) \
		-e MYSQL_USER=$(MYSQL_USER) \
		-e MYSQL_PASSWORD=$(MYSQL_PASSWORD) \
		-v $(PWD)/migrations:/docker-entrypoint-initdb.d \
		-p 3306:3306 $(MYSQL_IMAGE)

stop:
	docker stop $(CONTAINER_NAME)

clean: stop
	docker rm $(CONTAINER_NAME)

mysqlcli:
	docker exec -it $(CONTAINER_NAME) mysql -u$(MYSQL_USER) -p$(MYSQL_PASSWORD) $(MYSQL_DATABASE)

tbls-docs:
	$(TBLS) doc --config tbls.yml --rm-dist

lint:
	$(TBLS) lint

diff:
	$(TBLS) diff

tbls.yml

dsn: "mysql://${MYSQL_USER}:${MYSQL_PASSWORD}@${MYSQL_HOST}:3306/ecsite-samples"
docPath: dbdocs
viewpoints:
  - name: 注文
    desc: 注文した商品
    tables:
      - orders
      - ordered_items
      - items
      - users
    groups:
      - name: 注文
        desc: 注文した商品
        tables: 
          - orders
          - ordered_items
          - items
  - name: 購入前
    desc: 購入前の商品
    tables:
      - items
      - users
      - current_cart
    groups:
      - name: 購入前
        desc: 購入前の商品一覧
        tables:
          - current_cart
          - items
          - users
  - name: ユーザ
    desc: ユーザ一覧
    tables:
      - users
    groups:
      - name: ユーザ
        desc: ユーザ一覧
        tables:
          - users
lint:
  requireViewpoints:
    enabled: true

ara_ta3

dnsを生成というかymlの内部に環境変数を使うことが出来るが正しいか

ara_ta3

記事にもまとめておきたいな
最小限のテーブルのdocs生成
viewpointsの生成
複数のテーブル郡についての説明をまとめることが出来る

差分がでたときの対応
lintとdiff
lintでrequireViewpointsを使ってviewpointsに追加することを強制する
diffで追加された差分がdocumentに取り込まれていない場合に修正を強制する

みたいな感じのまとめにする心持ちでいる

このスクラップは14日前にクローズされました