Как создать и протестировать GitHub Action, генерирующий типы из базы данных Supabase

Как генерировать типы из базы данных Supabase

В документации Supabase есть страница, посвященная генерации типов. Следуя инструкциям, сценарий для запуска выглядит примерно так.

Обратите внимание на дополнительный параметр --version=2. Вероятно, он стал обязательным после какого-то обновления инструмента openapi-typescript.

npx openapi-typescript https://{projectId}.supabase.co/rest/v1/?apikey={specialApiKey} --output=types/supabase.ts --version=2

Значения для ключа anon и URL можно найти в приборной панели Supabase.

Запуск сценария генерирует файл следующего вида. С помощью определений, сгенерированных в нем, я могу создать тип для Bill, используя только блок кода ниже.

import {definitions} from '../types/supabase';

export type Bill = definitions['Bill'];

Большая часть исходного кода моего проекта по-прежнему работает нормально после изменения типа. Единственный код, который мне пришлось рефакторить, связан с полем deadline, которое имеет тип Date. В определениях поле объявлено как строка, хотя они и признают, что оно имеет формат Date.

Bill: {
    /** Format: date */
    deadline?: string;
}

Лично я считаю, что это нормально, поскольку это заставляет вас преобразовывать объекты даты в соответствующие строки ISO, так что будет меньше двусмысленности при передаче объекта Date, который вы создали в JS, в Supabase. Если вам это не нравится, вы можете переопределить это в своем самообъявленном типе.

В ту же документацию они также включили раздел о том, как автоматически обновлять типы с помощью GitHub Actions. Это гарантирует, что всякий раз, когда вы обновляете базу данных, ваше действие GitHub автоматически обновит типы, которые есть в вашей БД. Тогда в следующий раз, когда вы будете доставать исходный код, вы будете знать, какие новые изменения произошли и как их приспособить.

В документации есть сценарий, который нужно добавить в package.json в таком виде.

"update-types": "npx openapi-typescript https://your-project.supabase.co/rest/v1/?apikey=your-anon-key --output types/database/index.ts"

Однако я не был слишком уверен, как безопасно заменить значения в скрипте package.json переменными окружения, когда я продвигаю исходный код. Я не очень хорошо знаком с синтаксисом bash, но предполагаю, что для моего проекта сценарий должен выглядеть примерно так.

"update-types": : "npx openapi-typescript https://${SUPABASE_URL}/rest/v1/?apikey=${ANON_KEY} --version=2 --output types/database/index.ts"

Чтобы дважды подтвердить синтаксис, я решил использовать плагин Sourcegraph Visual Studio Code для поиска проектов, в которых реализовано это действие на GitHub.

Перекрестные ссылки на код с помощью плагина Sourcegraph Visual Studio Code

Плагин Sourcegraph Visual Studio Code можно установить через панель расширений.

После его установки вы сможете найти значок Sourcegraph в боковой панели. Когда вы нажмете на него, вы увидите обычный пользовательский интерфейс для универсального поиска кода. Чтобы найти другие проекты, которые также генерируют типы, мы можем передать запрос npx openapi-typescript.

Мы видим довольно много результатов, и, к счастью, в третьем проекте под названием tone-row/flowchart-fun я вижу, что у них есть скрипт package.json, который выглядит как многообещающий кандидат. У них есть такие переменные, как SB_URL и SB_ANON_KEY, которые напоминают Supabase ✨.

"generate:types": "export $(cat .env.local | xargs) && npx openapi-typescript "${SB_URL}/rest/v1/?apikey=${SB_ANON_KEY}" --output types/database/index.ts",

С помощью этой перекрестной ссылки и знаний мы знаем, что нам не хватает обернуть всю конечную точку API в строку с управляющими символами. Тогда мы можем изменить наш предыдущий сценарий, чтобы он соответствовал этому сценарию.

"update-types": "npx openapi-typescript "${SUPABASE_URL}/rest/v1/?apikey=${SUPABASE_ANON_KEY}" --version=2 --output types/database/index.ts"

Если мы запустим этот скрипт локально через npm run update-types, мы увидим, что он генерирует тот же результат, что и предыдущий ✨.

Из любопытства я также хочу узнать, следует ли их рабочий процесс на GitHub той же структуре, что и в примере, приведенном в документации Supabase. Самое интересное, что с помощью плагина Sourcegraph я могу исследовать репозиторий в самом редакторе.

К сожалению, этот проект не использует сценарий generate:types, который они написали в рабочем процессе GitHub. Вероятно, они запускают сценарий npm только локально. К счастью, с помощью специалистов по документации Supabase нам, по крайней мере, не придется писать действие с нуля.

Как создать рабочий процесс GitHub

Этот раздел был объединен с документацией Supabase здесь после публикации этой статьи.

Чтобы добавить рабочие процессы действий GitHub в ваш проект, вам понадобится новая папка .github/workflows для хранения рабочих процессов. Для workflow.yml, который содержит шаги для рабочего процесса действий GitHub, мы будем использовать в качестве основы образец рабочего процесса действий GitHub в документации Supabase. Я немного изменил его, чтобы вставить некоторые секреты GitHub в качестве переменных окружения, вы можете обратиться к комментариям ниже.

name: Update database types

on:
  schedule:
    # sets the action to run daily. You can modify this to run the action more or less frequently
    - cron: '0 0 * * *'
    # for the workflow to be dispatched manually via GitHub actions dashboards.
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    env:
        SUPABASE_URL: ${{secrets.SUPABASE_URL}}
        SUPABASE_ANON_KEY: ${{secrets.SUPABASE_URL}}
    steps:
      - uses: actions/checkout@v2
        with:
          persist-credentials: false
          fetch-depth: 0
      - uses: actions/setup-node@v2.1.5
        with:
          node-version: 14
      # -- add echo -- #
      - run: |
          npm run update-types 
          echo "$(cat types/database/index.ts)"
      - name: check for file changes
        id: git_status
        run: |
          echo "::set-output name=status::$(git status -s)"
      - name: Commit files
        if: ${{contains(steps.git_status.outputs.status, ' ')}}
        # -- change git stage filename -- #
        run: |
          git add types/database/index.ts
          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git config --local user.name "billy-github-actions[bot]"
          git commit -m "Update database types" -a
      - name: Push changes
        if: ${{contains(steps.git_status.outputs.status, ' ')}}
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: ${{ github.ref }}

Изменения включают:

• Добавление триггера workflow_dispatch, чтобы рабочий процесс при необходимости можно было отправить вручную через дашборды действий GitHub.
• Добавление оператора echo для просмотра содержимого файла результатов выполнения сценария update-types.
• Передача секретов действий GitHub в переменные окружения.
• Измените имя файла для постановки на хранение

Если вы не знакомы с секретами действий GitHub, считайте, что это отдельные переменные окружения, предназначенные только для действий GitHub. Это скриншот того, где вы можете добавить их в настройках вашего проекта GitHub.

Чтобы развернуть рабочий процесс, просто переместите папку .github/workflows.

После этого вы увидите новый рабочий процесс доступным на вкладке Actions вашего проекта GitHub. Нажав на кнопку дополнительных опций, вы можете вручную отправить рабочий процесс.

Вы также можете просмотреть журналы каждого запуска рабочего процесса, если столкнетесь с какими-либо проблемами. Например, здесь, в успешном задании, я вижу содержимое файла src/types/supabase.ts, которое извлекается, поскольку мы вывели его в журнал в рамках шагов рабочего процесса.

В следующем разделе я познакомлю вас с удобным инструментом, который я узнал при создании пользовательского составного действия GitHub для локального тестирования действий GitHub.

Как тестировать действия GitHub локально с помощью act

act – это инструмент, позволяющий тестировать действия GitHub локально. Преимущество этого инструмента в том, что вы быстрее получаете обратную связь, не засоряя историю GitHub Action Runner в вашем проекте.

Обратитесь к README.md репозитория GitHub, чтобы узнать, как установить act. Вам также понадобится установленный Docker. При первом запуске act вам будет предложено выбрать образ, который вы хотите создать. Для этого GitHub Action, чтобы проверить функциональность обновления типов баз данных, образа Micro будет достаточно.

После завершения настройки вы можете перейти в ~/.actrc, чтобы увидеть конфигурацию для вашего образа docker.

-P ubuntu-latest=node:16-buster-slim
-P ubuntu-20.04=node:16-buster-slim
-P ubuntu-18.04=node:16-buster-slim

Обратите внимание, что образ Micro не обладает всеми возможностями GitHub Action runner, поэтому вы увидите ошибки, связанные с командами git. Я не хочу взрывать память своего компьютера с помощью образа Large (~20 ГБ), но вы можете попробовать, если хотите.

Чтобы запустить этот рабочий процесс локально с помощью act, мы можем выполнить эту команду bash.

act -j update --secret-file .env

Мы можем передать следующие параметры:

Пояснение параметров

• • в этом рабочем процессе объявлено только 1 задание, поэтому мы можем передать задание обновления

• --secret-file ${filePath}

  • для проекта я уже использую .env для всех переменных окружения, поэтому я могу передать этот же файл для секретов.

  SUPABASE_URL=your_url
  SUPABASE_ANON_KEY=hehe
  

  • Если у вас по какой-то причине нет локальных файлов .env, вы также можете передать переменные вручную с параметром -s SUPBASE_URL=ваш_url -s SUPABASE_ANON_KEY=hehe.

После выполнения команды bash, вот упрощенная выдержка из вывода терминала

[Update database types/update]   ✅  Success - actions/setup-node@v2.1.5
[Update database types/update] ⭐  Run npm run update-types
echo "$(cat src/types/supabase.ts)"
[Update database types/update]   🐳  docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/2] user= workdir=
| 
| > billy@0.0.1 update-types /Users/lyqht/self-study/Billy
| > npx openapi-typescript "${SUPABASE_URL}/rest/v1/?apikey=${SUPABASE_ANON_KEY}" --version=2 --output src/types/supabase.ts
| 
| npx: installed 10 in 3.328s
| ✨ openapi-typescript 5.2.0
🚀 ***/rest/v1/?apikey=*** -> /Users/lyqht/self-study/Billy/src/types/supabase.ts [28ms]
| /**
|  * This file was auto-generated by openapi-typescript.
|  * Do not make direct changes to the file.
|  */
| 
| export interface paths {
|   "/": {
|     get: {
|       responses: {
|         /** OK */
|         200: unknown;
|       };
|     };
|   };
|   "/Bill": {
|     get: {
|     .... } // i won't show you all of it, but you will be able to see all these
[Update database types/update]   ✅  Success - npm run update-types
echo "$(cat src/types/supabase.ts)"
[Update database types/update] ⭐  Run check for file changes
[Update database types/update]   🐳  docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/git_status] user= workdir=
| /var/run/act/workflow/git_status: line 2: git: command not found
[Update database types/update]   ⚙  ::set-output:: status=
[Update database types/update]   ✅  Success - check for file changes

Если вы запустите это, вы увидите, что вывод содержит часть пути для ‘/Bill’ в результате выполнения скрипта update-types. Это означает, что все работает правильно 🎉

⚠️ Помните, что эти изменения происходят на самом экземпляре docker, вы не увидите никаких изменений в вашей локальной папке.

Бонус: в действии

7 Apr 2022 я добавил 2 новые таблицы, и мой бот был хорошим ботом.

С момента публикации оригинальной статьи я также создал на GitHub экшен, который делает то, что перечислено выше. Проверьте его здесь!

Вот и все, друзья! 🎉

Спасибо за прочтение, надеюсь, вам понравилась статья!

Если вам понравилась статья, нажмите на реакцию 🧡 и поделитесь ею 🐦~.

Чтобы быть в курсе всех моих новых материалов, следите за мной в Twitter.