@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éployez depuis votre tableau de bord Astro Studio.
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. Visualisez, gérez et déployez vos données distantes hébergées via le tableau de bord interactif de Studio.
Installation
Titre de la section InstallationAstro 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.
Installation manuelle
Titre de la section Installation manuelleSi vous préférez configurer les choses vous-même à partir de zéro, sautez 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
Titre de la section 1. Installer l’intégration à partir de npm via un gestionnaire de paquets2. Ajouter l’intégration à astro.config.mjs
Titre de la section 2. Ajouter l’intégration à astro.config.mjs3. Configurez votre base de données
Titre de la section 3. Configurez votre base de donnéesCré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.
Référence de la configuration du tableau
Titre de la section Référence de la configuration du tableaucolumns
Titre de la section columnsLes colonnes de la table sont configurées à l’aide de l’objet columns
:
Les colonnes sont configurées en utilisant l’utilitaire column
. column
supporte les types suivants :
column.text(...)
- Stocke du contenu textuel simple ou enrichicolumn.number(...)
- Stocke des valeurs entières et des valeurs à virgule flottantecolumn.boolean(...)
- Stocke des valeurs vraies / faussescolumn.date(...)
- Stocke les objetsDate
, 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 colonnenumber
outext
comme identifiant unique.optional
- Astro DB utiliseNOT NULL
pour toutes les colonnes par défaut. Mettezoptional
à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 desql
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.
indexes
Titre de la section indexesLes 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 :
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
:string | string[]
- Une seule colonne ou un tableau de noms de colonnes à indexer.unique
:boolean
- Fixé àtrue
pour imposer des valeurs uniques à travers les colonnes indexées.name
:string
(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 exempleComment_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
Titre de la section foreignKeysforeignKeys
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 :
Chaque objet de configuration de clé étrangère accepte les propriétés suivantes :
columns
:string[]
- Un tableau de noms de colonnes à associer à la table référencée.references
:() => Column[]
- Une fonction qui renvoie un tableau de colonnes de la table référencée.
Référence CLI Astro DB
Titre de la section Référence CLI Astro DBAstro DB inclut un ensemble de commandes CLI pour interagir avec la base de données de votre projet hébergé et votre compte Astro Studio.
Ces commandes sont appelées automatiquement lors de l’utilisation d’une action CI GitHub, et peuvent être appelées manuellement en utilisant le CLI astro db
.
astro db push
Titre de la section astro db pushFlags :
--force-reset
Réinitialiser toutes les données de production si une modification du schéma de rupture est nécessaire.
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. Si un changement radical de schéma doit être effectué, utilisez le drapeau --force-reset
pour réinitialiser toutes les données de production.
astro db verify
Titre de la section astro db verifyVérifier s’il y a des différences entre la configuration de la base de données locale et celle de la base de données distante. Ceci est automatiquement lancé par astro db push
. verify
comparera votre fichier local db/config.ts
avec la base de données distante et vous avertira si des changements sont détectés.
astro db execute <file-path>
Titre de la section astro db execute <file-path>Flags :
--remote
Exécuter sur la base de données de votre projet Studio. Ignorer pour l’exécuter sur votre serveur de développement.
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 supporte l’utilisation du module astro:db
pour écrire des requêtes sûres. Utilisez l’option --remote
pour lancer l’exécution sur la base de données de votre projet Studio, ou ignorez l’option pour lancer l’exécution sur votre serveur de développement. Voir comment utiliser les données sur le développement des seeds pour un exemple de fichier.
astro db shell --query <sql-string>
Titre de la section astro db shell --query <sql-string>Flags :
--query
Requête SQL brute à exécuter.--remote
Exécuter sur la base de données de votre projet Studio. Ignorer pour l’exécuter sur votre serveur de développement.
Exécute une requête SQL brute sur votre base de données. Utilisez l’option --remote
pour lancer la requête sur la base de données de votre projet Studio, ou ignorez l’option pour lancer la requête sur votre serveur de développement.
Référence de l’utilitaire Astro DB
Titre de la section Référence de l’utilitaire Astro DBisDbError()
Titre de la section isDbError()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 :