Merge branch 'beta' into beta

drizzle-orm/src/mysql-core/db.ts

@@ -76,6 +76,38 @@ export class MySqlDatabase<
 		}
 	}
 
+	/**
+	 * Creates a subquery that defines a temporary named result set as a CTE.
+	 * 
+	 * It is useful for breaking down complex queries into simpler parts and for reusing the result set in subsequent parts of the query.
+	 * 
+	 * See docs: {@link https://orm.drizzle.team/docs/select#with-clause}
+	 * 
+	 * @param alias The alias for the subquery.
+	 * 
+	 * Failure to provide an alias will result in a DrizzleTypeError, preventing the subquery from being referenced in other queries.
+	 * 
+	 * @example
+	 * 
+	 * ```ts
+	 * // Create a subquery with alias 'sq' and use it in the select query
+	 * const sq = db.$with('sq').as(db.select().from(users).where(eq(users.id, 42)));
+	 * 
+	 * const result = await db.with(sq).select().from(sq);
+	 * ```
+	 * 
+	 * To select arbitrary SQL values as fields in a CTE and reference them in other CTEs or in the main query, you need to add aliases to them:
+	 * 
+	 * ```ts
+	 * // Select an arbitrary SQL value as a field in a CTE and reference it in the main query
+	 * const sq = db.$with('sq').as(db.select({
+	 *   name: sql<string>`upper(${users.name})`.as('name'),
+	 * })
+	 * .from(users));
+	 * 
+	 * const result = await db.with(sq).select({ name: sq.name }).from(sq);
+	 * ```
+	 */
 	$with<TAlias extends string>(alias: TAlias) {
 		return {
 			as<TSelection extends ColumnsSelection>(
@@ -93,6 +125,25 @@ export class MySqlDatabase<
 		};
 	}
 
+	/**
+	 * Incorporates a previously defined CTE (using `$with`) into the main query.
+	 * 
+	 * This method allows the main query to reference a temporary named result set.
+	 * 
+	 * See docs: {@link https://orm.drizzle.team/docs/select#with-clause}
+	 * 
+	 * @param queries The CTEs to incorporate into the main query.
+	 * 
+	 * @example
+	 * 
+	 * ```ts
+	 * // Define a subquery 'sq' as a CTE using $with
+	 * const sq = db.$with('sq').as(db.select().from(users).where(eq(users.id, 42)));
+	 * 
+	 * // Incorporate the CTE 'sq' into the main query and select from it
+	 * const result = await db.with(sq).select().from(sq);
+	 * ```
+	 */
 	with(...queries: WithSubquery[]) {
 		const self = this;
 
@@ -128,12 +179,72 @@ export class MySqlDatabase<
 		return { select, selectDistinct };
 	}
 
+	/**
+	 * Creates a select query.
+	 * 
+	 * Calling this method with no arguments will select all columns from the table. Pass a selection object to specify the columns you want to select.
+	 * 
+	 * Use `.from()` method to specify which table to select from.
+	 * 
+	 * See docs: {@link https://orm.drizzle.team/docs/select}
+	 * 
+	 * @param fields The selection object.
+	 * 
+	 * @example
+	 * 
+	 * ```ts
+	 * // Select all columns and all rows from the 'cars' table
+	 * const allCars: Car[] = await db.select().from(cars);
+	 * 
+	 * // Select specific columns and all rows from the 'cars' table
+	 * const carsIdsAndBrands: { id: number; brand: string }[] = await db.select({ 
+	 *   id: cars.id, 
+	 *   brand: cars.brand 
+	 * })
+	 *   .from(cars);
+	 * ```
+	 * 
+	 * Like in SQL, you can use arbitrary expressions as selection fields, not just table columns:
+	 * 
+	 * ```ts
+	 * // Select specific columns along with expression and all rows from the 'cars' table
+	 * const carsIdsAndLowerNames: { id: number; lowerBrand: string }[] = await db.select({
+	 *   id: cars.id,
+	 *   lowerBrand: sql<string>`lower(${cars.brand})`,
+	 * })
+	 *   .from(cars);
+	 * ```
+	 */
 	select(): MySqlSelectBuilder<undefined, TPreparedQueryHKT>;
 	select<TSelection extends SelectedFields>(fields: TSelection): MySqlSelectBuilder<TSelection, TPreparedQueryHKT>;
 	select(fields?: SelectedFields): MySqlSelectBuilder<SelectedFields | undefined, TPreparedQueryHKT> {
 		return new MySqlSelectBuilder({ fields: fields ?? undefined, session: this.session, dialect: this.dialect });
 	}
 
+	/**
+	 * Adds `distinct` expression to the select query.
+	 * 
+	 * Calling this method will return only unique values. When multiple columns are selected, it returns rows with unique combinations of values in these columns.
+	 * 
+	 * Use `.from()` method to specify which table to select from.
+	 * 
+	 * See docs: {@link https://orm.drizzle.team/docs/select#distinct}
+	 * 
+	 * @param fields The selection object.
+	 * 
+	 * @example
+	 * ```ts
+	 * // Select all unique rows from the 'cars' table
+	 * await db.selectDistinct()
+	 *   .from(cars)
+	 *   .orderBy(cars.id, cars.brand, cars.color);
+	 * 
+	 * // Select all unique brands from the 'cars' table
+	 * await db.selectDistinct({ brand: cars.brand })
+	 *   .from(cars)
+	 *   .orderBy(cars.brand);
+	 * ```
+	 */
 	selectDistinct(): MySqlSelectBuilder<undefined, TPreparedQueryHKT>;
 	selectDistinct<TSelection extends SelectedFields>(
 		fields: TSelection,
@@ -147,14 +258,73 @@ export class MySqlDatabase<
 		});
 	}
 
+	/**
+	 * Creates an update query.
+	 * 
+	 * Calling this method without `.where()` clause will update all rows in a table. The `.where()` clause specifies which rows should be updated.
+	 * 
+	 * Use `.set()` method to specify which values to update.
+	 * 
+	 * See docs: {@link https://orm.drizzle.team/docs/update} 
+	 * 
+	 * @param table The table to update.
+	 * 
+	 * @example
+	 * 
+	 * ```ts
+	 * // Update all rows in the 'cars' table
+	 * await db.update(cars).set({ color: 'red' });
+	 * 
+	 * // Update rows with filters and conditions
+	 * await db.update(cars).set({ color: 'red' }).where(eq(cars.brand, 'BMW'));
+	 * ```
+	 */
 	update<TTable extends MySqlTable>(table: TTable): MySqlUpdateBuilder<TTable, TQueryResult, TPreparedQueryHKT> {
 		return new MySqlUpdateBuilder(table, this.session, this.dialect);
 	}
 
+	/**
+	 * Creates an insert query.
+	 * 
+	 * Calling this method will create new rows in a table. Use `.values()` method to specify which values to insert.
+	 * 
+	 * See docs: {@link https://orm.drizzle.team/docs/insert} 
+	 * 
+	 * @param table The table to insert into.
+	 * 
+	 * @example
+	 * 
+	 * ```ts
+	 * // Insert one row
+	 * await db.insert(cars).values({ brand: 'BMW' });
+	 * 
+	 * // Insert multiple rows
+	 * await db.insert(cars).values([{ brand: 'BMW' }, { brand: 'Porsche' }]);
+	 * ```
+	 */
 	insert<TTable extends MySqlTable>(table: TTable): MySqlInsertBuilder<TTable, TQueryResult, TPreparedQueryHKT> {
 		return new MySqlInsertBuilder(table, this.session, this.dialect);
 	}
 
+	/**
+	 * Creates a delete query.
+	 * 
+	 * Calling this method without `.where()` clause will delete all rows in a table. The `.where()` clause specifies which rows should be deleted. 
+	 * 
+	 * See docs: {@link https://orm.drizzle.team/docs/delete}
+	 *  
+	 * @param table The table to delete from.
+	 * 
+	 * @example
+	 * 
+	 * ```ts
+	 * // Delete all rows in the 'cars' table
+	 * await db.delete(cars);
+	 * 
+	 * // Delete rows with filters and conditions
+	 * await db.delete(cars).where(eq(cars.color, 'green'));
+	 * ```
+	 */
 	delete<TTable extends MySqlTable>(table: TTable): MySqlDeleteBase<TTable, TQueryResult, TPreparedQueryHKT> {
 		return new MySqlDeleteBase(table, this.session, this.dialect);
 	}

drizzle-orm/src/mysql-core/query-builders/delete.ts

@@ -97,6 +97,35 @@ export class MySqlDeleteBase<
 		this.config = { table };
 	}
 
+	/** 
+	 * Adds a `where` clause to the query.
+	 * 
+	 * Calling this method will delete only those rows that fulfill a specified condition.
+	 * 
+	 * See docs: {@link https://orm.drizzle.team/docs/delete}
+	 * 
+	 * @param where the `where` clause.
+	 * 
+	 * @example
+	 * You can use conditional operators and `sql function` to filter the rows to be deleted.
+	 * 
+	 * ```ts
+	 * // Delete all cars with green color
+	 * db.delete(cars).where(eq(cars.color, 'green'));
+	 * // or
+	 * db.delete(cars).where(sql`${cars.color} = 'green'`)
+	 * ```
+	 * 
+	 * You can logically combine conditional operators with `and()` and `or()` operators:
+	 * 
+	 * ```ts
+	 * // Delete all BMW cars with a green color
+	 * db.delete(cars).where(and(eq(cars.color, 'green'), eq(cars.brand, 'BMW')));
+	 * 
+	 * // Delete all cars with the green or blue color
+	 * db.delete(cars).where(or(eq(cars.color, 'green'), eq(cars.color, 'blue')));
+	 * ```
+	*/
 	where(where: SQL | undefined): MySqlDeleteWithout<this, TDynamic, 'where'> {
 		this.config.where = where;
 		return this as any;

drizzle-orm/src/mysql-core/query-builders/insert.ts

@@ -158,6 +158,32 @@ export class MySqlInsertBase<
 		this.config = { table, values, ignore };
 	}
 
+	/**
+	 * Adds an `on duplicate key update` clause to the query.
+	 * 
+	 * Calling this method will update update the row if any unique index conflicts. MySQL will automatically determine the conflict target based on the primary key and unique indexes.
+	 * 
+	 * See docs: {@link https://orm.drizzle.team/docs/insert#on-duplicate-key-update}
+	 * 
+	 * @param config The `set` clause
+	 * 
+	 * @example
+	 * ```ts
+	 * await db.insert(cars)
+	 *   .values({ id: 1, brand: 'BMW'})
+	 *   .onDuplicateKeyUpdate({ set: { brand: 'Porsche' }});
+	 * ```
+	 * 
+	 * While MySQL does not directly support doing nothing on conflict, you can perform a no-op by setting any column's value to itself and achieve the same effect:
+	 * 
+	 * ```ts
+	 * import { sql } from 'drizzle-orm';
+	 * 
+	 * await db.insert(cars)
+	 *   .values({ id: 1, brand: 'BMW' })
+	 *   .onDuplicateKeyUpdate({ set: { id: sql`id` } });
+	 * ```
+	 */
 	onDuplicateKeyUpdate(
 		config: MySqlInsertOnDuplicateKeyUpdateConfig<this>,
 	): MySqlInsertWithout<this, TDynamic, 'onDuplicateKeyUpdate'> {