@astrojs/ db

Astro DB est une base de données SQL entièrement gérée, conçue pour l’écosystème Astro : développez localement dans Astro et déployer vers n’importe quelle base de données compatible libSQL.

Avec Astro DB, vous disposez d’un outil puissant, local et sûr pour interroger et modéliser le contenu comme une base de données relationnelle.

Consultez le guide Astro DB pour une utilisation complète et des exemples.

Installation

Astro inclut une commande astro add pour automatiser l’installation des intégrations officielles. Si vous préférez, vous pouvez installer les intégrations manuellement à la place.

Exécutez l’une des commandes suivantes dans une nouvelle fenêtre de terminal.

npm

npx astro add db

pnpm

pnpm astro add db

Yarn

yarn astro add db

Installation manuelle

Si vous préférez configurer les choses vous-même à partir de zéro, ignorez astro add et suivez ces instructions pour installer Astro DB vous-même.

1. Installer l’intégration à partir de npm via un gestionnaire de paquets

npm

npm install @astrojs/db

pnpm

pnpm add @astrojs/db

Yarn

yarn add @astrojs/db

2. Ajouter l’intégration à astro.config.mjs

astro.config.mjs

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

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

3. Configurer votre base de données

Créez un fichier db/config.ts à la racine de votre projet. Il s’agit d’un fichier spécial qu’Astro chargera automatiquement et utilisera pour configurer les tables de votre base de données.

db/config.ts

import { defineDb } from 'astro:db';

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

Configuration

mode

Type : 'node' | 'web'
Par défaut : 'node'

Ajouté à la version : @astrojs/db@0.18.0

Configure le pilote à utiliser pour se connecter à votre base de données en production.

Par défaut, Astro DB utilise un pilote libSQL reposant sur Node.js pour les déploiements en production. Le mode node du pilote est suffisant pour la plupart des sites web hébergés ou auto-hébergés par Astro avec des environnements d’exécution Node.js. Cela vous permet de vous connecter à votre base de données via plusieurs protocoles, notamment memory:, file:, ws:, wss:, libsql, http et https, ainsi que d’accéder à des fonctionnalités plus avancées telles que les répliques intégrées.

Lors d’un déploiement dans un environnement serverless dans un environnement d’exécution autre que Node.js, comme Cloudflare Workers ou Deno, un pilote libSQL est disponible. Lors du déploiement à l’aide du mode web, vous pourrez établir des connexions web via libsql, http ou https.

Pour utiliser le mode web du pilote libSQL pour les environnements n’utilisant pas Node.js, définissez la propriété mode dans la configuration de votre adaptateur :

astro.config.mjs

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

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

Référence de configuration des tables

columns

Type : ColumnsConfig

Les colonnes de la table sont configurées à l’aide de l’objet 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 }),
  },
});

Les colonnes sont configurées en utilisant l’utilitaire column. column prend en charge les types suivants :

• column.text(...) - Stocke du contenu textuel simple ou enrichi
• column.number(...) - Stocke des valeurs entières et des valeurs à virgule flottante
• column.boolean(...) - Stocke des valeurs vraies / fausses
• column.date(...) - Stocke les objets Date, analysés comme des chaînes ISO pour le stockage des données.
• column.json(...) - Stocke des blobs JSON arbitraires, analysés en tant que JSON stringifié pour le stockage des données

Quelques valeurs de configuration sont communes à toutes les colonnes :

• primaryKey - Définit une colonne number ou text comme identifiant unique.
• optional - Astro DB utilise NOT NULL pour toutes les colonnes par défaut. Définissez optional sur true pour autoriser les valeurs nulles.
• default - Définit la valeur par défaut pour les entrées nouvellement insérées. Ceci accepte soit une valeur statique, soit une chaîne de sql pour les valeurs générées comme les timestamps.
• unique - Marque une colonne comme unique. Cela permet d’éviter les valeurs dupliquées dans les entrées de la table.
• references - Fait référence à une table liée par une colonne. Cela établit une contrainte de clé étrangère, ce qui signifie que chaque valeur de colonne doit avoir une valeur correspondante dans la table référencée.

Une colonne texte peut éventuellement définir une liste de chaînes de caractères litérales qui sera utilisée en tant qu’énumération pour la génération des types. Cependant, aucune validation ne sera effectuée au moment de l’exécution. La suppression, l’ajout et la modification de valeurs doivent être gérés dans le code de votre projet.

db/config.ts

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

// Définition de la table
const UserTable = defineTable({
  columns: {
    id: column.number({ primaryKey: true }),
    name: column.text(),
    rank: column.text({ enum: ['user', 'mod', 'admin'] }),
  },
});

// Définition de type résultant
type UserTableInferInsert = {
    id?: string;
    name: string;
    rank: "user" | "mod" | "admin";
}

indexes

Type : { on: string | string[]; unique?: boolean | undefined; name?: string | undefined; }[]

Les index de table sont utilisés pour améliorer la vitesse de recherche sur une colonne donnée ou une combinaison de colonnes. La propriété indexes accepte un tableau d’objets de configuration spécifiant les colonnes à indexer :

db/config.ts

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 },
  ]
});

Cela générera un index unique sur les colonnes authorId et published avec le nom Comment_authorId_published_idx.

Les options de configuration suivantes sont disponibles pour chaque index :

• on - Une seule colonne ou un tableau de noms de colonnes à indexer.
• unique - Définir sur true pour imposer des valeurs uniques à travers les colonnes indexées.
• name (Optionnel) - Un nom personnalisé pour l’index unique. Il remplacera le nom généré par Astro basé sur les noms de la table et de la colonne indexée (par exemple Comment_authorId_published_idx). Les noms personnalisés sont globaux, il faut donc s’assurer que les noms d’index n’entrent pas en conflit entre les tables.

foreignKeys

Type : { columns: string | string[]; references: () => Column | Column[]; }[]

Astuce

foreignKeys est une API avancée pour relier plusieurs colonnes d’une table. Si vous n’avez besoin de référencer qu’une seule colonne, essayez d’utiliser la propriété references de la colonne.

Les clés étrangères sont utilisées pour établir une relation entre deux tables. La propriété foreignKeys accepte un tableau d’objets de configuration qui peuvent relier une ou plusieurs colonnes entre les tables :

db/config.ts

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],
    },
  ],
});

Chaque objet de configuration de clé étrangère accepte les propriétés suivantes :

• columns - Un tableau de noms de colonnes à associer à la table référencée.
• references - Une fonction qui renvoie un tableau de colonnes de la table référencée.

Référence de la CLI d’Astro DB

Astro DB inclut un ensemble de commandes CLI pour interagir pour interagir avec votre base de données locale et compatible libSQL.

Ces commandes sont appelées automatiquement lors de l’utilisation d’une action CI GitHub, et peuvent être appelées manuellement en utilisant la CLI astro db.

astro db push

Options :

• --db-app-token <token> Fournir directement le jeton de l’application de base de données distante au lieu de ASTRO_DB_APP_TOKEN.
• --dry-run Imprimer les instructions SQL générées sans les appliquer.
• --force-reset Réinitialiser toutes les données de production si une modification du schéma avec rupture de compatibilité est nécessaire.
• --remote Transférer vers votre base de données distante plutôt que vers le fichier de base de données local. Nécessite que la variable d’environnement ASTRO_DB_REMOTE_URL soit définie, et soit que ASTRO_DB_APP_TOKEN soit défini dans l’environnement, soit qu’une valeur soit transmise avec l’argument de ligne de commande --db-app-token.

Transférez en toute sécurité les modifications apportées à la configuration de la base de données dans la base de données de votre projet. Cela vérifiera tout risque de perte de données et vous guidera sur les étapes de migration recommandées. Utilisez --remote pour appliquer les modifications à votre base de données distante. Si une modification de schéma avec rupture de compatibilité est nécessaire, utilisez --force-reset pour réinitialiser toutes les données de production.

astro db verify

Options :

• --db-app-token <token> Fournir directement le jeton de l’application de base de données distante au lieu de ASTRO_DB_APP_TOKEN.
• --json Imprimer un résultat JSON lisible par machine à partir de verify.
• --remote Comparer avec votre base de données distante plutôt qu’avec le fichier de base de données local. Nécessite que la variable d’environnement ASTRO_DB_REMOTE_URL soit définie, et soit que ASTRO_DB_APP_TOKEN soit défini dans l’environnement, soit qu’une valeur soit transmise avec l’argument de ligne de commande --db-app-token.

Compare votre schéma local à la base de données distante afin de vérifier les éventuelles différences entre les configurations de vos bases de données locale et distante. Cette opération est exécutée automatiquement par astro db push.

verify comparera votre fichier db/config.ts local avec la base de données distante et vous avertira si des modifications sont détectées. Elle renverra un code d’erreur si des modifications sont nécessaires ou non sécurisées, ce qui la rend utile pour l’intégration continue (CI).

astro db execute <file-path>

Options :

• --db-app-token <token> Fournir directement le jeton de l’application de base de données distante au lieu de ASTRO_DB_APP_TOKEN.
• --remote Exécuter cette commande sur votre base de données compatible libSQL. Omettre cette option pour exécuter la commande sur votre fichier de base de données local. Nécessite que la variable d’environnement ASTRO_DB_REMOTE_URL soit définie, et soit que ASTRO_DB_APP_TOKEN soit défini dans l’environnement, soit qu’une valeur soit transmise avec l’argument de ligne de commande --db-app-token.

Exécute un fichier .ts ou .js pour lire ou écrire dans votre base de données. Cette commande accepte un chemin de fichier comme argument, et prend en charge l’utilisation du module astro:db pour écrire des requêtes sûres. Utilisez l’option --remote pour exécuter sur votre base de données compatible libSQL, ou ignorez l’option pour lancer l’exécution sur votre fichier de base de données local. Consultez alimenter les données de développement pour un exemple de fichier.

astro db shell --query <sql-string>

Options :

• --query Requête SQL brute à exécuter.
• --remote Exécuter cette commande sur votre base de données compatible libSQL. Omettre cette option pour exécuter la commande sur votre fichier de base de données local. Nécessite que la variable d’environnement ASTRO_DB_REMOTE_URL soit définie, et soit que ASTRO_DB_APP_TOKEN soit défini dans l’environnement, soit qu’une valeur soit transmise avec l’argument de ligne de commande --db-app-token.

Exécute une requête SQL brute sur votre base de données.

L’exemple suivant sélectionne toutes les lignes d’une table Comment dans une base de données distante :

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

Référence de l’utilitaire Astro DB

isDbError()

Type : (err: unknown) => boolean

Ajouté à la version : @astrojs/db@0.9.1

La fonction isDbError() vérifie si une erreur est une exception de la base de données libSQL. Il peut s’agir d’une erreur de contrainte de clé étrangère lors de l’utilisation de références, ou de champs manquants lors de l’insertion de données. Vous pouvez combiner isDbError() avec un bloc try/catch pour gérer les erreurs de base de données dans votre application :

src/pages/api/comment/[id].ts

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(`Impossible d'insérer un commentaire avec l'id ${id}\n\n${e.message}`, { status: 400 });
    }
    return new Response("Une erreur inattendue s'est produite", { status: 500 });
  }

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

Plus d'intégrations

Framework d'interface utilisateur

• 

  @astrojs/alpinejs

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/svelte

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/vue

Adaptateurs SSR

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

Autres intégrations

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap