Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@AlexBlokh
AlexBlokh committed Jan 3, 2024
1 parent d535e0b commit e7cebe5
Show file tree
Hide file tree
Showing 3 changed files with 54 additions and 140 deletions.
168 changes: 28 additions & 140 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,156 +1,44 @@
<div align="center">
<h1>Drizzle ORM <a href=""><img alt="npm" src="https://img.shields.io/npm/v/drizzle-orm?label="></a></h1>
<img alt="npm" src="https://img.shields.io/npm/dm/drizzle-orm">
<img alt="npm bundle size" src="https://img.shields.io/bundlephobia/min/drizzle-orm">
<a href="https://discord.gg/yfjTbVXMW4" target="_blank"><img alt="Discord" src="https://img.shields.io/discord/1043890932593987624?label=Discord"></a>
<img alt="License" src="https://img.shields.io/npm/l/drizzle-orm">
<h6><i>If you know SQL, you know Drizzle ORM</i></h6>
<hr />
<img src="./misc/readme/logo-github-sq-dark.svg#gh-dark-mode-only" />
<img src="./misc/readme/logo-github-sq-light.svg#gh-light-mode-only" />
</div>

Drizzle ORM is a TypeScript ORM for SQL databases designed with maximum type safety in mind. It comes with a [drizzle-kit](https://github.com/drizzle-team/drizzle-kit-mirror) CLI companion for automatic SQL migrations generation. Drizzle ORM is meant to be a library, not a framework. It stays as an opt-in solution all the time at any levels.
The ORM's main philosophy is "If you know SQL, you know Drizzle ORM". We follow the SQL-like syntax whenever possible, are strongly typed ground up, and fail at compile time, not in runtime.
<br/>
<div align="center">
<h3>Headless ORM for NodeJS, TypeScript and JavaScript 🚀</h3>
<a href="https://orm.drizzle.team">Website</a> •
<a href="https://orm.drizzle.team/docs/overview">Documentation</a> •
<a href="https://x.com/drizzleorm">Twitter</a> •
<a href="https://driz.link/discord">Discord</a>
</div>

Drizzle ORM is being battle-tested on production projects by multiple teams 🚀 Give it a try and let us know if you have any questions or feedback on [Discord](https://discord.gg/yfjTbVXMW4).
<br/>
<br/>

## Features
### What's Drizzle?
Drizzle is a modern TypeScript ORM developers [wanna use in their next project](https://stateofdb.com/tools/drizzle).
It is [lightweight](https://bundlephobia.com/package/drizzle-orm) at only ~7.4kb minified+gzipped, it's tree shakeable with exactly 0 dependencies.

- Full type safety
- [Smart automated migrations generation](https://github.com/drizzle-team/drizzle-kit-mirror)
- No ORM learning curve
- SQL-like syntax for table definitions and queries
- Best in class fully typed joins
- Fully typed partial and non-partial selects of any complexity
- Auto-inferring of TS types for DB models for selections and insertions separately
- [Zod schema generation](/drizzle-zod/README.md)
- Zero dependencies
**Drizzle supports every PostgreSQL, MySQL and SQLite databases**, including serverless ones like [Turso](https://orm.drizzle.team/docs/get-started-sqlite#turso), [Neon](https://orm.drizzle.team/docs/get-started-postgresql#neon), [Xata](xata.io), [PlanetScale](https://orm.drizzle.team/docs/get-started-mysql#planetscale), [Cloudflare D1](https://orm.drizzle.team/docs/get-started-sqlite#cloudflare-d1), [FlyIO LiteFS](https://fly.io/docs/litefs/), [Vercel Postgres](https://orm.drizzle.team/docs/get-started-postgresql#vercel-postgres), [Supabase](https://orm.drizzle.team/docs/get-started-postgresql#supabase) and [AWS Data API](https://orm.drizzle.team/docs/get-started-postgresql#aws-data-api). No bells and whistles, no rust binaries, no serverless adapters, everything just works out of the box.

## Documentation
**Drizzle is serverless-ready by design**, it works in every major JavaScript runtime like NodeJS, Bun, Deno, Cloudflare Workers, Supabase functions, any Edge runtime and even in Browsers.
With Drizzle you can be [**fast out of the box**](https://orm.drizzle.team/benchmarks), save time and costs while never introducing any data proxies into your infrastructure.

Check the full documentation on [the website](https://orm.drizzle.team)
While you can use Drizzle as a JavaScript library, it shines in the TypeScript. It lets you [**declare SQL schema**](https://orm.drizzle.team/docs/sql-schema-declaration) and build both [**relational**](https://orm.drizzle.team/docs/rqb) and [**SQL-like queries**](https://orm.drizzle.team/docs/select), while keeping the balance between type-safety and extensibility for toolmakers to build on top.

## Supported databases
| Database | Support | | |
| :-------------- | :-----: | :------------------------------------------------ | :-------------------------------------------------------------------- |
| PostgreSQL | ✅ | [Docs](https://orm.drizzle.team/docs/quick-start) | |
| MySQL | ✅ | [Docs](https://orm.drizzle.team/docs/quick-start) | |
| SQLite | ✅ | [Docs](https://orm.drizzle.team/docs/quick-start) | |
| Cloudflare D1 | ✅ | [Docs](https://driz.link/docs-d1) | [Website](https://developers.cloudflare.com/d1) |
| libSQL | ✅ | [Docs](/examples/libsql/README.md) | [Website](https://libsql.org) |
| Turso | ✅ | [Docs](https://driz.link/docs-turso) | [Website](https://turso.tech) |
| PlanetScale | ✅ | [Docs](https://driz.link/docs-planetscale) | [Website](https://planetscale.com/) |
| Neon | ✅ | [Docs](https://driz.link/docs-neon) | [Website](https://neon.tech/) |
| Vercel Postgres | ✅ | [Docs](https://driz.link/docs-vercel-postgres) | [Website](https://vercel.com/docs/storage/vercel-postgres/quickstart) |
| Supabase | ✅ | [Docs](https://driz.link/docs-supabase) | [Website](https://supabase.com) |
| DynamoDB | ⏳ | | |
| MS SQL | ⏳ | | |
| CockroachDB | ⏳ | | |
### Ecosystem
While Drizzle ORM remains a thin typed layer on top of SQL, we made a set of tools for people to have best possible developer experience.

Drizzle comes with a powerful [**Drizzle Kit**](https://orm.drizzle.team/kit-docs/overview) CLI companion for you to have hasstle-free migrations. It can generate SQL migration files for you or apply schema changes directly to the database.

And we have a [**Drizzle Studio**](https://orm.drizzle.team/drizzle-studio/overview) for you to effortlessly browse and manipulate data in your database of choice.

## Our sponsors ❤️
### Documentation
Check out the full documentation on [the website](https://orm.drizzle.team/docs/overview)

### Our sponsors ❤️
<p align="center">
<a href="https://drizzle.team" target="_blank">
<img src='https://api.drizzle.team/github/sponsors/svg'/>
</a>
</p>

## Installation

```bash
npm install drizzle-orm
npm install -D drizzle-kit
```

## Feature showcase (PostgreSQL)

> **Note**: don't forget to install `pg` and `@types/pg` packages for this example to work.
```typescript
import { drizzle } from 'drizzle-orm/node-postgres';
import { integer, pgTable, serial, text, timestamp, varchar } from 'drizzle-orm/pg-core';
import { InferModel, eq, sql } from 'drizzle-orm';
import { Pool } from 'pg';

export const users = pgTable('users', {
id: serial('id').primaryKey(),
fullName: text('full_name').notNull(),
phone: varchar('phone', { length: 20 }).notNull(),
role: text('role', { enum: ['user', 'admin'] }).default('user').notNull(),
cityId: integer('city_id').references(() => cities.id),
createdAt: timestamp('created_at').defaultNow().notNull(),
updatedAt: timestamp('updated_at').defaultNow().notNull(),
});

export type User = InferModel<typeof users>;
export type NewUser = InferModel<typeof users, 'insert'>;

export const cities = pgTable('cities', {
id: serial('id').primaryKey(),
name: text('name').notNull(),
});

export type City = InferModel<typeof cities>;
export type NewCity = InferModel<typeof cities, 'insert'>;

const pool = new Pool({
connectionString: 'postgres://user:password@host:port/db',
});

const db = drizzle(pool);

// Insert
const newUser: NewUser = {
fullName: 'John Doe',
phone: '+123456789',
};
const insertedUsers /* : User[] */ = await db.insert(users).values(newUser).returning();
const insertedUser = insertedUsers[0]!;

const newCity: NewCity = {
name: 'New York',
};
const insertedCities /* : City[] */ = await db.insert(cities).values(newCity).returning();
const insertedCity = insertedCities[0]!;

// Update
const updateResult /* : { updated: Date }[] */ = await db.update(users)
.set({ cityId: insertedCity.id, updatedAt: new Date() })
.where(eq(users.id, insertedUser.id))
.returning({ updated: users.updatedAt });

// Select
const allUsers /* : User[] */ = await db.select().from(users);

// Select custom fields
const upperCaseNames /* : { id: number; name: string }[] */ = await db
.select({
id: users.id,
name: sql<string>`upper(${users.fullName})`,
})
.from(users);

// Joins
// You wouldn't BELIEVE how SMART the result type is! 😱
const allUsersWithCities = await db
.select({
id: users.id,
name: users.fullName,
city: {
id: cities.id,
name: cities.name,
},
})
.from(users)
.leftJoin(cities, eq(users.cityId, cities.id));

// Delete
const deletedNames /* : { name: string }[] */ = await db.delete(users)
.where(eq(users.id, insertedUser.id))
.returning({ name: users.fullName });
```

**See full docs for further reference:**

- [PostgreSQL](./drizzle-orm/src/pg-core/README.md)
- [MySQL](./drizzle-orm/src/mysql-core/README.md)
- [SQLite](./drizzle-orm/src/sqlite-core/README.md)
13 changes: 13 additions & 0 deletions misc/readme/logo-github-sq-dark.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
13 changes: 13 additions & 0 deletions misc/readme/logo-github-sq-light.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit e7cebe5

Please sign in to comment.