Upgrade to Pro — share decks privately, control downloads, hide ads and more …

The future of tbls and "Documentation as Code" ...

The future of tbls and "Documentation as Code" / phpconfuk 2023

Avatar for Ken’ichiro Oyama

Ken’ichiro Oyama

June 24, 2023
Tweet

More Decks by Ken’ichiro Oyama

Other Decks in Technology

Transcript

  1. The future of tbls and “Documentation as Code" খࢁ݈Ұ࿠ /

    GMO PEPABO inc. 2023.6.24 PHPΧϯϑΝϨϯε෱Ԭ2023 1
  2. 5 ͸͡Ίʹ • tblsΛத৺ʹൃද͢Δͷ͸࣮ʹ5೥ͿΓ2ճ໨Ͱ͢ • ຊηογϣϯͰ͸tblsͱDocumentation as Codeʹ͍ͭͯ࿩͠·͢ • tblsͱDocumentation

    as Codeʹ͍ͭͯͷ5೥෼ͷूେ੒ʹͳΓ·͢ • օ͞Μʹ͸tblsͷ࿩Λฉ͖ͳ͕Β΋ɺ΋ͬͱந৅తͳʮυΩϡϝϯςʔγϣ ϯͷͨΊͷπʔϧʯΛΠϝʔδͯ͠΄͍͠Ͱ͢ • tblsʹݶͬͨ࿩Ͱ͸ͳ͍ͱࢲ͸৴͍ͯ͡·͢
  3. 6

  4. 7 About tbls tbls is a CI-Friendly tool for document

    a database, written in Go. • CIϑϨϯυϦͳσʔλϕʔευΩϡϝϯτੜ੒πʔϧ • ൃԻ͸ /ˈteɪbl ̩z/ʢςʔϒϧεʣ • PostgreSQL, MySQLͳͲͷRDBMS͚ͩͰͳ͘ɺBigQuery΍ Amazon DynamoDB, Cloud Spannerͱ͍༷ͬͨʑͳσʔλιʔ εʹରԠ • υΩϡϝϯτΛॆ࣮ͤ͞Δػೳͱͯ͠ϝλσʔλΛΞϊςʔ γϣϯ͢Δ͜ͱ͕Մೳ • ςʔϒϧɺΧϥϜͳͲͷίϝϯτ෇༩͚ͩͰͳ͘ϥϕ ϧɺϦϨʔγϣϯγοϓͳͲ
  5. 9 About tbls ϝτϦΫεͰݟΔtbls • 2018೥5݄17೔ʹ։ൃ։࢝ɻ2023೥6݄23೔࣌఺Ͱ1,863೔ʢ5ϱ೥1ϲ݄6೔ʣ • 14σʔλιʔεαϙʔτ • 1,816ίϛοτɻ392ϓϧϦΫΤετ

    • k1LoW୯ಠͰ1,146ίϛοτɺ303ϓϧϦΫΤετ • 170ϦϦʔε • όʔδϣϯv1.68.0 • ίʔυ9,690ߦ / ςετίʔυ3,958ߦ • k1LoW୯ಠͰ691,018 ++ / 603,716 -- • 2,477ελʔ
  6. %PDVNFOUBUJPOBT$PEF %PDTBT$PEF SFGFSTUPBQIJMPTPQIZUIBUZPV TIPVMECFXSJUJOHEPDVNFOUBUJPOXJUIUIFTBNFUPPMTBTDPEF *TTVF5SBDLFST 7FSTJPO$POUSPM (JU  1MBJO5FYU.BSLVQ .BSLEPXO

    SF4USVDUVSFE5FYU "TDJJEPD  $PEF3FWJFXT "VUPNBUFE5FTUT 5IJTNFBOTGPMMPXJOHUIFTBNFXPSL fl PXTBTEFWFMPQNFOUUFBNT BOECFJOH JOUFHSBUFEJOUIFQSPEVDUUFBN*UFOBCMFTBDVMUVSFXIFSFXSJUFSTBOE EFWFMPQFSTCPUIGFFMPXOFSTIJQPGEPDVNFOUBUJPO BOEXPSLUPHFUIFSUP NBLFJUBTHPPEBTQPTTJCMF ɹΑΓൈਮɹ  Documentation as Code
  7. 12 Documentation as Code Documentation as Codeͷݪ఺ • ʮDocumentation as

    Codeͱ͸ɺίʔυͱಉ͡πʔϧΛ࢖ͬͯυΩϡϝϯςʔγϣϯΛॻ͘΂͖ ͩͱ͍͏఩ֶʯby Write the DocsίϛϡχςΟ • Issue Trackers • Version Control (Git) • Plain Text Markup (Markdown, reStructuredText, Asciidoc) • Code Reviews • Automated Tests • γεςϜͷ։ൃͷۙ͘ʹυΩϡϝϯτ࡞੒ͷ࢓૊ΈΛஔ͘͜ͱͰɺ։ൃαΠΫϧͷதʹυΩϡϝ ϯτ࡞੒Λ౷߹͠ɺγεςϜͱυΩϡϝϯτͷဃ཭Λখ͘͞͠Α͏ͱ͍ͯ͠Δ͜ͱ͕Θ͔Δ
  8. 14 Documentation as Code γεςϜͱυΩϡϝϯτͷဃ཭ • ʮγεςϜͱυΩϡϝϯτͷဃ཭Λখ͘͞ʯ͚ͩͰ͸࣌ͱ࣮ͯ͠༻ʹ͸ݫ͍͠ • ဃ཭͕ʢগ͠Ͱ΋ʣ͋ΔͱԿ͕ਖ਼͍͔͕͠Θ͔Βͳ͘ͳΔ •

    ਓ͸γεςϜͱͷဃ཭Λൃݟ͢Δͱ΋͏ͦͷυΩϡϝϯτΛ৴༻͠ͳ͘ͳͬͯ͠·͏ • ׂΕ૭ཧ࿦ • υΩϡϝϯτ͕ߋ৽͞ΕΕ͹ɺਓ͸ߋ৽෼ʹ͍ͭͯਖ਼͍͔͠Ͳ͏͔ͷϨϏϡʔ͸Ͱ͖Δɻ͔͠ ͠ɺγεςϜ։ൃ͕ਐΜͰऔΓ࢒͞Εͯ͠·ͬͨυΩϡϝϯτͷϨϏϡʔͷλΠϛϯά͕ͳ͍ɻ
  9. 16 Documentation as Code+ ࣮༻తͳʢγεςϜͱဃ཭͠ͳ͍ͨΊͷʣDocumentation as Code • ͦ΋ͦ΋ʮγεςϜͱυΩϡϝϯτͷဃ཭ʯ͸ͳͥى͜Δͷ͔ •

    γεςϜ͸࣌ؒͷܦաʹΑͬͯมԽ͢Δ͕ɺυΩϡϝϯτ͸ͦͷมԽʹ௥ै͠ͳ͍͔Β ʢ΋͘͠͸௥ै͢Δʹ΋λΠϜϥά͕ൃੜ͢Δ͔Βʣ • ࣌ؒܦաʹ଱͑ΔͨΊʹ͸ɺ౎౓ɺγεςϜΛͦͷ··υΩϡϝϯτʢ΋͘͠͸υΩϡϝϯτͷ ਽ܗʣʹม׵Ͱ͖Ε͹ྑ͍ • ͜͜ͷϞσϧԽʹڵຯ͋Δํ͸ͪ͜Βˠ • ʮγεςϜΛͦͷ··ʯ
 ʹγεςϜ͔Βߏ଄ԽσʔλΛநग़͢Δ https://speakerdeck.com/k1low/web-system-architecture-number-8
  10. 17 Documentation as Code+ γεςϜͱυΩϡϝϯτͷဃ཭Λθϩʹ͢Δ • γεςϜ͔Βߏ଄ԽσʔλΛநग़ͯ͠ɺͦͷߏ଄Խσʔλ͔ΒυΩϡϝϯτΛੜ੒͢Δ • Α͘஌ΒΕ͍ͯΔ΋ͷͱͯ͠͸PHPDoc΍godocͱ͍ͬͨιʔείʔυ͔ΒυΩϡϝϯτΛ ੜ੒͢ΔΞϓϩʔνʢιʔείʔυ΋γεςϜͷࣸ૾ͱ͍͑Δʣ

    • ߏ଄Խσʔλ͔ΒγεςϜͱυΩϡϝϯτͷ྆ํΛੜ੒͢Δ • OpenAPI • Protocol Buffersʢprotocʣ • γεςϜͱυΩϡϝϯτͷဃ཭Λθϩʹ͢ΔDocumentation as CodeΛຊൃදʢ͚ͩʣͰ͸ Documentation as Code+ͱݺͿ
  11. 18 Documentation as Code+ tbls։ൃͷ͖͔͚ͬ • ౰࣌ΞϧϑΝஈ֊ͷϓϩδΣΫτͰઈࢍ։ൃதʹɺϓϩμΫτΦʔφʔ͕SQLΛॻ͘ਓͰʮσʔ λϕʔεఆٛॻ͸Ͳ͜ʹ͋Γ·͔͢ʁʯͱฉ͔Εͯ͠·ͬͨ • σʔλϕʔεεΩʔϚ΋೔ʑมΘ͍ͬͯΔΑ͏ͳϑΣʔζͰ৘ใ͕ϚΠάϨʔγϣϯϑΝΠ

    ϧͱίϛοτϩάʹ͔͠ͳ͔ͬͨ • γεςϜʢσʔλϕʔεʣͱυΩϡϝϯτͷ
 ဃ཭Λθϩʹ͢Δπʔϧͱͯ͠tblsͷ։ൃΛ
 ͸͡Ίͨ https://speakerdeck.com/k1low/pepabo-tech-conference-number-16
  12. 19 Documentation as Code+ Documentation as Code+ͷࢹ఺Ͱ࡞੒͞Εͨtbls • tbls͸ߏ଄Խσʔλʢσʔλϕʔεʣ͔ΒυΩϡϝϯτΛੜ੒͢ΔΞϓϩʔν •

    CIͰυΩϡϝϯτΛੜ੒͢Δ͜ͱͰܧଓతʹγεςϜͱͷဃ཭Λθϩʹ͢Δ • ʮContinuous Documentationʯ • CIϑϨϯυϦ=ϫϯόΠφϦͰ؆୯ʹΠϯετʔϧͰ͖Δ https://speakerdeck.com/k1low/pepabo-tech-conference-number-16
  13. 20 Documentation as Code+ k1LoW/setup-tbls • tblsΛηοτΞοϓ͢ΔAction for GitHub Actions

    • https://github.com/k1LoW/setup-tbls • ΑΓCIϑϨϯυϦʹ
  14. 27 Documentation as Code+ ਖ਼͍͠ɻ͕ɺ໾ʹཱͨͳ͍ • ਖ਼͍͠σʔλϕʔευΩϡϝϯτͰ͋Δͱ͍͏҆৺ײ͸ಘΒΕͨ • tblsద༻ҎલͰ͸ಘΒΕͳ͔ͬͨײ֮Ͱ͋Δ͜ͱ͸ؒҧ͍ͳ͍ •

    σʔλϕʔεͷςʔϒϧ΍ΧϥϜͷίϝϯτɺϦϨʔγϣϯ͕੔උ͞Ε͍ͯΔυΩϡϝϯτ͕͋ Δ͜ͱͰҰఆͷ໾ʹ͸ཱ͕ͭɺͦΕҎ্Ͱ΋ͦΕҎԼͰ΋ͳ͍ • γεςϜͷ։ൃϥΠϑαΠΫϧʹ͓͍ͯ໾ʹཱͭλΠϛϯά͕গͳ͍ • ·ͩ·ͩυΩϡϝϯτΛ׆༻Ͱ͖͍ͯΔͱ͸ݴ͑ͳ͍ͷͰ͸ʁ
  15. 29 Documentation as Code++ υΩϡϝϯτʢʹσʔλʣͷ׆༻ൣғΛ޿͛Δ • γεςϜͷ։ൃϥΠϑαΠΫϧʹ͓͍ͯʮσʔλϕʔεΛ࢖༻͢ΔλΠϛϯάʯʮσʔλϕʔε Λ࢖ͬͯߟ͑ΔλΠϛϯάʯ͸ଟ͋͘Δ͸ͣ • σʔλϕʔεʮυΩϡϝϯτʯ͚ͩͰ͸଍Γͳ͍ͷ͔΋͠Εͳ͍ɻ

    • γεςϜ͔Βநग़ͨ͠৘ใҎ֎ͷ৘ใ΋෇༩͢Δɻ • ʮσʔλϕʔευΩϡϝϯτʯͱ͍͏ܗ͕ࣜϚον͍ͯ͠ͳ͍ͷ͔΋͠Εͳ͍ɻ • ਖ਼͍͠σʔλϕʔευΩϡϝϯτ͸ਖ਼͍͠σʔλͰ͋Δͱ͍͑ΔͷͰσʔλ׆༻ͷ؍఺͔ Β઀఺Λ૿΍͢ɻ
  16. 33 Documentation as Code++ labels: / comments[].labels: / comments[].columnLabels: •

    εΩʔϚ΍ςʔϒϧ΍ΧϥϜʹϥϕϧΛ෇༩Ͱ͖Δ • ϥϕϧ͸BigQueryʹ͸ػೳͱͯ͠ଘࡏ͍ͯ͠Δ͕tblsΛ࢖͏͜ͱͰ͋ΒΏΔσʔλϕʔεͷ υΩϡϝϯτʹϥϕϧΛ෇༩Ͱ͖Δ • ϥϕϧ৘ใ͸ͦͷ··υΩϡϝϯτʹ΋ͦͷ··൓ө͞ΕΔ • ʮηϯγςΟϒ৘ใ͕ೖΔΧϥϜʹ `sesitive` ͱ͍͏ϥϕϧΛ෇༩͠ɺͦͷϥϕϧ͕͋ΔΧϥϜ ͷ৘ใʹ͸ϚεΫΛ͢ΔɻӾཡݖݶΛߜΔʯ
  17. 36 Documentation as Code++ schema.json • ߏ଄ԽσʔλΛυΩϡϝϯτʹ͚͔ͩ͠࢖Θͳ͍ͱ͍͏ͷ͸΋͍ͬͨͳ͍ • σʔλ׆༻ͷൣғΛ޿͛ΔͨΊʹɺtbls͕σʔλϕʔεεΩʔϚͱ.tbls.ymlΛ࢖༻ͯ͠υΩϡϝϯ τΛੜ੒͢ΔͨΊʹ಺෦Ͱߏங͍ͯ͠Δߏ଄Խσʔλʢschema.jsonʣΛग़ྗ͢ΔΑ͏ʹ͢Δ

    • ΋ͱ΋ͱ tbls out -t json Ͱग़ྗͰ͖Δ͕ɺv1.57.0͔Βtbls docͰ΋σϑΥϧτͰग़ྗ͢Δ Α͏ʹͨ͠ • σϑΥϧτͰग़ྗ͞Ε͍ͯΕ͹ग़ྗ͞Ε͍ͯΔલఏͰ࣮૷͕Ͱ͖Δ • schema.json͸tblsʹͱͬͯ͸MySQL΍PostgreSQLͱಉ͡σʔλιʔεͳͷͰɺ json:// εΩʔϜ ΍ github:// εΩʔϜΛ࢖ͬͯࢦఆ͢Δ͜ͱͰɺmysql:// ΍ pg:// ͱಉ༷ʹ࢖༻Ͱ͖Δ
  18. 38 Documentation as Code++ ֎෦αϒίϚϯυ΁ͷߏ଄Խσʔλͷड͚౉͠ • ghʢGitHub CLIʣίϚϯυ΍gitίϚϯυɺkubectlίϚϯυͷΑ͏ͳαϒίϚϯυ֦ுػೳ • ࣮͸tblsʹ΋͋ΔϓϥάΠϯػߏ

    • σʔλϕʔεͷղੳ΍.tbls.ymlͷ৘ใऔಘ͸tbls͕ߦ͍ɺαϒίϚϯυʹ͸ղੳ݁Ռͷ schema.json͕؀ڥม਺Λ௨ͯ͡౉Δ࢓૊Έ • .tbls.ymlͰهࡌͨ͠ίϝϯτ΍ϥϕϧΛ
 ٯʹBitQueryʹઃఆ͢Δtbls-metaͳͲ͕͋Δ • https://github.com/k1LoW/tbls-meta https://speakerdeck.com/k1low/pepabohatena
  19. 40 Documentation as Code++ ਖ਼͘͠ඞཁͳσʔλΛLLMʹ౉ͤΔͱ͍͏ϝϦοτ • tblsͰσʔλϕʔευΩϡϝϯτ͸ਖ਼͍͜͠ͱ͕෼͔͍ͬͯΔɻίϯςΩετ৘ใ΋ଟ࣋ͬͯ͘ ͍Δɻ • ίϝϯτ΍ؔ࿈ɺϏϡʔϙΠϯτͳͲ

    • ʮจষ͕༩͑ΒΕͨ࣌ɺ࣍ͷจষΛਪଌ͢Δʯͱ͍͏LLM͕ಘҙͱ͢Δ໰୊ʹ౰ͯ͸ΊΔ • ʮίϝϯτ෇͖ͷਖ਼͍͠σʔλϕʔεεΩʔϚʯͱʮ࣭໰ʯΛ༩͑ͯLLMʹਪଌͤ͞Δ • ۩ମతʹ͸ɺσʔλϕʔεεΩʔϚͱίϯςΩετʹԊͬͨΫΤϦΛ࡞੒ͤ͞Δ͜ͱ͕Մೳ
  20. 42 Documentation as Code++ υΩϡϝϯτ׆༻ͷΠϯλʔϑΣʔεΛ޿͛Δ • schema.jsonΛܦ༝͢Δ͜ͱͰʢ࣮σʔλϕʔεʹ઀ଓ͠ͳͯ͘΋ʣܧଓతʹਖ਼͍͠৘ใΛσʔ λΛऩू͢Δ͜ͱ͕Ͱ͖Δ • LLMʹΑͬͯʮਖ਼͍͠υΩϡϝϯτʢߏ଄ԽσʔλʣΛ࢖ͬͨਪଌʯͱ͍͏Ξϓϩʔν

    • ྫ͑͹ʮνϟοτϘοτʯͱ͍͏υΩϡϝϯτ׆༻ͷΠϯλʔϑΣʔε • ʮ@tbls-bot query minneͷྦྷੵྲྀ௨ֹͷ߹ܭʯʮSELECT * ʙʯ͕༰қʹ࣮ݱͰ͖Δɻ • ͞ΒʹΫΤϦͷ࣮ߦΛڐ͢ͷͰ͋Ε͹ • ʮ@tbls-bot minneͷྦྷੵྲྀ௨ֹͷ߹ܭΛڭ͑ͯʯʮ͸͍ɻ 2023೥6݄15೔࣌఺Ͱͷྦྷܭ ྲྀ௨ֹ߹ܭ͸1,000,00*,***,***Ͱ͢ɻ࣮ߦͨ͠ΫΤϦ͸XXXͰ͢ɻʯ͕࣮ݱͰ͖Δɻ
  21. 47 ͓ΘΓʹ ͓ΘΓʹ • ౴͑ͱͯ͠͸ʮΘ͔Γ·ͤΜɻ͔͠͠ɺDocumentation as Codeʹ͍ͭͯߟ͑ͳ͕Βɺܧଓత ʹ։ൃΛ͖ͯ͠·ͨ͠ʯ • Documentation

    as Codeͷݪ఺͸ʮυΩϡϝϯτΛίʔυͱಉ͡Α͏ʹӡ༻͍ͯ͘͠ʯ • ͦͯͦ͠ͷઌΛߟ࣮͑૷͖ͯͨ͠ɻ • ࠓ࣌఺ͷࢲͷDocumentation as Codeͷείʔϓ͸ʮਖ਼͍͠υΩϡϝϯτ͸ਖ਼͍͠σʔλͰ͋ ΓɺυΩϡϝϯτͷൣᙝΛӽ͑ྑ࣭ͳೖྗʹͳΔʯ