Skip to content

Commit 2bc34eb

Browse files
github-actions[bot]github-actions[bot]
committed
docs: sync from coderbuzz/codex@643d093
1 parent 0376ea6 commit 2bc34eb

2 files changed

Lines changed: 16 additions & 122 deletions

File tree

‎AI_KNOWLEDGE.md‎

Lines changed: 10 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- docs: sync from coderbuzz/codex@60ca8c4 -->
1+
<!-- docs: sync from coderbuzz/codex@643d093 -->
22

33
# @coderbuzz/sql: AI Expert Knowledge Reference
44

@@ -13,7 +13,7 @@ package. Treat every rule here as authoritative.
1313
## 1. Mental Model
1414

1515
```
16-
Dialect Namespace (sqlite / pg / mysql / mssql / ch / oracle / snowflake / databricks)
16+
Dialect Namespace (sqlite / pg / mysql / mssql / ch)
1717
├── connect(config) → Engine instance (extends Sql<T>)
1818
├── table(name, schema) → SqlTable<S>
1919
├── column factories (integer, text, serial, uuid, ...)
@@ -50,9 +50,6 @@ import { pg as pgBun } from "@coderbuzz/sql/postgres-bun"; // driver: Bun built-
5050
import { mysql } from "@coderbuzz/sql/mysql";
5151
import { mssql } from "@coderbuzz/sql/mssql";
5252
import { ch } from "@coderbuzz/sql/clickhouse";
53-
import { oracle } from "@coderbuzz/sql/oracle";
54-
import { snowflake } from "@coderbuzz/sql/snowflake";
55-
import { databricks } from "@coderbuzz/sql/databricks";
5653
```
5754

5855
### 2.2 Root package: shared helpers and types
@@ -145,9 +142,6 @@ import * as sqliteTypes from "@coderbuzz/sql/sqlite-types";
145142
import * as clickhouseTypes from "@coderbuzz/sql/clickhouse-types";
146143
import * as mysqlTypes from "@coderbuzz/sql/mysql-types";
147144
import * as mssqlTypes from "@coderbuzz/sql/mssql-types";
148-
import * as oracleTypes from "@coderbuzz/sql/oracle-types";
149-
import * as snowflakeTypes from "@coderbuzz/sql/snowflake-types";
150-
import * as databricksTypes from "@coderbuzz/sql/databricks-types";
151145
```
152146

153147
---
@@ -220,32 +214,6 @@ const db = ch.connect({
220214
username: "default",
221215
password: "",
222216
});
223-
224-
// Oracle
225-
const db = oracle.connect({
226-
user: "app",
227-
password: "secret",
228-
connectString: "localhost/XEPDB1",
229-
poolMax: 10,
230-
});
231-
232-
// Snowflake
233-
const db = snowflake.connect({
234-
account: "my-account",
235-
username: "APP_USER",
236-
password: "secret",
237-
database: "APP_DB",
238-
schema: "PUBLIC",
239-
warehouse: "COMPUTE_WH",
240-
role: "APP_ROLE",
241-
});
242-
243-
// Databricks
244-
const db = databricks.connect({
245-
host: "adb-xxxx.azuredatabricks.net",
246-
path: "/sql/1.0/warehouses/xxxx",
247-
token: "dapi...",
248-
});
249217
```
250218

251219
---
@@ -663,9 +631,6 @@ await events.insert(db)
663631
| SQLite | ✓ | ✓ |
664632
| MySQL | ✗ (throws) | ✗ (throws) |
665633
| MSSQL | ✗ (throws) | ✗ (throws) |
666-
| Oracle | ✗ (throws) | ✗ (throws) |
667-
| Snowflake | ✗ (throws) | ✗ (throws) |
668-
| Databricks | ✗ (throws) | ✗ (throws) |
669634
| ClickHouse | ✗ (throws) | ✗ (throws) |
670635

671636
---
@@ -779,7 +744,6 @@ Placeholder styles per dialect:
779744
| PostgreSQL | `$N` | `... WHERE id = $1` |
780745
| MySQL | `?` | `... WHERE id = ?` |
781746
| MSSQL | `@pN` | `... WHERE id = @p1` |
782-
| Oracle | `:N` | `... WHERE id = :1` |
783747
| Others | `?` | `... WHERE id = ?` |
784748

785749
---
@@ -836,7 +800,7 @@ tx.select("last_no").from("nomor_faktur").where({ seri: "A" }).forUpdate()
836800
// .forShare(), .forUpdate({ noWait: true }), .forUpdate({ skipLocked: true })
837801
```
838802

839-
PostgreSQL / MySQL / Oracle only. SQLite, MSSQL and ClickHouse throw.
803+
PostgreSQL / MySQL only. SQLite, MSSQL and ClickHouse throw.
840804

841805
### Errors
842806

@@ -964,49 +928,20 @@ ch.boolean() ch.date() ch.date32() ch.datetime() ch.datetime64(precision)
964928
ch.uuid() ch.ipv4() ch.ipv6() ch.lowCardinality(type)
965929
```
966930

967-
### Oracle
968-
969-
ANSI types plus:
970-
971-
```ts
972-
oracle.number(p?, s?) oracle.varchar2(n) oracle.clob()
973-
oracle.blob() oracle.date() oracle.timestamp_tz(precision)
974-
// Note: oracle.date() is exported as `oracleDate` from the namespace
975-
// to avoid collision with ANSI `date`
976-
```
977-
978-
### Snowflake
979-
980-
ANSI types plus:
981-
982-
```ts
983-
snowflake.variant<T>() snowflake.timestamp_ntz(precision)
984-
snowflake.timestamp_ltz(precision) snowflake.array_type<T>()
985-
snowflake.object_type<T>()
986-
```
987-
988-
### Databricks
989-
990-
```ts
991-
databricks.string() databricks.long() databricks.double()
992-
databricks.struct<T>(fields) databricks.map_type<K, V>() databricks.array_type<T>()
993-
```
994-
995931
---
996932

997933
## 19. Dialect-Specific Behaviors
998934

999935
| Behavior | Details |
1000936
| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
1001-
| **Identifier quoting** | `"id"` (PG, SQLite, Oracle, Snowflake) · `` `id` `` (MySQL, CH, Databricks) · `[id]` (MSSQL) |
1002-
| **Placeholders** | `?` (SQLite/MySQL/CH/Snowflake/Databricks) · `$N` (PG) · `@pN` (MSSQL) · `:N` (Oracle) |
937+
| **Identifier quoting** | `"id"` (PG, SQLite) · `` `id` `` (MySQL, CH) · `[id]` (MSSQL) |
938+
| **Placeholders** | `?` (SQLite/MySQL/CH) · `$N` (PG) · `@pN` (MSSQL) |
1003939
| **RETURNING** | PostgreSQL + SQLite only. Others throw `"RETURNING is not supported by this dialect"` |
1004940
| **FULL OUTER JOIN** | PostgreSQL + ANSI only. SQLite/MySQL/ClickHouse throw at compile time |
1005941
| **ClickHouse params** | Values inlined into SQL (HTTP API has no native binding). Safe via `escapeClickHouseValue()` |
1006942
| **ClickHouse CREATE INDEX** | Not emitted. Indexes are defined via the ENGINE / ORDER BY clause |
1007943
| **ClickHouse UNIQUE** | Not supported. Throws if `.unique()` is used in a ClickHouse table |
1008944
| **MSSQL LIMIT** | Renders as `OFFSET n ROWS FETCH NEXT m ROWS ONLY`. Injects `ORDER BY (SELECT NULL)` when no ORDER BY exists |
1009-
| **Oracle LIMIT** | Same `OFFSET/FETCH` syntax as MSSQL |
1010945
| **MySQL SERIAL** | `SERIAL` primary key becomes `INT AUTO_INCREMENT` in DDL |
1011946
| **SQLite WAL** | `PRAGMA journal_mode = WAL` applied automatically for file-based DB |
1012947
| **SQLite streaming** | Uses `bun:sqlite` synchronous `stmt.iterate()` |
@@ -1083,7 +1018,7 @@ result.statistics?.read_rows; // optional stats
10831018

10841019
| Error message | When it occurs |
10851020
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
1086-
| `"RETURNING is not supported by this dialect"` | `.returning()` called on MySQL/MSSQL/Oracle/Snowflake/Databricks/ClickHouse and `.toSQL()` called |
1021+
| `"RETURNING is not supported by this dialect"` | `.returning()` called on MySQL/MSSQL/ClickHouse and `.toSQL()` called |
10871022
| `"SQLite does not support FULL OUTER JOIN"` | `.full_join()` used with SQLite compiler |
10881023
| `"MySQL does not support FULL OUTER JOIN"` | `.full_join()` used with MySQL compiler |
10891024
| `"ClickHouse does not support FULL OUTER JOIN"` | `.full_join()` used with ClickHouse compiler |
@@ -1107,11 +1042,10 @@ const rows = await db.execute(`SELECT * FROM users WHERE name = '${name}'`);
11071042
const rows = await db.sql`SELECT * FROM users WHERE name = ${name}`.execute();
11081043
```
11091044

1110-
**DO NOT** call `.stream()` or `.prepare()` on MySQL, MSSQL, Oracle, Snowflake,
1111-
Databricks, or ClickHouse engines: they throw.
1045+
**DO NOT** call `.stream()` or `.prepare()` on MySQL, MSSQL, or ClickHouse
1046+
engines: they throw.
11121047

1113-
**DO NOT** use `.returning()` on MySQL, MSSQL, Oracle, Snowflake, Databricks, or
1114-
ClickHouse: throws `"RETURNING is not supported by this dialect"`.
1048+
**DO NOT** use `.returning()` on MySQL, MSSQL, or ClickHouse: throws `"RETURNING is not supported by this dialect"`.
11151049

11161050
**DO NOT** use `.full_join()` with SQLite, MySQL, or ClickHouse: throws at
11171051
compile time.
@@ -1533,7 +1467,7 @@ Package: @coderbuzz/sql
15331467
Version: 0.1.3
15341468
License: MIT
15351469
Type: ESM only (type: "module")
1536-
Peer deps (all optional): pg, mysql2, mssql, better-sqlite3, @db/sqlite, oracledb, snowflake-sdk, @databricks/sql
1470+
Peer deps (all optional): pg, mysql2, mssql, better-sqlite3, @db/sqlite
15371471
Runtime dep: @coderbuzz/veta (internal, schema coercion)
15381472
```
15391473
@@ -1549,15 +1483,9 @@ Runtime dep: @coderbuzz/veta (internal, schema coercion)
15491483
| `@coderbuzz/sql/mysql` | `mysql` namespace + `MySQLEngine` |
15501484
| `@coderbuzz/sql/mssql` | `mssql` namespace + `MSSQLEngine` |
15511485
| `@coderbuzz/sql/clickhouse` | `ch` namespace + `ClickHouseEngine` |
1552-
| `@coderbuzz/sql/oracle` | `oracle` namespace + `OracleEngine` |
1553-
| `@coderbuzz/sql/snowflake` | `snowflake` + `SnowflakeEngine` |
1554-
| `@coderbuzz/sql/databricks` | `databricks` + `DatabricksEngine` |
15551486
| `@coderbuzz/sql/sqlite-types` | SQLite column factories only |
15561487
| `@coderbuzz/sql/postgres-types` | PostgreSQL column factories only |
15571488
| `@coderbuzz/sql/mysql-types` | MySQL column factories only |
15581489
| `@coderbuzz/sql/mssql-types` | MSSQL column factories only |
15591490
| `@coderbuzz/sql/clickhouse-types` | ClickHouse column factories only |
1560-
| `@coderbuzz/sql/oracle-types` | Oracle column factories only |
1561-
| `@coderbuzz/sql/snowflake-types` | Snowflake column factories only |
1562-
| `@coderbuzz/sql/databricks-types` | Databricks column factories only |
15631491
| `@coderbuzz/sql/ansi` | ANSI column factories only |

‎README.md‎

Lines changed: 6 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- docs: sync from coderbuzz/codex@60ca8c4 -->
1+
<!-- docs: sync from coderbuzz/codex@643d093 -->
22

33
# @coderbuzz/sql
44

@@ -24,7 +24,7 @@ This is not an ORM. There are no lazy-loaded relations, no magical `save()` meth
2424
| Pain Point | Drizzle ORM | Kysely | Prisma | **@coderbuzz/sql** |
2525
|---|---|---|---|---|
2626
| Runtime agnostic | Bun, Node, Deno | Bun, Node, Deno | Node only | **Bun, Node, Deno** |
27-
| Dialects supported | 5 (SQLite, PG, MySQL, PG, SQLite) | 6 | 5 (with connectors) | **8**: SQLite, PG, MySQL, MSSQL, ClickHouse, Oracle, Snowflake, Databricks |
27+
| Dialects supported | 5 (SQLite, PG, MySQL, PG, SQLite) | 6 | 5 (with connectors) | **5**: SQLite, PG, MySQL, MSSQL, ClickHouse |
2828
| Query builder vs ORM | Hybrid (ORM-like) | Query builder | ORM (magic) | **Query builder**: full SQL control |
2929
| Learning curve | Steady (ORM conventions) | Low (SQL-like) | Steep (Prisma schema, CLI) | **Low**: you already know SQL |
3030
| Migration tools | Drizzle Kit (CLI) | Manual | Prisma Migrate (CLI) | **Built-in**: `introspect()` + `diff()` + `applyDiff()` |
@@ -42,7 +42,7 @@ This is not an ORM. There are no lazy-loaded relations, no magical `save()` meth
4242

4343
- **You want type safety** without an ORM's magic
4444
- **You need multi-dialect support**: one codebase for SQLite dev and PostgreSQL prod
45-
- **You need ClickHouse, Snowflake, or Databricks support**: Drizzle and Kysely don't cover these
45+
- **You need ClickHouse support**: Drizzle and Kysely don't cover it
4646
- **You want full control** over SQL output: every query is inspectable via `.toSQL()`
4747
- **You need high-throughput batch inserts**: debounce, timeout, and backpressure built in
4848
- **You want schema migrations** without a CLI: introspect live DBs, diff against schemas, generate ALTER TABLE
@@ -51,7 +51,7 @@ This is not an ORM. There are no lazy-loaded relations, no magical `save()` meth
5151

5252
## Features
5353

54-
- **8 databases**: SQLite, PostgreSQL, MySQL/MariaDB, SQL Server, ClickHouse, Oracle, Snowflake, Databricks/Spark SQL
54+
- **5 databases**: SQLite, PostgreSQL, MySQL/MariaDB, SQL Server, ClickHouse
5555
- **Schema-driven table definitions**: define columns once for DDL + typed queries
5656
- **Fluent query builders**: SELECT, INSERT, UPDATE, DELETE with full type inference
5757
- **Safe raw SQL**: `db.sql\`...\`` tagged templates with dialect-aware placeholders
@@ -102,9 +102,6 @@ bun add pg # PostgreSQL
102102
bun add mysql2 # MySQL / MariaDB
103103
bun add mssql # SQL Server
104104
bun add better-sqlite3 # SQLite (Node.js)
105-
bun add oracledb # Oracle
106-
bun add snowflake-sdk # Snowflake
107-
bun add @databricks/sql # Databricks
108105
```
109106

110107
SQLite on Bun uses `bun:sqlite` (built-in, no driver needed).
@@ -124,9 +121,6 @@ which uses Bun's built-in SQL client.
124121
| MySQL / MariaDB | `@coderbuzz/sql/mysql` | `mysql` | `mysql2` |
125122
| SQL Server | `@coderbuzz/sql/mssql` | `mssql` | `mssql` |
126123
| ClickHouse | `@coderbuzz/sql/clickhouse` | `ch` | Native `fetch` HTTP |
127-
| Oracle | `@coderbuzz/sql/oracle` | `oracle` | `oracledb` |
128-
| Snowflake | `@coderbuzz/sql/snowflake` | `snowflake` | `snowflake-sdk` |
129-
| Databricks / Spark SQL | `@coderbuzz/sql/databricks` | `databricks` | `@databricks/sql` |
130124

131125
---
132126

@@ -981,48 +975,20 @@ const db = mssql.connect({ server: "localhost", port: 1433, database: "app", use
981975
const db = ch.connect({ url: "http://localhost:8123", database: "default", username: "default", password: "" });
982976
```
983977

984-
### Oracle
985-
986-
```ts
987-
const db = oracle.connect({
988-
user: "app", password: "secret",
989-
connectString: "localhost/XEPDB1", poolMax: 10,
990-
});
991-
```
992-
993-
### Snowflake
994-
995-
```ts
996-
const db = snowflake.connect({
997-
account: "my-account", username: "APP_USER", password: "secret",
998-
database: "APP_DB", schema: "PUBLIC", warehouse: "COMPUTE_WH", role: "APP_ROLE",
999-
});
1000-
```
1001-
1002-
### Databricks
1003-
1004-
```ts
1005-
const db = databricks.connect({
1006-
host: "adb-xxxx.azuredatabricks.net",
1007-
path: "/sql/1.0/warehouses/xxxx",
1008-
token: "dapi...",
1009-
});
1010-
```
1011-
1012978
---
1013979

1014980
## Dialect Behavior Notes
1015981

1016982
| Feature | Notes |
1017983
|---|---|
1018-
| Placeholders | `?` (SQLite/MySQL/ClickHouse), `$N` (PostgreSQL), `@pN` (MSSQL), `:N` (Oracle) |
984+
| Placeholders | `?` (SQLite/MySQL/ClickHouse), `$N` (PostgreSQL), `@pN` (MSSQL) |
1019985
| `RETURNING` | PostgreSQL and SQLite only |
1020986
| Full outer join | Not supported by SQLite, MySQL, or ClickHouse |
1021987
| ClickHouse params | Escaped and inlined into SQL (no native binding) |
1022988
| ClickHouse indexes | Part of ENGINE definition |
1023989
| MSSQL limit without order | Injects `ORDER BY (SELECT NULL)` automatically |
1024990
| SQLite WAL mode | Enabled automatically for file-based DBs |
1025-
| Identifier quoting | `"quotes"` (PG, SQLite, Oracle, Snowflake), backticks (MySQL, ClickHouse, Databricks), `[brackets]` (MSSQL) |
991+
| Identifier quoting | `"quotes"` (PG, SQLite), backticks (MySQL, ClickHouse), `[brackets]` (MSSQL) |
1026992

1027993
---
1028994

0 commit comments

Comments
 (0)