diff --git a/config/sidebar.ts b/config/sidebar.ts index e10117a5b0252..de73ddc588214 100644 --- a/config/sidebar.ts +++ b/config/sidebar.ts @@ -22,22 +22,30 @@ type StarlightSidebarConfig = NonNullable[0]['sideb /** Generate a Starlight sidebar config object from our existing `nav.ts` files. */ export function makeSidebar(): StarlightSidebarConfig { + let currentSubGroup: Extract; return navTranslations.en.reduce((sidebar, item) => { if ('header' in item) { - sidebar.push({ + const newGroup = { label: item.text, translations: getTranslations(item), items: [], - }); - } else { - const group = sidebar.at(-1); - if (group && 'items' in group) { - group.items.push({ - label: item.text, - link: item.slug, - translations: getTranslations(item), - }); + collapsed: item.collapsed, + }; + if (item.nested) { + const parentGroup = sidebar.at(-1); + if (parentGroup && 'items' in parentGroup) { + parentGroup.items.push(newGroup); + } + } else { + sidebar.push(newGroup); } + currentSubGroup = newGroup; + } else { + currentSubGroup.items.push({ + label: item.text, + link: item.slug, + translations: getTranslations(item), + }); } return sidebar; }, [] as StarlightSidebarConfig); diff --git a/src/content/docs/en/getting-started.mdx b/src/content/docs/en/getting-started.mdx index 4ffe969896024..4143cee9a5b2c 100644 --- a/src/content/docs/en/getting-started.mdx +++ b/src/content/docs/en/getting-started.mdx @@ -12,7 +12,7 @@ hero: title: Astro Docs tagline: Guides, resources, and API references to help you build with Astro. actions: - - text: Get started + - text: Install Astro icon: rocket link: /en/install/auto/ variant: primary diff --git a/src/content/docs/en/guides/data-fetching.mdx b/src/content/docs/en/guides/data-fetching.mdx index ce944ae139b60..53be0e042f878 100644 --- a/src/content/docs/en/guides/data-fetching.mdx +++ b/src/content/docs/en/guides/data-fetching.mdx @@ -8,7 +8,8 @@ i18nReady: true ## `fetch()` in Astro -All [Astro components](/en/basics/astro-components/) have access to the [global `fetch()` function](https://developer.mozilla.org/en-US/docs/Web/API/fetch) in their component script to make HTTP requests to APIs using the full URL (e.g. https://example.com/api or `Astro.url + "/api"`). +All [Astro components](/en/basics/astro-components/) have access to the [global `fetch()` function](https://developer.mozilla.org/en-US/docs/Web/API/fetch) in their component script to make HTTP requests to APIs using the full URL (e.g. https://example.com/api). +Additionally, you can construct a URL to your project's pages and endpoints that are rendered on demand on the server using `new URL("/api", Astro.url)`. This fetch call will be executed at build time, and the data will be available to the component template for generating dynamic HTML. If [SSR](/en/guides/server-side-rendering/) mode is enabled, any fetch calls will be executed at runtime. diff --git a/src/content/docs/en/reference/dev-toolbar-app-reference.mdx b/src/content/docs/en/reference/dev-toolbar-app-reference.mdx index 2457cd9e3139f..a58bb53d356b5 100644 --- a/src/content/docs/en/reference/dev-toolbar-app-reference.mdx +++ b/src/content/docs/en/reference/dev-toolbar-app-reference.mdx @@ -229,7 +229,7 @@ app.onToolbarPlacementUpdated((options) => { Changes the state of the app. This can be used to enable or disable the app programmatically, for example, when the user clicks on a button in the app's UI. ```ts title="src/my-app.js" -app.changeAppState({state: false}); +app.toggleState({ state: false }); ``` ### `toggleNotification()` diff --git a/src/content/docs/fr/guides/astro-db.mdx b/src/content/docs/fr/guides/astro-db.mdx new file mode 100644 index 0000000000000..c82360a9bda17 --- /dev/null +++ b/src/content/docs/fr/guides/astro-db.mdx @@ -0,0 +1,624 @@ +--- +title: 'Astro DB' +description: Apprenez à utiliser Astro DB, une base de données SQL entièrement gérée, conçue exclusivement pour Astro. +githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/db/' +i18nReady: true +--- +import { FileTree } from '@astrojs/starlight/components'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; +import ReadMore from '~/components/ReadMore.astro'; +import StudioHeading from '~/components/StudioHeading.astro'; +import { Steps } from '@astrojs/starlight/components'; + +Astro DB est une base de données SQL entièrement gérée, conçue exclusivement pour Astro. Développez localement ou connectez-vous à une base de données hébergée et gérée sur notre plateforme [Astro Studio](/fr/recipes/studio/). + +## Installation + +Ajoutez Astro DB à un projet Astro nouveau ou existant (nécessite `astro@4.5` ou plus) avec l'intégration [`@astrojs/db`](/fr/guides/integrations-guide/db/) (`v0.8.0` ou plus). Astro inclut une commande intégrée `astro add` pour automatiser ce processus d'installation. + + + + ```sh + npx astro add db + ``` + + + ```sh + pnpm astro add db + ``` + + + ```sh + yarn astro add db + ``` + + + +Si vous préférez, vous pouvez [installer `@astrojs/db` manuellement](/fr/guides/integrations-guide/db/#installation-manuelle) à la place. + +## Définir votre base de données + +Astro DB est une solution complète pour configurer, développer et consulter vos données. Une base de données locale est créée chaque fois que vous lancez `astro dev`, utilisant LibSQL pour gérer vos données sans avoir besoin de Docker ou d'une connexion réseau. + +L'installation de `@astrojs/db` avec la commande `astro add` créera un fichier `db/config.ts` dans votre projet où vous définirez les tables de votre base de données : + +```ts title="db/config.ts" +import { defineDb } from 'astro:db'; + +export default defineDb({ + tables: { }, +}) +``` + +### Tables + +Dans Astro DB, les données sont stockées dans des tables SQL. Les tables structurent vos données en lignes et en colonnes, où les colonnes imposent le type de chaque valeur de ligne. + +Lorsque vous définissez une table, Astro génère une interface TypeScript pour interroger cette table à partir de votre projet. Le résultat est un support TypeScript complet lorsque vous accédez à vos données avec l'autocomplétion des propriétés et la vérification des types. + +Pour configurer une table de base de données individuelle, importez et utilisez les utilitaires `defineTable()` et `column` de `astro:db`. + +Cet exemple configure une table `Comment` avec des colonnes de texte obligatoires pour `author` et `body` et la rend disponible pour votre projet à travers l'export `defineDb()`. + +```ts title="db/config.ts" "Comment" +import { defineDb, defineTable, column } from 'astro:db'; + +const Comment = defineTable({ + columns: { + author: column.text(), + body: column.text(), + } +}) + +export default defineDb({ + tables: { Comment }, +}) +``` + +Voir la [référence de configuration des tables](/fr/guides/integrations-guide/db/#référence-de-la-configuration-du-tableau) pour une référence complète des options de table. + +### Colonnes + +Astro DB prend en charge les types de colonnes suivants : + +```ts title="db/config.ts" "column.text()" "column.number()" "column.boolean()" "column.date()" "column.json()" +import { defineTable, column } from 'astro:db'; + +const Comment = defineTable({ + columns: { + // Une chaîne de texte. + author: column.text(), + // Une valeur entière. + likes: column.number(), + // Une valeur vraie ou fausse. + flagged: column.boolean(), + // Valeurs de date et d'heure interrogées sous forme d'Objets JavaScript de type date. + published: column.date(), + // Un objet JSON non typé. + metadata: column.json(), + } +}); +``` + +Voir la [référence des colonnes de la table](/fr/guides/integrations-guide/db/#référence-de-la-configuration-du-tableau) pour plus de détails. + +### Table des références + +Les relations entre les tables sont un modèle courant dans la conception des bases de données. Par exemple, une table `Blog` peut être en relation étroite avec d'autres tables `Comment`, `Author`, et `Category`. + +Vous pouvez définir ces tables de relations et les enregistrer dans le schéma de votre base de données à l'aide de **colonnes de référence**. Pour établir une relation, vous aurez besoin de : + +- Une **colonne identifiant** de la table référencée. Il s'agit généralement d'une colonne `id` avec la propriété `primaryKey`. +- Une colonne sur la table de base pour **stocker l'`id` référencé**. Ceci utilise la propriété `references` pour établir une relation. + +Cet exemple montre que la colonne `authorId` d'une table `Comment` fait référence à la colonne `id` d'une table `Author`. + +```ts title="db/config.ts" {3, 10} +const Author = defineTable({ + columns: { + id: column.number({ primaryKey: true }), + name: column.text(), + } +}); + +const Comment = defineTable({ + columns: { + authorId: column.number({ references: () => Author.columns.id }), + content: column.text(), + } +}); +``` + +## Alimentez votre base de données + +En développement, Astro utilisera la configuration de votre base de données pour générer des types locaux en fonction de vos schémas. Ceux-ci seront générés à chaque fois que le serveur de développement sera démarré, et vous permettront d'interroger et de travailler sur la forme de vos données avec la sécurité des types et l'autocomplétion. + +Pour ajouter des données de développement pour les tests et le débogage dans votre projet Astro, créez un fichier `db/seed.ts`. Importez l'objet `db` et toute table configurée depuis `astro:db`. Utilisez la fonction `db.insert()` pour fournir un tableau d'objets de données de ligne de table. + +L'exemple suivant définit deux lignes de données de développement pour une table `Comment` : + +```ts title="db/seed.ts" +import { db, Comment } from 'astro:db'; + +export default async function() { + await db.insert(Comment).values([ + { authorId: 1, body: "J'espère que vous aimerez Astro DB !" }, + { authorId: 2, body: 'Profitez !'}, + ]) +} +``` + +Votre serveur de développement redémarrera automatiquement votre base de données chaque fois que ce fichier changera, régénérant vos types et alimentant vos données de développement à partir de `seed.ts`. + +## Interrogez votre base de données + +Vous pouvez interroger votre base de données depuis n'importe quelle [page Astro](/fr/basics/astro-pages/#pages-astro) ou [endpoint](/fr/guides/endpoints/) de votre projet en utilisant l'ORM `db` et le constructeur de requêtes fourni. + +### Drizzle ORM + +``` +import { db } from 'astro:db'; +``` + +Astro DB comprend un client intégré [Drizzle ORM](https://orm.drizzle.team/). Il n'y a pas d'installation ou de configuration manuelle requise pour utiliser le client. Le client Astro DB `db` est automatiquement configuré pour communiquer avec votre base de données (locale ou distante) lorsque vous lancez Astro. Il utilise la définition exacte du schéma de votre base de données pour des requêtes SQL sûres, avec des erreurs TypeScript lorsque vous référencez une colonne ou une table qui n'existe pas. + + +### Select + +L'exemple suivant sélectionne toutes les lignes d'une table `Comment`. Cela renvoie le tableau complet des données de développement provenant de `db/seed.ts`, qui est alors disponible pour être utilisé dans votre modèle de page : + +```astro title="src/pages/index.astro" +--- +import { db, Comment } from 'astro:db'; + +const comments = await db.select().from(Comment); +--- + +

Commentaires

+ +{ + comments.map(({ author, body }) => ( +
+

Auteur: {author}

+

{body}

+
+ )) +} +``` + +Voir la [référence API Drizzle `select()`](https://orm.drizzle.team/docs/select) pour une vue d'ensemble complète. + +### Insert + +Pour accepter les entrées de l'utilisateur, comme le traitement des demandes de formulaire et l'insertion de données dans votre base de données hébergée à distance, configurez votre projet Astro pour [un rendu à la demande](/fr/basics/rendering-modes/#rendu-à-la-demande) et [ajoutez un adaptateur SSR](/fr/guides/server-side-rendering/#adaptateurs-officiels) pour votre environnement de déploiement. + +Cet exemple insère une ligne dans une table `Comment` sur la base d'une requête POST de formulaire analysée : + +```astro +--- +// src/pages/index.astro +import { db, Comment } from 'astro:db'; + +if (Astro.request.method === 'POST') { + // parse form data + const formData = await Astro.request.formData(); + const author = formData.get('author'); + const content = formData.get('content'); + if (typeof author === 'string' && typeof content === 'string') { + // insérer les données du formulaire dans la table Comment + await db.insert(Comment).values({ author, content }); + } +} + +// affiche la nouvelle liste des commentaires sur chaque demande +const comments = await db.select().from(Comment); +--- + +
+ + + + + + + +
+ + +``` + +Vous pouvez également interroger votre base de données à partir d'un point de terminaison de l'API. Cet exemple supprime une ligne d'une table `Comment` par le paramètre `id` : + +```ts +// src/pages/api/comments/[id].ts +import type { APIRoute } from "astro"; +import { db, Comment } from 'astro:db'; + +export const DELETE: APIRoute = async (ctx) => { + await db.delete(Comment).where({ id: ctx.params.id }); + return new Response(null, { status: 204 }); +} +``` + + + + Voir la [référence API Drizzle `insert()`] (https://orm.drizzle.team/docs/insert) pour une vue d'ensemble complète. + + + +### Filtrage + +Pour rechercher les résultats d'une table en fonction d'une propriété spécifique, utilisez [les options Drizzle pour les sélections partielles](https://orm.drizzle.team/docs/select#partial-select). Par exemple, ajoutez [un appel à `.where()`](https://orm.drizzle.team/docs/select#filtering) à votre requête `select()` et passez la comparaison que vous voulez faire. + +L'exemple suivant recherche toutes les lignes d'une table `Comment` qui contiennent l'expression "Astro DB". Utilisez [l'opérateur `like()`](https://orm.drizzle.team/docs/operators#like) pour vérifier si une phrase est présente dans le `body` : + + +```astro title="src/pages/index.astro" +--- +import { db, Comment, like } from 'astro:db'; + +const comments = await db.select().from(Comment).where( + like(Comment.body, '%Astro DB%') +); +--- +``` + +### Utilitaires de Drizzle + +Tous les utilitaires Drizzle permettant de construire des requêtes sont exposés à partir du module `astro:db`. Cela inclut : + +- [Opérateurs de filtre](https://orm.drizzle.team/docs/operators) comme `eq()` et `gt()` +- [Les aides à l'agrégation](https://orm.drizzle.team/docs/select#aggregations-helpers) comme `count()` +- [L'aide `sql`](https://orm.drizzle.team/docs/sql) pour écrire des requêtes SQL brutes + +```ts +import { eq, gt, count, sql } from 'astro:db'; +``` + +### Les relations + +Vous pouvez interroger des données liées provenant de plusieurs tables à l'aide d'une liaison SQL. Pour créer une requête de liaison, ajoutez un opérateur de liaison à votre déclaration `db.select()`. Chaque fonction accepte une table à l'origine de la liaison et une condition pour faire correspondre les lignes entre les deux tables. + +Cet exemple utilise une fonction `innerJoin()` pour faire la liaison entre les auteurs de `Commentaires` et leurs informations `Author` sur la base de la colonne `authorId`. Cette fonction retourne un tableau d'objets avec chaque ligne `Author` et `Comment` comme propriétés de premier niveau : + +```astro title="src/pages/index.astro" +--- +import { db, eq, Comment, Author } from 'astro:db'; + +const comments = await db.select() + .from(Comment) + .innerJoin(Author, eq(Comment.authorId, Author.id)); +--- + +

Commentaires

+ +{ + comments.map(({ Author, Comment }) => ( +
+

Auteur: {Author.name}

+

{Comment.body}

+
+ )) +} +``` + + + + Voir la [référence de liaison Drizzle](https://orm.drizzle.team/docs/joins#join-types) pour tous les opérateurs de liaison disponibles et les options de configuration. + + + +### Transactions par paquets + +Toutes les requêtes de bases de données distantes sont effectuées sous la forme d'une requête réseau. Vous pouvez avoir besoin de regrouper les requêtes en une seule transaction lorsque vous effectuez un grand nombre de requêtes, ou de procéder à des retours en arrière automatiques en cas d'échec d'une requête. + +Cet exemple permet de lancer plusieurs lignes en une seule requête à l'aide de la méthode `db.batch()` : + +```ts +// db/seed.ts +import { db, Author, Comment } from 'astro:db'; + +export default async function () { + let queries; + // Envoyez 100 exemples de commentaires dans votre base de données distante + // avec une seule demande de réseau. + for (let i = 0; i < 100; i++) { + queries.push(db.insert(Comment).values({ body: `Test comment ${i}` })); + } + await db.batch(queries); +} +``` + + + + Voir la documentation [Drizzle `db.batch()`](https://orm.drizzle.team/docs/batch-api) pour plus de détails. + + + + + ## Astro Studio + + +Astro DB peut [se connecter à la plateforme Astro Studio](/fr/recipes/studio/) pour ajouter rapidement une base de données hébergée à votre projet. Vous pouvez visualiser, gérer et déployer de nouvelles bases de données hébergées à partir du portail web Astro Studio. + +Pour créer un nouveau projet, vous pouvez utiliser un [modèle prêt à l'emploi](https://studio.astro.build) ou consulter le [guide Astro Studio](/fr/recipes/studio/#créer-un-nouveau-projet-studio). + + + ### Pousser les schémas de table + + + +Le schéma de vos tables évoluera au fur et à mesure que votre projet se développera. Vous pouvez tester en toute sécurité les changements de configuration localement et les transférer dans la base de données de Studio lors du déploiement. + +Lorsque vous [créez un projet Studio à partir du tableau de bord](#astro-studio), vous avez la possibilité de créer une action GitHub CI. Cette action migrera automatiquement les changements de schéma lors de la fusion avec la branche principale de votre dépôt. + +Vous pouvez aussi pousser les changements de schéma via le CLI en utilisant la commande `astro db push --remote` : + + + + ```sh + npm run astro db push --remote + ``` + + + ```sh + pnpm astro db push --remote + ``` + + + ```sh + yarn astro db push --remote + ``` + + + +Cette commande vérifiera que les changements peuvent être effectués sans perte de données et guidera sur les changements de schéma recommandés pour résoudre les conflits. Si une modification du schéma _doit_ être faite, ajoutez le drapeau `--force-reset` pour réinitialiser toutes les données de production. + +### Pousser les changements majeurs de schéma + +:::caution +__Cela détruira votre base de données__. N'exécutez cette commande que si vous n'avez pas besoin de vos données de production. +::: + +Si vous devez modifier le schéma de votre table d'une manière incompatible avec vos données existantes hébergées chez Astro Studio, vous devrez réinitialiser votre base de données de production. + +Pour pousser une mise à jour du schéma de table qui inclut un changement radical, ajoutez le drapeau `--force-reset` pour réinitialiser toutes les données de production : + + + + ``sh + npm run astro db push --remote --force-reset + ``` + + + ```sh + pnpm astro db push --remote --force-reset + ``` + + + ```sh + yarn astro db push --remote --force-reset + ``` + + + + + ### Renommer des tables + + +Il est possible de renommer une table après avoir transféré votre schéma dans Astro Studio. + +Si vous **n'avez pas de données de production importantes**, alors vous pouvez [réinitialiser votre base de données](#pousser-les-schémas-de-table) en utilisant l'option `--force-reset`. Ce drapeau supprimera toutes les tables de la base de données et en créera de nouvelles afin qu'elle corresponde exactement à votre schéma actuel. + +Pour renommer une table tout en préservant vos données de production, vous devez effectuer une série de modifications irréversibles afin de transférer votre schéma local vers Astro studio en toute sécurité. + +L'exemple suivant renomme une table de `Comment` en `Feedback` : + + + +1. Dans le fichier de configuration de votre base de données, ajoutez la propriété `deprecated : true` à la table que vous voulez renommer : + + ```ts title="db/config.ts" ins={2} + const Comment = defineTable({ + deprecated: true, + columns: { + author: column.text(), + body: column.text(), + } + }); + ``` + +2. Ajoutez un nouveau schéma de table (correspondant exactement aux propriétés de la table existante) avec le nouveau nom : + + ```ts title="db/config.ts" ins={9-14} + const Comment = defineTable({ + deprecated: true, + columns: { + author: column.text(), + body: column.text(), + } + }); + + const Feedback = defineTable({ + columns: { + author: column.text(), + body: column.text(), + } + }); + ``` +3. [Poussez vers Astro Studio](#pousser-les-schémas-de-table) avec `astro db push --remote`. Cela ajoutera la nouvelle table et marquera l'ancienne comme obsolète. +4. Mettez à jour le code de votre projet local pour utiliser la nouvelle table au lieu de l'ancienne. Il se peut que vous deviez également migrer des données vers la nouvelle table. +5. Une fois que vous êtes sûr que l'ancienne table n'est plus utilisée dans votre projet, vous pouvez supprimer le schéma de votre `config.ts` : + ```ts title="db/config.ts" del={1-7} + const Comment = defineTable({ + deprecated: true, + columns: { + author: column.text(), + body: column.text(), + } + }); + + const Feedback = defineTable({ + columns: { + author: column.text(), + body: column.text(), + } + }); + ``` +6. Poussez à nouveau vers Astro Studio avec `astro db push --remote`. L'ancienne table sera supprimée, ne laissant que la nouvelle table renommée. + + + + ### Pousser des données + + +Vous pouvez avoir besoin de pousser des données vers votre base de données Studio pour les _seed_ (données initiales) ou les migrations de données. Vous pouvez créer un fichier `.ts` avec le module `astro:db` pour écrire des requêtes sûres. Ensuite, exécutez le fichier contre votre base de données Studio en utilisant la commande `astro db execute --remote` : + +Les commentaires suivants peuvent être initiés à l'aide de la commande `astro db execute db/seed.ts --remote` : + +```ts +// db/seed.ts +import { Comment } from 'astro:db'; + +export default async function () { + await db.insert(Comment).values([ + { authorId: 1, body: "J'espère que vous aimerez Astro DB !" }, + { authorId: 2, body: 'Profitez !' }, + ]) +} +``` + + + + Voir la [référence CLI](/fr/guides/integrations-guide/db/#référence-cli-astro-db) pour une liste complète des commandes. + + + + + ### Se connecter à Astro Studio + + +Par défaut, Astro utilisera un fichier de base de données local chaque fois que vous lancerez les commandes `dev` ou `build`. Les tables sont recréées à partir de zéro lors de l'exécution de chaque commande, et les données d'amorçage du développement seront insérées. + +Pour vous connecter à votre base de données Studio hébergée, vous pouvez ajouter l'option `--remote`. Utilisez ce drapeau pour les déploiements en production afin d'avoir un accès en lecture et en écriture à votre base de données Studio. Cela vous permettra [d'accepter et de persister les données des utilisateurs](#insérer). + +```bash +# Construire avec une connexion à distance +astro build --remote + +# Développer avec une connexion à distance +astro dev --remote +``` + +:::caution + +Soyez prudent en utilisant `--remote` dans le développement. Cela se connectera à une base de données de production, et toutes les insertions, mises à jour ou suppressions seront persistantes. + +::: + +Pour utiliser une connexion à distance, vous aurez besoin d'un jeton d'application pour vous authentifier auprès de Studio. Consultez le tableau de bord de Studio pour obtenir des instructions sur la création et la configuration d'un jeton. + + + + Lorsque vous êtes prêt à déployer, consultez notre guide [Déployer avec une connexion Studio](/fr/recipes/studio/#déployer-avec-une-connexion-studio). + + + +## Construire des intégrations Astro DB + +Les [intégrations Astro](/fr/reference/integrations-reference/) permettent d'étendre les projets des utilisateurs avec des tables Astro DB supplémentaires et des données de départ. + +Utilisez la méthode `extendDb()` dans le hook `astro:db:setup` pour enregistrer des fichiers de configuration et de la données initiales (_seed_) Astro DB supplémentaires. +L'aide `defineDbIntegration()` fournit le support TypeScript et l'auto-complétion pour le crochet `astro:db:setup`. + +```js {8-13} +// my-integration/index.ts +import { defineDbIntegration } from '@astrojs/db/utils'; + +export default function MyIntegration() { + return defineDbIntegration({ + name: 'my-astro-db-powered-integration', + hooks: { + 'astro:db:setup': ({ extendDb }) => { + extendDb({ + configEntrypoint: '@astronaut/my-package/config', + seedEntrypoint: '@astronaut/my-package/seed', + }); + }, + // Autres fonctions d'intégration... + }, + }); +} +``` + +Les fichiers d'intégration [config](#définir-votre-base-de-données) et [seed](#alimentez-votre-base-de-données) suivent le même format que leurs équivalents définis par l'utilisateur. + +### Opérations de sécurité dans les intégrations + +Lorsque vous travaillez sur des intégrations, il se peut que vous ne puissiez pas bénéficier des types de table générés par Astro et exportés depuis `astro:db`. +Pour une sécurité totale des types, utilisez l'utilitaire `asDrizzleTable()` pour créer un objet de référence de table que vous pouvez utiliser pour les opérations de base de données. + +Par exemple, dans le cas d'une intégration mettant en place la table de base de données `Pets` suivante : + +```js +// my-integration/config.ts +import { defineDb, defineTable, column } from 'astro:db'; + +export const Pets = defineTable({ + columns: { + name: column.text(), + species: column.text(), + }, +}); + +export default defineDb({ tables: { Pets } }); +``` + +Le fichier _seed_ (données initiales) peut importer `Pets` et utiliser `asDrizzleTable()` pour insérer des lignes dans votre table avec vérification du type : + +```js {2,7} /typeSafePets(?! )/ +// my-integration/seed.ts +import { asDrizzleTable } from '@astrojs/db/utils'; +import { db } from 'astro:db'; +import { Pets } from './config'; + +export default async function() { + const typeSafePets = asDrizzleTable('Pets', Pets); + + await db.insert(typeSafePets).values([ + { name: 'Palomita', species: 'cat' }, + { name: 'Pan', species: 'dog' }, + ]); +} +``` + +La valeur retournée par `asDrizzleTable('Pets', Pets)` est équivalente à `import { Pets } from 'astro:db'`, mais elle est disponible même si la génération de type d'Astro ne peut pas fonctionner. +Vous pouvez l'utiliser dans tout code d'intégration qui doit interroger ou insérer dans la base de données. + +## Déploiement de la production en auto-hébergement + +Si vous déployez votre site sur un hôte autogéré tel qu'un [serveur privé virtuel](https://fr.wikipedia.org/wiki/Serveur_d%C3%A9di%C3%A9_virtuel), vous pouvez choisir d'utiliser un fichier de base de données au lieu de vous connecter à une base de données hébergée chez Astro Studio. + +:::caution +L'utilisation d'un fichier de base de données est une fonctionnalité avancée, et il convient d'être prudent lors du déploiement afin d'éviter d'écraser votre base de données et de perdre vos données de production. + +En outre, cette méthode ne fonctionnera pas dans les déploiements sans serveur, car le système de fichiers n'est pas persistant dans ces environnements. + +Pour une solution entièrement gérée, [se connecter aux bases de données hébergées sur la plateforme Astro Studio](/fr/recipes/studio/) à la place. +::: + +Si vous êtes prêt à prendre des risques et que vous pouvez gérer le déploiement vous-même, vous pouvez utiliser un fichier de base de données au lieu de vous connecter à Studio. + +Définissez la variable d'environnement `ASTRO_DATABASE_FILE` avec un chemin pointant vers votre fichier `.db` dans l'environnement de l'hôte pendant votre compilation : + +```shell +ASTRO_DATABASE_FILE=/srv/files/database.db astro build +``` + +La compilation se fera de manière statique avec ce chemin comme base de données de production. Lorsque vous déployez et lancez votre serveur, il se connectera au fichier à ce chemin sur l'hôte de production. + +En outre, [pousser tout changement de schéma de table](#pousser-les-schémas-de-table) (également connu sous le nom de "migrations de schéma") doit être géré manuellement à l'aide de cette variable d'environnement. + +:::danger +Si vous remplacez votre fichier `.db` lors du déploiement, vous perdrez vos données de production. Suivez attentivement le processus de la méthode de déploiement pour votre hôte afin d'éviter toute perte de données. +::: diff --git a/src/content/docs/fr/guides/backend/google-firebase.mdx b/src/content/docs/fr/guides/backend/google-firebase.mdx index 50b8de0968e84..040920a65e65f 100644 --- a/src/content/docs/fr/guides/backend/google-firebase.mdx +++ b/src/content/docs/fr/guides/backend/google-firebase.mdx @@ -20,13 +20,13 @@ Consultez notre guide dédié au [déploiement sur Firebase hosting](/fr/guides/ - Un [projet Firebase avec une application Web configurée](https://firebase.google.com/docs/web/setup). - Un projet astro avec [server-side rendering (SSR)](/fr/guides/server-side-rendering/) activé. -- Des identifiants Firebase : vous aurez besoin de deux ensembles d'identifiants pour connecter Astro à Firebase : - - Les identifiants de l'application Web : ces informations d'identification seront utilisées par le côté client de votre application. Vous pouvez les trouver dans la console Firebase sous *Paramètres du projet > Général*. Faites défiler jusqu'à la section **Vos applications** et cliquez sur l'icône **Application Web**. - - Les informations d'identification du projet : ces informations d'identification seront utilisées par le côté serveur de votre application. Vous pouvez les générer dans la console Firebase sous *Paramètres du projet > Comptes de service > Firebase Admin SDK > Générer une nouvelle clé privée*. +- Des identifiants Firebase : vous aurez besoin de deux ensembles d'identifiants pour connecter Astro à Firebase : + - Les identifiants de l'application Web : ces informations d'identification seront utilisées par le côté client de votre application. Vous pouvez les trouver dans la console Firebase sous *Paramètres du projet > Général*. Faites défiler jusqu'à la section **Vos applications** et cliquez sur l'icône **Application Web**. + - Les informations d'identification du projet : ces informations d'identification seront utilisées par le côté serveur de votre application. Vous pouvez les générer dans la console Firebase sous *Paramètres du projet > Comptes de service > Firebase Admin SDK > Générer une nouvelle clé privée*. ### Ajouter les informations d'identification Firebase -Pour ajouter vos informations d'identification Firebase à Astro, créez un fichier « .env » à la racine de votre projet avec les variables suivantes : +Pour ajouter vos informations d'identification Firebase à Astro, créez un fichier « .env » à la racine de votre projet avec les variables suivantes : ```ini title=".env" FIREBASE_PRIVATE_KEY_ID=YOUR_PRIVATE_KEY_ID @@ -79,7 +79,7 @@ Votre projet devrait à présent inclure les fichiers suivants : ### Installer les dépendances -Pour connecter Astro à Firebase, installez les paquets suivants à l'aide de la commande ci-dessous dans votre gestionnaire de paquets préféré : +Pour connecter Astro à Firebase, installez les paquets suivants à l'aide de la commande ci-dessous dans votre gestionnaire de paquets préféré : - `firebase` - le SDK Firebase pour le côté client - `firebase-admin` - le SDK Firebase Admin pour le côté serveur @@ -104,7 +104,7 @@ Pour connecter Astro à Firebase, installez les paquets suivants à l'aide de la Ensuite, créez un dossier nommé `firebase` dans le répertoire `src/ ` et ajoutez deux nouveaux fichiers à ce dossier : `client.ts` et `server.ts`. -Dans `client.ts`, ajoutez le code suivant pour initialiser Firebase côté client à l'aide des informations d'identification de votre application Web et du paquet « firebase » : +Dans `client.ts`, ajoutez le code suivant pour initialiser Firebase côté client à l'aide des informations d'identification de votre application Web et du paquet « firebase » : ```ts title="src/firebase/client.ts" import { initializeApp } from "firebase/app"; @@ -125,7 +125,7 @@ export const app = initializeApp(firebaseConfig); N'oubliez pas de remplacer l'objet `firebaseConfig` par vos propres informations d'identification d'application Web. ::: -Dans `server.ts`, ajoutez le code suivant pour initialiser Firebase côté serveur à l'aide des informations d'identification de votre projet et du package `firebase-admin` : +Dans `server.ts`, ajoutez le code suivant pour initialiser Firebase côté serveur à l'aide des informations d'identification de votre projet et du package `firebase-admin` : ```ts title="src/firebase/server.ts" import type { ServiceAccount } from "firebase-admin"; @@ -176,13 +176,13 @@ N'oubliez pas de remplacer l'objet `serviceAccount` par vos propres informations ### Créer les points de terminaison du serveur d'authentification -L'authentification Firebase dans Astro nécessite les trois [points de terminaison du serveur Astro](/fr/guides/endpoints/) suivants : +L'authentification Firebase dans Astro nécessite les trois [points de terminaison du serveur Astro](/fr/guides/endpoints/) suivants : - `GET /api/auth/signin` - pour connecter un utilisateur - `GET /api/auth/signout` - pour déconnecter un utilisateur - `POST /api/auth/register` - pour enregistrer un utilisateur -Créez trois points de terminaison liés à l'authentification dans un nouveau répertoire `src/pages/api/auth/` : `signin.ts`, `signout.ts` et `register.ts`. +Créez trois points de terminaison liés à l'authentification dans un nouveau répertoire `src/pages/api/auth/` : `signin.ts`, `signout.ts` et `register.ts`. `signin.ts` contient le code nécessaire pour connecter un utilisateur via Firebase : @@ -219,7 +219,7 @@ export const GET: APIRoute = async ({ request, cookies, redirect }) => { expiresIn: fiveDays, }); - cookies.set("session", sessionCookie, { + cookies.set("__session", sessionCookie, { path: "/", }); @@ -227,6 +227,10 @@ export const GET: APIRoute = async ({ request, cookies, redirect }) => { }; ``` +:::caution +Firebase n'autorise que l'utilisation [d'un seul cookie, qui doit être nommé `__session`](https://firebase.google.com/docs/hosting/manage-cache#using_cookies). Tout autre cookie envoyé par le client ne sera pas visible par votre application. +::: + :::note Il s'agit d'une implémentation de base du point de terminaison de connexion. Vous pouvez ajouter plus de logique à ce point de terminaison en fonction de vos besoins. ::: @@ -355,8 +359,8 @@ import Layout from "../layouts/Layout.astro"; /* On vérifie si l'utilisateur est authentifié */ const auth = getAuth(app); -if (Astro.cookies.has("session")) { - const sessionCookie = Astro.cookies.get("session").value; +if (Astro.cookies.has("__session")) { + const sessionCookie = Astro.cookies.get("__session").value; const decodedCookie = await auth.verifySessionCookie(sessionCookie); if (decodedCookie) { return Astro.redirect("/dashboard"); @@ -432,10 +436,10 @@ import Layout from "../layouts/Layout.astro"; const auth = getAuth(app); /* Vérification de la session */ -if (!Astro.cookies.has("session")) { +if (!Astro.cookies.has("__session")) { return Astro.redirect("/signin"); } -const sessionCookie = Astro.cookies.get("session").value; +const sessionCookie = Astro.cookies.get("__session").value; const decodedCookie = await auth.verifySessionCookie(sessionCookie); const user = await auth.getUser(decodedCookie.uid); @@ -461,7 +465,7 @@ Dans la console Firebase, accédez à la section **Authentification** et cliquez L'exemple ci-dessous utilise le fournisseur **Google**. -Modifiez la page `signin.astro` pour ajouter : +Modifiez la page `signin.astro` pour ajouter : - un bouton pour se connecter avec Google sous le formulaire existant - un écouteur d'événement sur le bouton pour gérer le processus de connexion dans le `