Merge pull request #152 from drizzle-team/add-feature-overview-docs

Add feature showcase section to README

.markdownlint.yaml

@@ -3,4 +3,3 @@ first-line-h1: false
 line-length: false
 MD010:
   spaces_per_tab: 2
-  code_blocks: false

README.md

@@ -25,9 +25,9 @@ Drizzle ORM is being battle-tested on production projects by multiple teams 🚀
 - Auto-inferring of TS types for DB models for selections and insertions separately
 - Zero dependencies
 
-## Database support status
+## Supported databases
 
-| Database    | Support | |
+| Database    | Status | |
 |:------------|:-------:|:---|
 | PostgreSQL  | ✅ | [Docs](./drizzle-orm/src/pg-core/README.md)|
 | MySQL       | ✅      |[Docs](./drizzle-orm/src/mysql-core/README.md)|
@@ -43,4 +43,94 @@ npm install drizzle-orm
 npm install -D drizzle-kit
 ```
 
-See [dialect-specific docs](#database-support-status) for more details.
+## Feature showcase (PostgreSQL)
+
+> **Note**: don't forget to install `pg` and `@types/pg` packages for this example to work.
+
+```typescript
+import { eq } from 'drizzle-orm/expressions';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { InferModel, integer, pgTable, serial, text, timestamp, varchar } from 'drizzle-orm/pg-core';
+import { sql } from 'drizzle-orm/sql';
+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<'user' | 'admin'>('role').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(users);
+
+// Select custom fields
+const upperCaseNames /* : { id: number; name: string }[] */ = await db.select(users)
+  .fields({
+    id: users.id,
+    name: sql`upper(${users.fullName})`.as<string>(),
+  });
+
+// Joins
+// You wouldn't BELIEVE how SMART the result type is! 😱
+const allUsersWithCities = await db.select(users)
+  .fields({
+    user: {
+      id: users.id,
+      name: users.fullName,
+    },
+    cityId: cities.id,
+    cityName: cities.name,
+  })
+  .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)

changelogs/drizzle-orm/0.17.0.md

@@ -1,5 +1,3 @@
-# drizzle-orm 0.17.0
-
 ## ❗ All ORM packages are now merged into `drizzle-orm`
 
 Starting from release `0.17.0` and onwards, all dialect-specific packages are merged into `drizzle-orm`. Legacy ORM packages will be archived.

changelogs/drizzle-orm/0.17.1.md

@@ -0,0 +1 @@
+- Added feature showcase section to README

docs/custom-types.lite.md

@@ -2,11 +2,11 @@
 
 > **Info**: For more advanced documentation about defining custom data types in PostgreSQL and MySQL please check [custom-types.md](https://github.com/drizzle-team/drizzle-orm/blob/main/docs/custom-types.md)
 
-# Examples
+## Examples
 
 Best way to see, how customType definition is working - is to check how existing data types in postgres and mysql could be defined using `customType` function from Drizzle ORM
 
-### Postgres Data Types using `node-pg` driver
+### Postgres Data Types using `node-postgres` driver
 
 ---
 

drizzle-orm/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "drizzle-orm",
-	"version": "0.17.0",
+	"version": "0.17.1",
 	"description": "Drizzle ORM package for SQL databases",
 	"scripts": {
 		"build": "tsc && resolve-tspaths && cp ../README.md package.json dist/",

drizzle-orm/src/pg-core/README.md

@@ -80,7 +80,7 @@ export const users = pgTable('users', {
 ```typescript
 // db.ts
 import { pgTable, serial, text, varchar } from 'drizzle-orm/pg-core';
-import { drizzle } from 'drizzle-orm/node-pg';
+import { drizzle } from 'drizzle-orm/node-postgres';
 import { Pool } from 'pg';
 
 import { users } from './schema';
@@ -107,7 +107,7 @@ const allUsers = await db.select(users);
 ```typescript
 // db.ts
 import { pgTable, serial, text, varchar } from 'drizzle-orm/pg-core';
-import { drizzle } from 'drizzle-orm/node-pg';
+import { drizzle } from 'drizzle-orm/node-postgres';
 import { Client } from 'pg';
 
 import { users } from './schema';
@@ -162,7 +162,7 @@ export const cities = pgTable('cities', {
 
 ```typescript
 import { pgTable, InferModel, serial, text, varchar } from 'drizzle-orm/pg-core';
-import { drizzle, NodePgDatabase } from 'drizzle-orm/node-pg';
+import { drizzle, NodePgDatabase } from 'drizzle-orm/node-postgres';
 
 const users = pgTable('users', {
   id: serial('id').primaryKey(),
@@ -332,7 +332,7 @@ Querying, sorting and filtering. We also support partial select.
 ```typescript
 ...
 import { pgTable, serial, text, varchar } from 'drizzle-orm/pg-core';
-import { drizzle } from 'drizzle-orm/node-pg';;
+import { drizzle } from 'drizzle-orm/node-postgres';;
 import { and, asc, desc, eq, or } from 'drizzle-orm/expressions';
 
 const users = pgTable('users', {
@@ -414,7 +414,7 @@ or(expressions: SQL[])
 
 ```typescript
 import { pgTable, serial, text, timestamp, InferModel } from 'drizzle-orm/pg-core';
-import { drizzle } from 'drizzle-orm/node-pg';;
+import { drizzle } from 'drizzle-orm/node-postgres';;
 
 const users = pgTable('users', {
   id: serial('id').primaryKey(),
@@ -690,8 +690,8 @@ CREATE INDEX IF NOT EXISTS users_full_name_index ON users (full_name);
 And you can run migrations manually or using our embedded migrations module
 
 ```typescript
-import { drizzle } from 'drizzle-orm/node-pg';;
-import { migrate } from 'drizzle-orm/node-pg/migrator';
+import { drizzle } from 'drizzle-orm/node-postgres';;
+import { migrate } from 'drizzle-orm/node-postgres/migrator';
 import { Pool } from 'pg';
 
 const pool = new Pool({

drizzle-orm/tests/mysql/dan/insert.ts

@@ -1,5 +1,5 @@
 import { Equal, Expect } from 'tests/utils';
-import { InferModel, MySqlQueryResult, MySqlRawQueryResult } from '~/mysql-core/index';
+import { InferModel, MySqlQueryResult, MySqlRawQueryResult } from '~/mysql-core';
 import { sql } from '~/sql';
 import { db } from './db';
 import { users } from './tables';