diff --git a/changelogs/drizzle-kit/0.25.0.md b/changelogs/drizzle-kit/0.25.0.md index 0c1c5ea6e..fc4b36c83 100644 --- a/changelogs/drizzle-kit/0.25.0.md +++ b/changelogs/drizzle-kit/0.25.0.md @@ -1,4 +1,55 @@ -## Libsql and Sqlite migration updates +## Breaking changes and migrate guide for Turso users + +If you are using Turso and libsql, you will need to upgrade your `drizzle.config` and `@libsql/client` package. + +1. This version of drizzle-orm will only work with `@libsql/client@0.10.0` or higher if you are using the `migrate` function. For other use cases, you can continue using previous versions(But the suggestion is to upgrade) +To install the latest version, use the command: + +```bash +npm i @libsql/client@latest +``` + +2. Previously, we had a common `drizzle.config` for SQLite and Turso users, which allowed a shared strategy for both dialects. Starting with this release, we are introducing the turso dialect in drizzle-kit. We will evolve and improve Turso as a separate dialect with its own migration strategies. + +**Before** + +```ts +import { defineConfig } from "drizzle-kit"; + +export default defineConfig({ + dialect: "sqlite", + schema: "./schema.ts", + out: "./drizzle", + dbCredentials: { + url: "database.db", + }, + breakpoints: true, + verbose: true, + strict: true, +}); +``` + +**After** + +```ts +import { defineConfig } from "drizzle-kit"; + +export default defineConfig({ + dialect: "turso", + schema: "./schema.ts", + out: "./drizzle", + dbCredentials: { + url: "database.db", + }, + breakpoints: true, + verbose: true, + strict: true, +}); +``` + +If you are using only SQLite, you can use `dialect: "sqlite"` + +## LibSQL/Turso and Sqlite migration updates ### SQLite "generate" and "push" statements updates @@ -35,14 +86,12 @@ ALTER TABLE `__new_worker` RENAME TO `worker`; PRAGMA foreign_keys=ON; ``` -### LibSQL "generate" and "push" statements updates +### LibSQL/Turso "generate" and "push" statements updates Since LibSQL supports more ALTER statements than SQLite, we can generate more statements without recreating your schema and moving all the data, which can be potentially dangerous for production environments. LibSQL and Turso will now have a separate dialect in the Drizzle config file, meaning that we will evolve Turso and LibSQL independently from SQLite and will aim to support as many features as Turso/LibSQL offer. -> **Breaking change!** All users who want to get the most out of Turso and LibSQL DDL statements should remove `driver: turso` from the `drizzle.config` file and add `dialect: turso` instead - With the updated LibSQL migration strategy, you will have the ability to: - **Change Data Type**: Set a new data type for existing columns. @@ -56,7 +105,7 @@ You can find more information in the [LibSQL documentation](https://github.com/t - Dropping or altering an index will cause table recreation. -This is because LibSQL does not support dropping this type of index. +This is because LibSQL/Turso does not support dropping this type of index. ```sql CREATE TABLE `users` ( @@ -71,7 +120,7 @@ CREATE TABLE `users` ( - Drizzle-Kit will drop the indexes, modify the columns, and then recreate the indexes. - Adding or dropping composite foreign keys is not supported and will cause table recreation -### NOTES: +### NOTES - You can create a reference on any column type, but if you want to insert values, the referenced column must have a unique index or primary key. diff --git a/changelogs/drizzle-orm/0.34.0.md b/changelogs/drizzle-orm/0.34.0.md index 55eb0411f..490422628 100644 --- a/changelogs/drizzle-orm/0.34.0.md +++ b/changelogs/drizzle-orm/0.34.0.md @@ -1,4 +1,55 @@ -## Libsql and Sqlite migration updates +## Breaking changes and migrate guide for Turso users + +If you are using Turso and libsql, you will need to upgrade your `drizzle.config` and `@libsql/client` package. + +1. This version of drizzle-orm will only work with `@libsql/client@0.10.0` or higher if you are using the `migrate` function. For other use cases, you can continue using previous versions(But the suggestion is to upgrade) +To install the latest version, use the command: + +```bash +npm i @libsql/client@latest +``` + +2. Previously, we had a common `drizzle.config` for SQLite and Turso users, which allowed a shared strategy for both dialects. Starting with this release, we are introducing the turso dialect in drizzle-kit. We will evolve and improve Turso as a separate dialect with its own migration strategies. + +**Before** + +```ts +import { defineConfig } from "drizzle-kit"; + +export default defineConfig({ + dialect: "sqlite", + schema: "./schema.ts", + out: "./drizzle", + dbCredentials: { + url: "database.db", + }, + breakpoints: true, + verbose: true, + strict: true, +}); +``` + +**After** + +```ts +import { defineConfig } from "drizzle-kit"; + +export default defineConfig({ + dialect: "turso", + schema: "./schema.ts", + out: "./drizzle", + dbCredentials: { + url: "database.db", + }, + breakpoints: true, + verbose: true, + strict: true, +}); +``` + +If you are using only SQLite, you can use `dialect: "sqlite"` + +## LibSQL/Turso and Sqlite migration updates ### SQLite "generate" and "push" statements updates @@ -35,14 +86,12 @@ ALTER TABLE `__new_worker` RENAME TO `worker`; PRAGMA foreign_keys=ON; ``` -### LibSQL "generate" and "push" statements updates +### LibSQL/Turso "generate" and "push" statements updates Since LibSQL supports more ALTER statements than SQLite, we can generate more statements without recreating your schema and moving all the data, which can be potentially dangerous for production environments. LibSQL and Turso will now have a separate dialect in the Drizzle config file, meaning that we will evolve Turso and LibSQL independently from SQLite and will aim to support as many features as Turso/LibSQL offer. -> **Breaking change!** All users who want to get the most out of Turso and LibSQL DDL statements should remove `driver: turso` from the `drizzle.config` file and add `dialect: turso` instead - With the updated LibSQL migration strategy, you will have the ability to: - **Change Data Type**: Set a new data type for existing columns. @@ -56,7 +105,7 @@ You can find more information in the [LibSQL documentation](https://github.com/t - Dropping or altering an index will cause table recreation. -This is because LibSQL does not support dropping this type of index. +This is because LibSQL/Turso does not support dropping this type of index. ```sql CREATE TABLE `users` ( @@ -71,7 +120,7 @@ CREATE TABLE `users` ( - Drizzle-Kit will drop the indexes, modify the columns, and then recreate the indexes. - Adding or dropping composite foreign keys is not supported and will cause table recreation -### NOTES: +### NOTES - You can create a reference on any column type, but if you want to insert values, the referenced column must have a unique index or primary key. @@ -96,28 +145,77 @@ See more: https://www.sqlite.org/foreignkeys.html ## A new and easy way to start using drizzle -before on example with node-postgres +Current and the only way to do, is to define client yourself and pass it to drizzle ```ts -// 1, current const client = new Pool({ url: '' }); drizzle(client, { logger: true }); +``` + +But we want to introduce you to a new API, which is a simplified method in addition to the existing one. + +Most clients will have a few options to connect, starting with the easiest and most common one, and allowing you to control your client connection as needed. -// 2 -await drizzle('neon', { client: 'postgresql://...', logger: true }) +Let's use `node-postgres` as an example, but the same pattern can be applied to all other clients -// 3 -await drizzle('neon', { client: { url: 'postgresql://...' }, logger: true }) +```ts +// Finally, one import for all available clients and dialects! +import { drizzle } from 'drizzle-orm' + +// Choose a client and use a connection URL — nothing else is needed! +const db1 = await drizzle("node-postgres", process.env.POSTGRES_URL); + +// If you need to pass a logger, schema, or other configurations, you can use an object and specify the client-specific URL in the connection +const db2 = await drizzle("node-postgres", { + connection: process.env.POSTGRES_URL, + logger: true +}); + +// And finally, if you need to use full client/driver-specific types in connections, you can use a URL or host/port/etc. as an object inferred from the underlying client connection types +const db3 = await drizzle("node-postgres", { + connection: { + connectionString: process.env.POSTGRES_URL, + }, +}); -// 4 -await drizzle('neon', 'postgresql://...') +const db4 = await drizzle("node-postgres", { + connection: { + user: process.env.DB_USER, + password: process.env.DB_PASSWORD, + host: process.env.DB_HOST, + port: process.env.DB_PORT, + database: process.env.DB_NAME, + ssl: true, + }, +}); ``` -will become +A few clients will have a slightly different API due to their specific behavior. Let's take a look at them: + +For `aws-data-api-pg`, Drizzle will require `resourceArn`, `database`, and `secretArn`, along with any other AWS Data API client types for the connection, such as credentials, region, etc. ```ts -await drizzle('', { client: '', logger: true }) -await drizzle('', { client: {}, logger: true }) +drizzle("aws-data-api-pg", { + connection: { + resourceArn: "", + database: "", + secretArn: "", + }, +}); +``` + +For `d1`, the Cloudflare Worker types as described in the [documentation](https://developers.cloudflare.com/d1/get-started/) here will be required. + +```ts +drizzle("d1", { + connection: env.DB // Cloudflare Worker Types +}) +``` + +For `vercel-postgres`, nothing is needed since Vercel automatically retrieves the `POSTGRES_URL` from the `.env` file. You can check this [documentation](https://vercel.com/docs/storage/vercel-postgres/quickstart) for more info + +```ts +drizzle("vercel-postgres") ``` > Note that the first example with the client is still available and not deprecated. You can use it if you don't want to await the drizzle object. The new way of defining drizzle is designed to make it easier to import from one place and get autocomplete for all the available clients @@ -125,12 +223,14 @@ await drizzle('', { client: {}, logger: true }) ## New "count" API Befor this release to count entities in a table, you would need to do this: + ```ts const res = await db.select({ count: sql`count(*)` }).from(users); const count = res[0].count; ``` The new API will look like this: + ```ts // how many users are in the database const count: number = await db.$count(users); @@ -140,6 +240,7 @@ const count: number = await db.$count(users, eq(name, "Dan")); ``` This can also work as a subquery and within relational queries + ```ts const users = await db.select({ ...users,