Astro DB
Astro DB è un database SQL completamente gestito progettato esclusivamente per Astro. Sviluppa localmente o connettiti a un database ospitato gestito sulla nostra piattaforma Astro Studio.
Installazione
Sezione intitolata InstallazioneAggiungi Astro DB a un nuovo o esistente progetto Astro (richiede astro@4.5
o successivo) con l’integrazione @astrojs/db
(v0.8.0
o successivo). Astro include un comando integrato astro add
per automatizzare questo processo di configurazione per te.
Se preferisci, puoi installare @astrojs/db
manualmente invece.
Definisci il tuo database
Sezione intitolata Definisci il tuo databaseAstro DB è una soluzione completa per configurare, sviluppare e interrogare i tuoi dati. Un database locale viene creato ogni volta che esegui astro dev
, utilizzando LibSQL per gestire i tuoi dati senza la necessità di Docker o di una connessione di rete.
Installare @astrojs/db
con il comando astro add
creerà un file db/config.ts
nel tuo progetto dove definirai le tabelle del tuo database:
Tabelle
Sezione intitolata TabelleI dati in Astro DB sono memorizzati utilizzando tabelle SQL. Le tabelle strutturano i tuoi dati in righe e colonne, dove le colonne impongono il tipo di ogni valore di riga.
Quando definisci una tabella, Astro genererà un’interfaccia TypeScript per interrogare quella tabella dal tuo progetto. Il risultato è un supporto completo di TypeScript quando accedi ai tuoi dati con il completamento automatico delle proprietà e type-checking.
Per configurare una tabella del database, importa e utilizza le utility defineTable()
e column
da astro:db
.
Questo esempio configura una tabella Comment
con colonne di testo obbligatorie per author
e body
. Quindi, rendila disponibile al tuo progetto attraverso l’esportazione defineDb()
.
Colonne
Sezione intitolata ColonneAstro DB supporta i seguenti tipi di colonne:
Riferimenti alle Tabelle
Sezione intitolata Riferimenti alle TabelleLe relazioni tra tabelle sono un modello comune nella progettazione dei database. Ad esempio, una tabella Blog
può essere strettamente correlata ad altre tabelle di Comment
, Author
e Category
.
Puoi definire queste tabelle di relazioni e salvarle nel tuo schema di database utilizzando colonne di riferimento. Per stabilire una relazione, avrai bisogno di:
- Una colonna identificativa sulla tabella di riferimento. Solitamente si tratta di una colonna
id
con la proprietàprimaryKey
. - Una colonna sulla tabella base per memorizzare l’
id
di riferimento. Questo utilizza la proprietàreferences
per stabilire una relazione.
Questo esempio mostra la colonna authorId
di una tabella Comment
che fa riferimento alla colonna id
di una tabella Author
.
Popola il tuo database
Sezione intitolata Popola il tuo databaseIn fase di sviluppo, Astro utilizzerà la tua configurazione DB per generare tipi locali in base ai tuoi schemi. Questi verranno generati nuovamente ogni volta che il server di sviluppo viene avviato e ti permetteranno di interrogare e lavorare con la forma dei tuoi dati con sicurezza dei tipi e autocompletamento.
Per popolare dati di sviluppo per test e debug nel tuo progetto Astro, crea un file db/seed.ts
. Importa sia l’oggetto db
che qualsiasi tabella configurata da astro:db
. Usa la funzione db.insert()
per fornire un array di oggetti di dati di righe di tabella.
L’esempio seguente definisce due righe di dati di sviluppo per una tabella Comment
:
Il tuo server di sviluppo riavvierà automaticamente il tuo database ogni volta che questo file cambia, rigenerando i tuoi tipi e popolando i tuoi dati di sviluppo da seed.ts
.
Interroga il tuo database
Sezione intitolata Interroga il tuo databasePuoi interrogare il tuo database da qualsiasi pagina Astro o endpoint nel tuo progetto utilizzando l’ORM db
fornito e il costruttore di query.
Drizzle ORM
Sezione intitolata Drizzle ORMAstro DB include un client Drizzle ORM integrato. Non è necessaria alcuna configurazione o impostazione manuale per utilizzare il client. Il client db
di Astro DB è automaticamente configurato per comunicare con il tuo database (locale o remoto) quando esegui Astro. Utilizza la tua esatta definizione dello schema del database per query SQL type-safe con errori TypeScript quando fai riferimento a una colonna o tabella che non esiste.
L’esempio seguente seleziona tutte le righe di una tabella Comment
. Questo restituisce l’intero array di dati di sviluppo popolati da db/seed.ts
che è quindi disponibile per l’uso nel tuo template di pagina:
select()
di Drizzle per una panoramica completa.
Per accettare input dell’utente, come gestire richieste di form e inserire dati nel tuo database ospitato remoto, configura il tuo progetto Astro per la rendering on-demand e aggiungi un adattatore SSR per il tuo ambiente di distribuzione.
Questo esempio inserisce una riga in una tabella Comment
in base a una richiesta POST di un form analizzata:
Puoi anche interrogare il tuo database da un endpoint API. Questo esempio elimina una riga da una tabella Comment
tramite il parametro id
:
Vedi il riferimento all’API insert()
di Drizzle per una panoramica completa.
Filtraggio
Sezione intitolata FiltraggioPer interrogare i risultati delle tabelle per una proprietà specifica, usa le opzioni Drizzle per selezioni parziali. Ad esempio, aggiungi una chiamata .where()
alla tua query select()
e passa il confronto che vuoi fare.
L’esempio seguente interroga tutte le righe in una tabella Comment
che contengono la frase “Astro DB”. Usa l’operatore like()
per verificare se una frase è presente all’interno del body
:
Utilità Drizzle
Sezione intitolata Utilità DrizzleTutte le utilità Drizzle per costruire query sono esposte dal modulo astro:db
. Questo include:
- Operatori di filtro come
eq()
egt()
- Helper di aggregazione come
count()
- L’helper
sql
per scrivere query SQL grezze
Relazioni
Sezione intitolata RelazioniPuoi interrogare dati correlati da più tabelle utilizzando un join SQL. Per creare una query di join, estendi la tua dichiarazione db.select()
con un operatore di join. Ogni funzione accetta una tabella con cui unirsi e una condizione per abbinare le righe tra le due tabelle.
Questo esempio utilizza una funzione innerJoin()
per unire gli autori dei Comment
con le loro informazioni Author
correlate in base alla colonna authorId
. Questo restituisce un array di oggetti con ogni riga Author
e Comment
come proprietà di primo livello:
Vedi il riferimento join di Drizzle per tutti gli operatori di join disponibili e le opzioni di configurazione.
Transazioni Batch
Sezione intitolata Transazioni BatchTutte le query al database remoto vengono effettuate come una richiesta di rete. Potresti aver bisogno di “raggruppare” le query insieme in una singola transazione quando effettui un gran numero di query, o per avere rollback automatici se una query fallisce.
Questo esempio inserisce più righe in una singola richiesta utilizzando il metodo db.batch()
:
Vedi i documenti db.batch()
di Drizzle per maggiori dettagli.
Astro Studio
Sezione intitolata Astro StudioAstro DB può connettersi alla piattaforma Astro Studio per aggiungere rapidamente un database ospitato al tuo progetto. Puoi visualizzare, gestire e distribuire nuovi database ospitati direttamente dalla dashboard di Astro Studio.
Per creare un nuovo progetto, puoi utilizzare un template già pronto o visitare la guida di Astro Studio.
Pubblicazione degli schemi delle tabelle
Sezione intitolata Pubblicazione degli schemi delle tabelleIl tuo schema delle tabelle cambierà nel tempo man mano che il tuo progetto cresce. Puoi testare in sicurezza le modifiche alla configurazione localmente e spingerle al tuo database Studio quando effettui il deploy.
Quando crei un progetto Studio dalla dashboard, avrai l’opzione di creare un’azione CI di GitHub. Questo migrerà automaticamente le modifiche allo schema quando si fonde con il ramo principale del tuo repository.
Puoi anche pubblicare le modifiche allo schema locale ad Astro Studio tramite la CLI utilizzando il comando astro db push --remote
:
Questo comando verificherà che le modifiche locali possano essere effettuate senza perdita di dati e, se necessario, suggerirà come apportare in sicurezza modifiche allo schema per risolvere i conflitti.
Pubblicare modifiche distruttive allo schema
Sezione intitolata Pubblicare modifiche distruttive allo schemaQuesto distruggerà il tuo database. Esegui questo comando solo se non hai bisogno dei tuoi dati di produzione.
Se devi modificare lo schema della tabella in un modo incompatibile con i tuoi dati esistenti ospitati su Astro Studio, dovrai resettare il tuo database di produzione.
Per pubblicare un aggiornamento dello schema della tabella che include una modifica di rottura, aggiungi il flag --force-reset
per resettare tutti i dati di produzione:
Rinominare le tabelle
Sezione intitolata Rinominare le tabelleÈ possibile rinominare una tabella dopo aver pubblicato lo schema su Astro Studio.
Se non hai dati di produzione importanti, puoi resettare il tuo database utilizzando il flag --force-reset
. Questo flag eliminerà tutte le tabelle nel database e ne creerà di nuove in modo che corrisponda esattamente al tuo schema attuale.
Per rinominare una tabella preservando i dati di produzione, devi eseguire una serie di modifiche non di rottura per pubblicare in sicurezza lo schema locale su Astro Studio.
L’esempio seguente rinomina una tabella da Comment
a Feedback
:
-
Nel file di configurazione del database, aggiungi la proprietà
deprecated: true
alla tabella che vuoi rinominare: -
Aggiungi un nuovo schema di tabella (corrispondente esattamente alle proprietà della tabella esistente) con il nuovo nome:
-
Pubblica su Astro Studio con
astro db push --remote
. Questo aggiungerà la nuova tabella e segnerà la vecchia come deprecata. -
Aggiorna qualsiasi codice del tuo progetto locale per utilizzare la nuova tabella invece della vecchia. Potresti anche dover migrare i dati nella nuova tabella.
-
Una volta che sei sicuro che la vecchia tabella non viene più utilizzata nel tuo progetto, puoi rimuovere lo schema dal tuo
config.ts
: -
Pubblica di nuovo su Astro Studio con
astro db push --remote
. La vecchia tabella verrà eliminata, lasciando solo la nuova tabella rinominata.
Pubblicazione dei dati
Sezione intitolata Pubblicazione dei datiPotresti aver bisogno di spingere dati al tuo database Studio per seeding o migrazioni di dati. Puoi scrivere un file .ts
con il modulo astro:db
per scrivere query type-safe. Poi, esegui il file contro il tuo database Studio usando il comando astro db execute <file-path> --remote
:
I seguenti Commenti possono essere inseriti utilizzando il comando astro db execute db/seed.ts --remote
:
Vedi il riferimento CLI per un elenco completo dei comandi.
Collegamento ad Astro Studio
Sezione intitolata Collegamento ad Astro StudioPer impostazione predefinita, Astro utilizzerà un file di database locale ogni volta che esegui i comandi dev
o build
. Le tabelle vengono ricreate da zero ogni volta che viene eseguito un comando e i dati di seed di sviluppo verranno inseriti.
Per collegarti al tuo database ospitato Studio, puoi aggiungere il flag --remote
. Usa questo flag per i deploy di produzione per avere accesso sia in lettura che in scrittura al tuo database Studio. Questo ti permetterà di accettare e persistere i dati degli utenti.
Fai attenzione usando --remote
in sviluppo. Questo collegherà a un database di produzione live, e tutti gli inserimenti, aggiornamenti o cancellazioni verranno persistiti.
Per utilizzare una connessione remota, avrai bisogno di un token dell’app per autenticarti con Studio. Visita la dashboard di Studio per le istruzioni sulla creazione e configurazione del token.
Quando sei pronto per il deploy, consulta la nostra guida al Deploy con una Connessione Studio.
Costruzione di integrazioni Astro DB
Sezione intitolata Costruzione di integrazioni Astro DBLe integrazioni Astro possono estendere i progetti degli utenti con tabelle Astro DB aggiuntive e dati di seed.
Usa il metodo extendDb()
nell’hook astro:db:setup
per registrare ulteriori configurazioni Astro DB e file di seed.
L’helper defineDbIntegration()
fornisce supporto TypeScript e autocompletamento per l’hook astro:db:setup
.
I file di configurazione e seed delle integrazioni seguono lo stesso formato dei loro equivalenti definiti dall’utente.
Operazioni tipizzate nelle integrazioni
Sezione intitolata Operazioni tipizzate nelle integrazioniLavorando sulle integrazioni, potresti non essere in grado di beneficiare dei tipi di tabella generati da Astro esportati da astro:db
.
Per la piena sicurezza dei tipi, usa l’utilità asDrizzleTable()
per creare un oggetto di riferimento della tabella che puoi usare per le operazioni sul database.
Ad esempio, data un’integrazione che configura la seguente tabella del database Pets
:
Il file seed può importare Pets
e usare asDrizzleTable()
per inserire righe nella tua tabella con il controllo dei tipi:
Il valore restituito da asDrizzleTable('Pets', Pets)
è equivalente a import { Pets } from 'astro:db'
, ma è disponibile anche quando la generazione dei tipi di Astro non può essere eseguita.
Puoi usarlo in qualsiasi codice di integrazione che necessita di interrogare o inserire nel database.
Distribuzione di produzione self-hosted
Sezione intitolata Distribuzione di produzione self-hostedSe distribuisci il tuo sito su un host autogestito come un server privato virtuale, puoi scegliere di utilizzare un file di database invece di connetterti a un database ospitato su Astro Studio.
L’utilizzo di un file di database è una funzionalità avanzata e occorre prestare attenzione durante la distribuzione per evitare di sovrascrivere il database e perdere i dati di produzione.
Inoltre, questo metodo non funzionerà nelle distribuzioni serverless, poiché il file system non viene persistito in tali ambienti.
Per una soluzione completamente gestita, connettiti invece ai database ospitati sulla piattaforma Astro Studio.
Se sei a tuo agio con i rischi e puoi gestire la distribuzione autonomamente, puoi utilizzare un file di database invece di connetterti a Studio.
Imposta la variabile d’ambiente ASTRO_DATABASE_FILE
su un percorso che punta al tuo file .db
all’interno dell’ambiente host durante la build:
La build compilerà staticamente con questo percorso come database di produzione. Quando distribuisci e avvii il server, si connetterà al file in questo percorso sull’host di produzione.
Inoltre, la pubblicazione di eventuali modifiche allo schema delle tabelle (note anche come “migrazioni dello schema”) deve essere gestita manualmente utilizzando questa variabile d’ambiente.
Se sovrascrivi il tuo file .db
durante la distribuzione, perderai i dati di produzione. Segui attentamente il processo del metodo di distribuzione per il tuo host per evitare la perdita di dati.