$30 off During Our Annual Pro Sale. View Details »

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

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

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ͷείʔϓ͸ʮਖ਼͍͠υΩϡϝϯτ͸ਖ਼͍͠σʔλͰ͋ ΓɺυΩϡϝϯτͷൣᙝΛӽ͑ྑ࣭ͳೖྗʹͳΔʯ