@astrojs/ db

v0.13.2 GitHub npm Changelog

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

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

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

Установка

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

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

npx astro add db

pnpm astro add db

yarn astro add db

Установка вручную

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

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: {},
})

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

`columns`

Столбцы таблицы настраиваются с использованием объекта 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 для сгенерированных значений, таких как метки времени.
unique - Пометьте столбец как уникальный. Это предотвращает дублирование значений в таблице.
references - Ссылка на связанную таблицу по столбцу. Это создает ограничение внешнего ключа, что означает, что каждое значение столбца должно иметь соответствующее значение в ссылочной таблице.

`indexes`

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

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

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

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

on: string | string[] - Один столбец или массив имен столбцов для индексации.
unique: boolean - Установите значение true для обеспечения уникальности значений в индексируемых столбцах.

`foreignKeys`

Внешние ключи используются для установления связи между двумя таблицами. Свойство 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: string[] - Массив имен столбцов для связи со ссылающейся таблицей.
references: () => Column[] - Функция, возвращающая массив столбцов из таблицы, на которую ссылается объект.

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

Astro DB включает в себя набор команд CLI для взаимодействия с базой данных вашего проекта на хостинге и учетной записью Astro Studio.

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

`astro db push`

Флаги:

--force-reset Сбросьте все производственные данные, если требуется изменение структуры данных.

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

`astro db verify`

Проверьте, нет ли различий между конфигурациями локальной и удаленной баз данных. Эта проверка выполняется автоматически при запуске astro db push. verify сравнит ваш локальный файл db/config.ts с удаленной базой данных и предупредит, если будут обнаружены изменения.

`astro db execute <file-path>`

Флаги:

--remote Выполнить в вашей проектной базе данных Studio. Не указывайте для запуска на вашем сервере разработки.

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

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

Флаги:

--query Сырой SQL-запрос для выполнения.
--remote Выполнить в вашей проектной базе данных Studio. Опустите, чтобы выполнить на вашем сервере разработки.

Выполните необработанный SQL-запрос к вашей базе данных. Используйте флаг --remote для выполнения в базе данных проекта Studio или опустите этот флаг для выполнения на сервере разработки.

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

`isDbError()`

Функция isDbError() проверяет, является ли ошибка исключением базы данных libSQL. Это может быть ошибка ограничения внешнего ключа при использовании ссылок или отсутствие полей при вставке данных. Вы можете комбинировать 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(`Невозможно вставить комментарий с id ${id}\n\n${e.message}`, { status: 400 });
    }
    return new Response('Произошла непредвиденная ошибка', { status: 500 });
  }

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

@astrojs/ db

Установка

Установка вручную

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

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

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

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

columns

indexes

foreignKeys

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

astro db push

astro db verify

astro db execute <file-path>

astro db shell --query <sql-string>

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

isDbError()

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

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

SSR адаптеры

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

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

`columns`

`indexes`

`foreignKeys`

`astro db push`

`astro db verify`

`astro db execute <file-path>`

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

`isDbError()`