Skip to content

Commit abfcdd6

Browse files
AndriiShermanAndriiSherman
committed
Add docs for a new release
1 parent 7ac8fbc commit abfcdd6

File tree

4 files changed

+280
-0
lines changed

4 files changed

+280
-0
lines changed

‎src/content/docs/_meta.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@
5858
["drizzle-kit-migrate", "`migrate`"],
5959
["drizzle-kit-push", "`push`"],
6060
["drizzle-kit-pull", "`pull`"],
61+
["drizzle-kit-export", "`export`"],
6162
["drizzle-kit-check", "`check`"],
6263
["drizzle-kit-up", "`up`"],
6364
["drizzle-kit-studio", "`studio`"],

‎src/content/docs/drizzle-kit-export.mdx

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
import CodeTab from "@mdx/CodeTab.astro";
2+
import CodeTabs from "@mdx/CodeTabs.astro";
3+
import Section from "@mdx/Section.astro";
4+
import Tab from "@mdx/Tab.astro";
5+
import Tabs from "@mdx/Tabs.astro";
6+
import Callout from "@mdx/Callout.astro";
7+
import Prerequisites from "@mdx/Prerequisites.astro"
8+
import Npx from "@mdx/Npx.astro";
9+
import SchemaFilePaths from "@mdx/SchemaFilePaths.mdx"
10+
import Dialects from "@mdx/Dialects.mdx"
11+
12+
# `drizzle-kit export`
13+
14+
<Prerequisites>
15+
- Get started with Drizzle and `drizzle-kit` - [read here](/docs/get-started)
16+
- Drizzle schema foundamentals - [read here](/docs/sql-schema-declaration)
17+
- Database connection basics - [read here](/docs/connect-overview)
18+
- Drizzle migrations foundamentals - [read here](/docs/migrations)
19+
- Drizzle Kit [overview](/docs/kit-overview) and [config file](/docs/drizzle-config-file)
20+
</Prerequisites>
21+
22+
23+
<br/>
24+
25+
`drizzle-kit export` lets you export SQL representation of Drizzle schema and print in console SQL DDL representation on it.
26+
<Callout collapsed="How it works under the hood?">
27+
Drizzle Kit `export` command triggers a sequence of events:
28+
1. It will read through your Drizzle schema file(s) and compose a json snapshot of your schema
29+
3. Based on json differences it will generate SQL DDL statements
30+
4. Output SQL DDL statements to console
31+
</Callout>
32+
33+
It's designed to cover [codebase first](/docs/migrations) approach of managing Drizzle migrations.
34+
You can export the SQL representation of the Drizzle schema, allowing external tools like Atlas to handle all the migrations for you
35+
36+
`drizzle-kit export` command requires you to provide both `dialect` and `schema` path options,
37+
you can set them either via [drizzle.config.ts](/docs/drizzle-config-file) config file or via CLI options
38+
<CodeTabs items={["With config file", "As CLI options"]}>
39+
<Section>
40+
```ts
41+
// drizzle.config.ts
42+
import { defineConfig } from "drizzle-kit";
43+
44+
export default defineConfig({
45+
dialect: "postgresql",
46+
schema: "./src/schema.ts",
47+
});
48+
```
49+
```shell
50+
npx drizzle-kit export
51+
```
52+
</Section>
53+
54+
```shell
55+
npx drizzle-kit export --dialect=postgresql --schema=./src/schema.ts
56+
```
57+
</CodeTabs>
58+
59+
### Schema files path
60+
You can have a single `schema.ts` file or as many schema files as you want spread out across the project.
61+
Drizzle Kit requires you to specify path(s) to them as a [glob](https://www.digitalocean.com/community/tools/glob?comments=true&glob=/**/*.js&matches=false&tests=//%20This%20will%20match%20as%20it%20ends%20with%20'.js'&tests=/hello/world.js&tests=//%20This%20won't%20match!&tests=/test/some/globs) via `schema` configuration option.
62+
63+
<SchemaFilePaths/>
64+
65+
### Multiple configuration files in one project
66+
You can have multiple config files in the project, it's very useful when you have multiple database stages or multiple databases or different databases on the same project:
67+
<Npx>
68+
drizzle-kit export --config=drizzle-dev.config.ts
69+
drizzle-kit export --config=drizzle-prod.config.ts
70+
</Npx>
71+
```plaintext {5-6}
72+
📦 <project root>
73+
├ 📂 drizzle
74+
├ 📂 src
75+
├ 📜 .env
76+
├ 📜 drizzle-dev.config.ts
77+
├ 📜 drizzle-prod.config.ts
78+
├ 📜 package.json
79+
└ 📜 tsconfig.json
80+
```
81+
82+
### Extended list of available configurations
83+
`drizzle-kit export` has a list of cli-only options
84+
85+
<rem025/>
86+
87+
| | |
88+
| :-------- | :--------------------------------------------------- |
89+
| `--sql` | generating SQL representation of Drizzle Schema |
90+
91+
By default, Drizzle Kit outputs SQL files, but in the future, we want to support different formats
92+
93+
<rem025/>
94+
95+
<Npx>
96+
drizzle-kit push --name=init
97+
drizzle-kit push --name=seed_users --custom
98+
</Npx>
99+
100+
<br/>
101+
<hr/>
102+
<br/>
103+
We recommend configuring `drizzle-kit` through [drizzle.config.ts](/docs/drizzle-config-file) file,
104+
yet you can provide all configuration options through CLI if necessary, e.g. in CI/CD pipelines, etc.
105+
106+
| | | |
107+
| :------------ | :------- | :---------------------------------------------------------------------- |
108+
| `dialect` | `required` | Database dialect, one of <Dialects/> |
109+
| `schema` | `required` | Path to typescript schema file(s) or folder(s) with multiple schema files |
110+
| `config` | | Configuration file path, default is `drizzle.config.ts` |
111+
112+
### Example
113+
Example of how to export drizzle schema to console with Drizzle schema located in `./src/schema.ts`
114+
115+
We will also place drizzle config file in the `configs` folder.
116+
117+
Let's create config file:
118+
119+
```plaintext {4}
120+
📦 <project root>
121+
├ 📂 configs
122+
│ └ 📜 drizzle.config.ts
123+
├ 📂 src
124+
│ └ 📜 schema.ts
125+
└ …
126+
```
127+
```ts filename='drizzle.config.ts'
128+
import { defineConfig } from "drizzle-kit";
129+
130+
export default defineConfig({
131+
dialect: "postgresql",
132+
schema: "./src/schema.ts",
133+
});
134+
```
135+
136+
```ts filename='schema.ts'
137+
import { pgTable, serial, text } from 'drizzle-orm/pg-core'
138+
139+
export const users = pgTable('users', {
140+
id: serial('id').primaryKey(),
141+
email: text('email').notNull(),
142+
name: text('name')
143+
});
144+
```
145+
146+
Now let's run
147+
```shell
148+
npx drizzle-kit export --config=./configs/drizzle.config.ts
149+
```
150+
And it will successfully output SQL representation of drizzle schema
151+
```bash
152+
CREATE TABLE "users" (
153+
"id" serial PRIMARY KEY NOT NULL,
154+
"email" text NOT NULL,
155+
"name" text
156+
);
157+
```

‎src/content/docs/migrations.mdx

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -350,3 +350,66 @@ CREATE TABLE "users" (
350350
351351
<rem/>
352352
<rem/>
353+
<rem/>
354+
355+
<Tag style="font-size: 12px">**Option 6**</Tag>
356+
> I want to have database schema in my TypeScript codebase,
357+
> I want Drizzle to output the SQL representation of my Drizzle schema to the console,
358+
> and I will apply them to my database via Atlas
359+
360+
<Callout collapsed="Expand details">
361+
That's a **codebase first** approach. You have your TypeScript Drizzle schema as a source of truth and
362+
Drizzle let's you export SQL statements based on your schema changes with [`drizzle-kit export`](/docs/drizzle-kit-generate) and then
363+
you can apply them to the database via external migration tools.
364+
365+
<Section>
366+
```typescript filename="src/schema.ts"
367+
import * as p from "drizzle-orm/pg-core";
368+
369+
export const users = p.pgTable("users", {
370+
id: p.serial().primaryKey(),
371+
name: p.text(),
372+
email: p.text().unique(),
373+
};
374+
```
375+
```
376+
┌────────────────────────┐
377+
│ $ drizzle-kit export │
378+
└─┬──────────────────────┘
379+
│
380+
└ 1. read your drizzle schema
381+
2. generated SQL representation of your schema
382+
┌ 4. outputs to console
383+
│
384+
│
385+
│
386+
│
387+
│
388+
v
389+
```
390+
```sql
391+
CREATE TABLE "users" (
392+
"id" SERIAL PRIMARY KEY,
393+
"name" TEXT,
394+
"email" TEXT UNIQUE
395+
);
396+
```
397+
```
398+
┌───────────────────────────────────┐
399+
│ (._.) now you run your migrations │
400+
└─┬─────────────────────────────────┘
401+
│
402+
via Atlas
403+
│ ┌──────────────┐
404+
│ ┌────────────────────┐ │ │
405+
└──│ Atlas ├───────────>│ Database │
406+
└────────────────────┘ │ │
407+
└──────────────┘
408+
409+
[✓] done!
410+
```
411+
</Section>
412+
</Callout>
413+
414+
<rem/>
415+
<rem/>

‎src/content/docs/select.mdx

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -807,4 +807,63 @@ const iterator = await query.iterator();
807807
for await (const row of iterator) {
808808
console.log(row);
809809
}
810+
```
811+
812+
## ---
813+
814+
### Use Index
815+
816+
The `USE INDEX` hint suggests to the optimizer which indexes to consider when processing the query. The optimizer is not forced to use these indexes but will prioritize them if they are suitable.
817+
818+
<IsSupportedChipGroup chips={{ 'MySQL': true, 'PostgreSQL': false, 'SQLite': false, 'SingleStore': false }} />
819+
820+
```ts copy
821+
export const users = mysqlTable('users', {
822+
id: int('id').primaryKey(),
823+
name: varchar('name', { length: 100 }).notNull(),
824+
}, () => [usersTableNameIndex]);
825+
826+
const usersTableNameIndex = index('users_name_index').on(users.name);
827+
828+
await db.select()
829+
.from(users, { useIndex: usersTableNameIndex })
830+
.where(eq(users.name, 'David'));
831+
```
832+
833+
### Ignore Index
834+
835+
The `IGNORE INDEX` hint tells the optimizer to avoid using specific indexes for the query. MySQL will consider all other indexes (if any) or perform a full table scan if necessary.
836+
837+
<IsSupportedChipGroup chips={{ 'MySQL': true, 'PostgreSQL': false, 'SQLite': false, 'SingleStore': false }} />
838+
839+
```ts copy
840+
export const users = mysqlTable('users', {
841+
id: int('id').primaryKey(),
842+
name: varchar('name', { length: 100 }).notNull(),
843+
}, () => [usersTableNameIndex]);
844+
845+
const usersTableNameIndex = index('users_name_index').on(users.name);
846+
847+
await db.select()
848+
.from(users, { ignoreIndex: usersTableNameIndex })
849+
.where(eq(users.name, 'David'));
850+
```
851+
852+
### Force Index
853+
854+
The `FORCE INDEX` hint forces the optimizer to use the specified index(es) for the query. If the specified index cannot be used, MySQL will not fall back to other indexes; it might resort to a full table scan instead.
855+
856+
<IsSupportedChipGroup chips={{ 'MySQL': true, 'PostgreSQL': false, 'SQLite': false, 'SingleStore': false }} />
857+
858+
```ts copy
859+
export const users = mysqlTable('users', {
860+
id: int('id').primaryKey(),
861+
name: varchar('name', { length: 100 }).notNull(),
862+
}, () => [usersTableNameIndex]);
863+
864+
const usersTableNameIndex = index('users_name_index').on(users.name);
865+
866+
await db.select()
867+
.from(users, { forceIndex: usersTableNameIndex })
868+
.where(eq(users.name, 'David'));
810869
```

0 commit comments

Comments
 (0)