Infrastructure/astro
0
Fork 0
mirror of https://github.com/withastro/astro.git synced 2025-02-03 22:29:08 -05:00
Code Issues Activity

chore: delete README contents (now on Notion)

Browse source
This commit is contained in:
bholmesdev 2024-01-19 16:40:18 -05:00 • committed by Nate Moore
parent 674fae454d
commit d81d5ef5a8
1 changed files with 0 additions and 199 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

199
packages/db/README.md
View file

@ -1,200 +1 @@
# `@astrojs/db` # `@astrojs/db`
Astro DB helps you create a SQLite database with powerful query APIs.
## Installation
`@astrojs/db` is an Astro integration you can install with the `astro add` command:
```bash
# npm
npm run astro add db
# pnpm
pnpm astro add db
```
## Configure your first collection
“Collections” are database tables you can query from your Astro project. To create a collection, you can use the `defineCollection()` and `field` utilities provided by `@astrojs/db`. All collections should be applied to the `db` object in your `astro.config.mjs` file:
```js
import { defineCollection, field } from '@astrojs/db';
import { defineConfig } from 'astro/config';
const Author = defineCollection({
fields: {
name: field.text(),
socialLink: field.text({ optional: true }),
isFeatured: field.boolean(),
}
});
export default defineConfig({
db: {
collections: { Author },
}
});
```
📚 See the `defineCollection()` API reference for all supported fields and configuration options.
### Default `id` field
All collections will be created with a generated `id` field. This can be used to fetch individual entries or “join” related tables. This `id` will be be of type “text” with a generated [nanoid](https://www.npmjs.com/package/nanoid).
## Pass collection data
Collections are considered “read-only” by default. To set collection data, you can add the `data()` function to your collection config. This should return an array of objects to insert into the database, with keys matching your collection `fields`:
```js
import { defineCollection, field } from '@astrojs/db';
import { defineConfig } from 'astro/config';
const Author = defineCollection({
fields: {…},
data() {
return [
{ name: 'Fred K Schott' },
{ name: 'Ben Holmes', isFeatured: true },
{ name: 'ThePrimeagen', socialLink: 'https://twitch.tv/ThePrimeagen' },
]
}
});
export default defineConfig({
db: {
collections: { Author },
}
});
```
### Glob data from the filesystem
You may want to glob a directory of files (say `.json`) to insert as database rows. You can install the `fast-glob` package to glob from your `astro.config.mjs` file:
```bash
# npm
npm i fast-glob
# pnpm
pnpm i fast-glob
```
Then, call `glob()` over your directory of choice, and parse each file’s contents using Node `readFile()` and `JSON.parse()`:
```js
import { glob } from 'fast-glob';
import { readFile } from 'node:fs/promises';
import { defineCollection, field } from '@astrojs/db';
import { defineConfig } from 'astro/config';
const Author = defineCollection({
fields: {…},
async data() {
const authors = await glob(‘authors/**/*.json’);
return Promise.all(authors.map(async (author => {
const contents = await readfile(author);
return JSON.parse(contents);
})));
}
});
export default defineConfig({
db: {
collections: { Author },
}
});
```
## Query data
You can query collection data using the `@astrojs/db` SQL ORM. This is powered by [Drizzle ORM](https://orm.drizzle.team/), exposing collections as Drizzle objects you can use to construct type-safe SQL queries.
You can create queries using the `db` object provided by the `astro:db` module. This example selects all entries in the Authors collection and renders the results to a list:
```astro
---
import { db, Author } from 'astro:db';
const authors = await db.select().from(Author);
---
<h2>Authors</h2>
<ul>
{authors.map(({ name, socialLink }) => (
<li>
socialLink ? <a href={socialLink}>{name}</a> : name
</li>
))}
</ul>
```
### Filter data
You can [filter entries](https://orm.drizzle.team/docs/select#filtering) using a `where()` clause. This accepts [conditional functions](https://orm.drizzle.team/docs/operators) like `eq()`, which can be used to assert a field has a particular value. This example filters for “featured” authors in the `Authors` collection:
```astro
---
import { db, eq, Author } from 'astro:db';
const authors = await db.select().from(Author).where(
eq(Author.isFeatured, true),
);
---
```
### Join related data
You may want to join related collections by `id`. You can handle joins using [a SQL join operator](https://orm.drizzle.team/docs/joins#join-types) like `innerJoin()`.
This example stores an Author's social links in a separate collection named `SocialLink`. This collection includes the `authorId` as a field to relate multiple social links to a given author:
```js
// astro.config.mjs
import { defineCollection, field } from '@astrojs/db';
import { defineConfig } from 'astro/config';
const Author = defineCollection({
fields: {
name: field.text(),
isFeatured: field.boolean(),
},
data() {
return [
{ id: 'fks', name: 'Fred K Schott' },
{ id: 'bh', name: 'Ben Holmes', isFeatured: true },
{ id: 'prime', name: 'ThePrimeagen' },
]
}
});
const SocialLink = defineCollection({
fields: {
authorId: field.text(),
url: field.text(),
},
data() {
return [
{ authorId: 'prime', url: 'https://twitch.tv/ThePrimeagen' }
]
}
});
export default defineConfig({
db: {
collections: { Author, SocialLink },
}
});
```
You can join all social links to a given author by using a join query. This example uses a `leftJoin()`, meaning that all authors will be returned, and social links will be joined if they exist (`undefined` otherwise):
```astro
---
import { db, eq, Author, SocialLink } from 'astro:db';
const authors = await db.select().from(Author)
.innerJoin(SocialLink, eq(Author.id, SocialLink.authorId));
---
```
## Writable data with Astro Studio
TODO