@astrojs/db

v0.19.0 GitHub npm Список изменений

Astro DB - это полностью управляемая SQL база данных, разработанная для экосистемы Astro: разрабатывайте локально в Astro и развертывайте в любую совместимую с libSQL базу данных.

С Astro DB у вас есть мощный локальный, типобезопасный инструмент для запросов и моделирования данных как реляционной базы.

Смотрите руководство по Astro DB для полного описания использования и примеров.

Установка

Astro включает команду astro add для автоматической настройки официальных интеграций. Если вы предпочитаете, вы можете установить интеграции вручную.

Запустите одну из следующих команд в новом окне терминала.

npx astro add db

pnpm astro add db

yarn astro add db

Ручная установка

Если вы предпочитаете настраивать все самостоятельно, пропустите astro add и следуйте инструкциям ниже.

1. Установите интеграцию из npm через менеджер пакетов

npm install @astrojs/db

pnpm add @astrojs/db

yarn add @astrojs/db

2. Добавьте интеграцию в `astro.config.mjs`

import { defineConfig } from 'astro/config';
import db from '@astrojs/db';

export default defineConfig({
  integrations: [
   db()
  ]
});

3. Настройте вашу базу данных

Создайте файл db/config.ts в корне проекта. Это специальный файл, который Astro автоматически загрузит и использует для настройки таблиц.

import { defineDb } from 'astro:db';

export default defineDb({
  tables: {},
})

Конфигурация

`mode`

Тип: 'node' | 'web'
По умолчанию: 'node'

Добавлено в: @astrojs/db@0.18.0

Настраивает драйвер, используемый для подключения к базе данных в продакшене.

По умолчанию Astro DB использует libSQL драйвер на основе Node.js для продакшен-развертываний. Режим node подходит для большинства сайтов (как на хостинге Astro, так и на собственном хостинге) с Node.js окружением. Он позволяет подключаться к базе данных по нескольким протоколам, включая memory:, file:, ws:, wss:, libsql, http и https, а также использовать более продвинутые возможности, такие как встроенные реплики.

При развертывании в бессерверной среде, где runtime не является Node.js (например Cloudflare Workers или Deno), доступен web-драйвер libSQL. В режиме web вы сможете подключаться по libsql, http или https.

Чтобы использовать web libSQL драйвер в окружениях без Node.js, установите mode в конфигурации вашего адаптера:

import { defineConfig } from 'astro/config';
import db from '@astrojs/db';

export default defineConfig({
  integrations: [
   db({
     mode: 'web'
   })
  ]
});

Справочник конфигурации таблиц

`columns`

Тип: ColumnsConfig

Колонки таблицы настраиваются с помощью объекта columns:

import { defineTable, column, NOW } from 'astro:db';

const Comment = defineTable({
  columns: {
    id: column.number({ primaryKey: true }),
    author: column.text(),
    content: column.text({ optional: true }),
    published: column.date({ default: NOW }),
  },
});

Колонки настраиваются утилитой column. column поддерживает следующие типы:

column.text(...) - хранение обычного или форматированного текста
column.number(...) - хранение целых чисел и значений с плавающей точкой
column.boolean(...) - хранение true / false
column.date(...) - хранение объектов Date (в хранилище сохраняются как ISO-строки)
column.json(...) - хранение произвольного JSON (в хранилище сохраняется как JSON-строка)

Есть несколько общих опций конфигурации для всех колонок:

primaryKey - сделать number или text колонку уникальным идентификатором.
optional - по умолчанию Astro DB использует NOT NULL для всех колонок. Установите optional: true, чтобы разрешить null.
default - значение по умолчанию для новых записей (статическое значение или строка sql для генерируемых значений, например timestamp).
unique - сделать колонку уникальной (предотвращает дубликаты значений в таблице).
references - ссылка на связанную таблицу (внешний ключ): значение колонки должно существовать в ссылаемой таблице.

Колонка text может опционально определять список строковых литералов в enum для генерации типов. Однако валидации во время выполнения не будет. Удаление, добавление и изменение значений следует обрабатывать в коде проекта.

import { defineTable, column } from 'astro:db';

// Определение таблицы
const UserTable = defineTable({
  columns: {
    id: column.number({ primaryKey: true }),
    name: column.text(),
    rank: column.text({ enum: ['user', 'mod', 'admin'] }),
  },
});

// Результирующее определение типа
type UserTableInferInsert = {
    id?: string;
    name: string;
    rank: "user" | "mod" | "admin";
}

`indexes`

Тип: { on: string | string[]; unique?: boolean | undefined; name?: string | undefined; }[]

Индексы улучшают скорость поиска по одной колонке или комбинации колонок. Свойство indexes принимает массив объектов конфигурации, задающих колонки для индексации:

import { defineTable, column } from 'astro:db';

const Comment = defineTable({
  columns: {
    authorId: column.number(),
    published: column.date(),
    body: column.text(),
  },
  indexes: [
    { on: ["authorId", "published"], unique: true },
  ]
});

Это создаст уникальный индекс по колонкам authorId и published с именем Comment_authorId_published_idx.

Доступны следующие опции для каждого индекса:

on - одна колонка или массив колонок для индекса.
unique (опционально) - установить true, чтобы обеспечить уникальность значений по индексируемым колонкам.
name (опционально) - пользовательское имя индекса. Оно переопределит автоматически сгенерированное имя Astro. Пользовательские имена глобальны, поэтому убедитесь, что имена индексов не конфликтуют между таблицами.

`foreignKeys`

Тип: { columns: string | string[]; references: () => Column | Column[]; }[]

Внешние ключи устанавливают связь между двумя таблицами. Свойство foreignKeys принимает массив объектов конфигурации, которые могут связывать одну или несколько колонок между таблицами:

import { defineTable, column } from 'astro:db';

const Author = defineTable({
  columns: {
    firstName: column.text(),
    lastName: column.text(),
  },
});

const Comment = defineTable({
  columns: {
    authorFirstName: column.text(),
    authorLastName: column.text(),
    body: column.text(),
  },
  foreignKeys: [
    {
      columns: ["authorFirstName", "authorLastName"],
      references: () => [Author.columns.firstName, Author.columns.lastName],
    },
  ],
});

Каждый объект конфигурации внешнего ключа принимает:

columns - одна колонка или массив колонок, которые нужно связать.
references - функция, которая возвращает колонку или массив колонок из ссылаемой таблицы.

Справочник Astro DB CLI

Astro DB включает набор команд CLI для взаимодействия с локальной и libSQL-совместимой базой данных.

Эти команды вызываются автоматически при использовании GitHub CI action и могут быть вызваны вручную через astro db.

`astro db push`

Флаги:

--db-app-token <token> передать токен приложения удаленной базы данных напрямую вместо ASTRO_DB_APP_TOKEN.
--dry-run вывести сгенерированные SQL-запросы без применения.
--force-reset сбросить все продакшен-данные, если требуется критическое изменение схемы.
--remote применить изменения к удаленной базе вместо локального файла. Требует ASTRO_DB_REMOTE_URL и либо ASTRO_DB_APP_TOKEN в окружении, либо значение, переданное через --db-app-token.

Безопасно отправляет изменения конфигурации базы данных в базу данных проекта. Команда проверит риск потери данных и подскажет рекомендуемые шаги миграции. Используйте --remote, чтобы применить изменения к удаленной базе. Если нужно сделать критическое изменение схемы, используйте --force-reset, чтобы сбросить все данные в продакшене.

`astro db verify`

Флаги:

--db-app-token <token> передать токен приложения удаленной базы данных напрямую вместо ASTRO_DB_APP_TOKEN.
--json вывести машиночитаемый JSON результат verify.
--remote сравнить с удаленной базой вместо локального файла. Требует ASTRO_DB_REMOTE_URL и либо ASTRO_DB_APP_TOKEN в окружении, либо значение, переданное через --db-app-token.

Сравнивает локальную схему с удаленной базой данных и предупреждает, если есть различия. Эта команда автоматически запускается внутри astro db push.

verify сравнит ваш локальный файл db/config.ts с удаленной базой и завершится с ненулевым кодом, если требуются изменения или они небезопасны, что полезно для CI.

`astro db execute <file-path>`

Флаги:

--db-app-token <token> передать токен приложения удаленной базы данных напрямую вместо ASTRO_DB_APP_TOKEN.
--remote запускать против удаленной libSQL-совместимой базы данных. Если не указывать, будет использован локальный файл базы. Требует ASTRO_DB_REMOTE_URL и либо ASTRO_DB_APP_TOKEN в окружении, либо значение, переданное через --db-app-token.

Выполняет файл .ts или .js, который читает или записывает данные в базу. Команда принимает путь к файлу и поддерживает использование модуля astro:db для типобезопасных запросов. Используйте --remote для удаленной базы или не указывайте флаг для локальной базы. Пример см. в руководстве по Astro DB.

`astro db shell --query <sql-string>`

Флаги:

--query выполнить сырой SQL-запрос.
--remote запускать против удаленной базы. Если не указывать, будет использован локальный файл базы. Требует ASTRO_DB_REMOTE_URL и либо ASTRO_DB_APP_TOKEN в окружении, либо значение, переданное через --db-app-token.

Выполняет сырой SQL-запрос к базе данных.

Пример ниже выбирает все строки из таблицы Comment в удаленной базе данных:

npx astro db shell --query "SELECT * FROM Comment;" --remote

Справочник утилит Astro DB

`isDbError()`

Тип: (err: unknown) => boolean

Добавлено в: @astrojs/db@0.9.1

Функция isDbError() проверяет, является ли ошибка исключением базы данных libSQL. Это может включать ошибку ограничения внешнего ключа при использовании references или отсутствие полей при вставке данных. Вы можете комбинировать isDbError() с try / catch, чтобы обработать ошибки базы данных:

import { db, Comment, isDbError } from 'astro:db';
import type { APIRoute } from 'astro';

export const POST: APIRoute = (ctx) => {
  try {
    await db.insert(Comment).values({
      id: ctx.params.id,
      content: 'Hello, world!'
    });
  } catch (e) {
    if (isDbError(e)) {
      return new Response(`Cannot insert comment with id ${id}\n\n${e.message}`, { status: 400 });
    }
    return new Response('An unexpected error occurred', { status: 500 });
  }

  return new Response(null, { status: 201 });
};

@astrojs/db

Установка

Ручная установка

1. Установите интеграцию из npm через менеджер пакетов

2. Добавьте интеграцию в `astro.config.mjs`

3. Настройте вашу базу данных

Конфигурация

`mode`

Справочник конфигурации таблиц

`columns`

`indexes`

`foreignKeys`

Справочник Astro DB CLI

`astro db push`

`astro db verify`

`astro db execute <file-path>`

`astro db shell --query <sql-string>`

Справочник утилит Astro DB

`isDbError()`

Дополнительные интеграции

UI-фреймворки

@astrojs/alpinejs

@astrojs/preact

@astrojs/react

@astrojs/solid⁠-⁠js

@astrojs/svelte

@astrojs/vue

Адаптеры

@astrojs/cloudflare

@astrojs/netlify

@astrojs/node

@astrojs/vercel

Другие интеграции

@astrojs/db

@astrojs/markdoc

@astrojs/mdx

@astrojs/partytown

@astrojs/sitemap

@astrojs/db

Установка

Ручная установка

1. Установите интеграцию из npm через менеджер пакетов

2. Добавьте интеграцию в astro.config.mjs

3. Настройте вашу базу данных

Конфигурация

mode

Справочник конфигурации таблиц

columns

indexes

foreignKeys

Справочник Astro DB CLI

astro db push

astro db verify

astro db execute <file-path>

astro db shell --query <sql-string>

Справочник утилит Astro DB

isDbError()

Дополнительные интеграции

UI-фреймворки

Адаптеры

Другие интеграции

2. Добавьте интеграцию в `astro.config.mjs`

`mode`

`columns`

`indexes`

`foreignKeys`

`astro db push`

`astro db verify`

`astro db execute <file-path>`

`astro db shell --query <sql-string>`

`isDbError()`