flint-orm 0.7.2 → 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KavenLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # Flint ORM
 
-A type-safe SQLite ORM for JavaScript. One schema, any driver.
+Type-safe SQLite ORM for JavaScript
 
 ## Features
 

package/dist/entries/table.d.ts

@@ -1,4 +1,4 @@
 export { text, integer, boolean, json, date, real } from '../schema/columns';
 export type { ColumnDef, IntegerColumnDef, DateColumnDef, DateColumnDefWithDefault, ForeignKeyAction } from '../schema/columns';
-export { table, index, snakeCase } from '../schema/table';
-export type { InferRow, InsertRow, TableDef, AnyTable, IndexDef, IndexBuilder } from '../schema/table';
+export { table, index, primaryKey, snakeCase } from '../schema/table';
+export type { InferRow, InsertRow, TableDef, AnyTable, IndexDef, IndexBuilder, PrimaryKeyBuilder, PrimaryKeyDef } from '../schema/table';

package/dist/index.d.ts

@@ -3,8 +3,8 @@ export type { SQLExpression, Executable, SelectBuilder, InsertStage1, UpdateStag
 export type { Executor } from './executor';
 export { text, integer, boolean, json, date, real } from './schema/columns';
 export type { ColumnDef, IntegerColumnDef, DateColumnDef, DateColumnDefWithDefault } from './schema/columns';
-export { table, index, snakeCase } from './schema/table';
-export type { InferRow, InsertRow, TableDef, AnyTable, IndexDef, IndexBuilder } from './schema/table';
+export { table, index, primaryKey, snakeCase } from './schema/table';
+export type { InferRow, InsertRow, TableDef, AnyTable, IndexDef, IndexBuilder, PrimaryKeyBuilder, PrimaryKeyDef } from './schema/table';
 export { eq, and, or, gt, gte, lt, lte, neq, isIn, isNotIn, isNull, isNotNull, like, glob, between } from './query/conditions';
 export type { Condition } from './query/conditions';
 export { count, countColumn, sum, avg, min, max } from './query/aggregates';

package/dist/migration/types.d.ts

@@ -18,6 +18,7 @@ export interface SerializedTable {
     name: string;
     columns: SerializedColumn[];
     indexes: SerializedIndex[];
+    primaryKeyColumns?: string[];
 }
 /** Serialized index definition. */
 export interface SerializedIndex {

package/dist/schema/table.d.ts

@@ -5,7 +5,7 @@ export type TableDef<T> = T & {
         readonly name: string;
     };
 };
-export declare function table<T extends Record<string, ColumnDef<any, any>>>(name: string, columns: T, indexFn?: (t: TableDef<T>) => IndexBuilder[]): TableDef<T>;
+export declare function table<T extends Record<string, ColumnDef<any, any>>>(name: string, columns: T, indexFn?: (t: TableDef<T>) => (IndexBuilder | PrimaryKeyBuilder)[]): TableDef<T>;
 /**
  * Derive the row shape from a table's column definitions.
  * DateColumnDef → Date | null (nullable unless defaultNow() was called)
@@ -37,7 +37,7 @@ export type InsertRow<T extends TableDef<any>> = {
  *   firstName: text(),
  * });
  */
-export declare function snakeCaseTable<T extends Record<string, ColumnDef<any, any>>>(tableName: string, columns: T, indexFn?: (t: TableDef<T>) => IndexBuilder[]): TableDef<T>;
+export declare function snakeCaseTable<T extends Record<string, ColumnDef<any, any>>>(tableName: string, columns: T, indexFn?: (t: TableDef<T>) => (IndexBuilder | PrimaryKeyBuilder)[]): TableDef<T>;
 /** Provides `snakeCase.table()` for auto snake_case column naming. */
 export declare const snakeCase: {
     table: typeof snakeCaseTable;
@@ -55,6 +55,30 @@ export interface IndexBuilder {
     /** Mark the index as unique. */
     unique(): IndexBuilder;
 }
+/** A composite primary key definition — used internally by the migration system. */
+export interface PrimaryKeyDef {
+    columns: string[];
+}
+/** Public builder returned by `primaryKey()` — chain `.on(columns)`. */
+export interface PrimaryKeyBuilder {
+    /** Add one or more columns to the composite primary key. */
+    on(...columns: ColumnDef<any, any>[]): PrimaryKeyBuilder;
+}
+/**
+ * Create a composite primary key definition using a chainable API.
+ *
+ * @param name - Optional name (reserved for future use, currently unused in SQL)
+ * @returns A PrimaryKeyBuilder — chain `.on(columns)`
+ *
+ * @example
+ * const userRoles = table("user_roles", {
+ *   userId: text("user_id"),
+ *   roleId: text("role_id"),
+ * }, (t) => [
+ *   primaryKey().on(t.userId, t.roleId),
+ * ]);
+ */
+export declare function primaryKey(): PrimaryKeyBuilderInternal;
 /**
  * Create an index definition using a chainable API.
  *

package/dist/src/cli.js

@@ -326,6 +326,11 @@ function diffTable(tableName, prev, curr) {
   if (unsafe) {
     return [rebuildTable(tableName, prev, curr)];
   }
+  const prevPK = prev.primaryKeyColumns ?? [];
+  const currPK = curr.primaryKeyColumns ?? [];
+  if (JSON.stringify(prevPK) !== JSON.stringify(currPK)) {
+    return [rebuildTable(tableName, prev, curr)];
+  }
   const ops = [...columnOps];
   const prevIndexes = new Map(prev.indexes.map((i2) => [i2.name, i2]));
   const currIndexes = new Map(curr.indexes.map((i2) => [i2.name, i2]));
@@ -572,7 +577,17 @@ function serializeTable(table) {
       });
     }
   }
-  return { name: tableName, columns, indexes };
+  let primaryKeyColumns;
+  if (tableObj.__primaryKey) {
+    const pkDef = tableObj.__primaryKey;
+    primaryKeyColumns = pkDef.columns;
+    for (const col of columns) {
+      if (col.isPrimaryKey) {
+        throw new Error(`Column "${col.name}" has primaryKey() but table "${tableName}" also defines a composite primaryKey(). Use one or the other.`);
+      }
+    }
+  }
+  return { name: tableName, columns, indexes, primaryKeyColumns };
 }
 function serializeSchema(tables) {
   const tableMap = {};
@@ -595,9 +610,9 @@ __export(exports_sql, {
 function sqlType(col) {
   return col.sqlType.toUpperCase();
 }
-function columnToDDL(col) {
+function columnToDDL(col, isCompositePK = false) {
   const parts = [col.name, sqlType(col)];
-  if (col.isPrimaryKey)
+  if (col.isPrimaryKey && !isCompositePK)
     parts.push("PRIMARY KEY");
   if (col.isAutoIncrement === true)
     parts.push("AUTOINCREMENT");
@@ -644,7 +659,12 @@ function rebuildTableToSQL(op) {
   const tempName = `_flint_rebuild_${tableName}`;
   const stmts = [];
   stmts.push("PRAGMA defer_foreign_keys = 1");
-  const cols = newTable.columns.map(columnToDDL).join(`,
+  const isComposite = newTable.primaryKeyColumns && newTable.primaryKeyColumns.length > 0;
+  const colDefs = newTable.columns.map((c3) => columnToDDL(c3, isComposite));
+  if (isComposite) {
+    colDefs.push(`PRIMARY KEY(${newTable.primaryKeyColumns.join(", ")})`);
+  }
+  const cols = colDefs.join(`,
   `);
   stmts.push(`CREATE TABLE ${tempName} (
   ${cols}
@@ -671,7 +691,12 @@ function rebuildTableToSQL(op) {
 function operationToSQL(op) {
   switch (op.type) {
     case "addTable": {
-      const cols = op.table.columns.map(columnToDDL).join(`,
+      const isComposite = op.table.primaryKeyColumns && op.table.primaryKeyColumns.length > 0;
+      const colDefs = op.table.columns.map((c3) => columnToDDL(c3, isComposite));
+      if (isComposite) {
+        colDefs.push(`PRIMARY KEY(${op.table.primaryKeyColumns.join(", ")})`);
+      }
+      const cols = colDefs.join(`,
   `);
       const stmts = [`CREATE TABLE ${op.table.name} (
   ${cols}
@@ -1315,12 +1340,16 @@ function decodeSelectedRow(raw, tbl, keys) {
   }
   return out;
 }
-function findPKKey(tbl) {
+function findPKKeys(tbl) {
+  const keys = [];
   for (const [key, col] of columnEntries(tbl)) {
     if (col.__internal.isPrimaryKey)
-      return key;
+      keys.push(key);
+  }
+  if (keys.length === 0) {
+    throw new FlintValidationError("Table has no primary key column");
   }
-  throw new FlintValidationError("Table has no primary key column");
+  return keys;
 }
 function resolveForeignKeyCondition(parent, parentName, child, childName) {
   for (const [, col] of columnEntries(child)) {
@@ -1758,8 +1787,8 @@ class JoinBuilderImpl {
   }
   #decodeJoinRows(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -1770,7 +1799,7 @@ class JoinBuilderImpl {
     }
     const grouped = new Map;
     for (const row of rows) {
-      const pk = row[pkColName];
+      const pk = pkColNames.length === 1 ? row[pkColNames[0]] : pkColNames.map((name) => String(row[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {
@@ -1888,8 +1917,8 @@ class SingleJoinBuilderImpl {
   }
   #decodeJoinRow(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -1900,7 +1929,7 @@ class SingleJoinBuilderImpl {
     }
     const grouped = new Map;
     for (const r2 of rows) {
-      const pk = r2[pkColName];
+      const pk = pkColNames.length === 1 ? r2[pkColNames[0]] : pkColNames.map((name) => String(r2[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {

package/dist/src/entries/better-sqlite3.js

@@ -976,12 +976,16 @@ function decodeSelectedRow(raw, tbl, keys) {
   }
   return out;
 }
-function findPKKey(tbl) {
+function findPKKeys(tbl) {
+  const keys = [];
   for (const [key, col] of columnEntries(tbl)) {
     if (col.__internal.isPrimaryKey)
-      return key;
+      keys.push(key);
   }
-  throw new FlintValidationError("Table has no primary key column");
+  if (keys.length === 0) {
+    throw new FlintValidationError("Table has no primary key column");
+  }
+  return keys;
 }
 function resolveForeignKeyCondition(parent, parentName, child, childName) {
   for (const [, col] of columnEntries(child)) {
@@ -1419,8 +1423,8 @@ class JoinBuilderImpl {
   }
   #decodeJoinRows(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -1431,7 +1435,7 @@ class JoinBuilderImpl {
     }
     const grouped = new Map;
     for (const row of rows) {
-      const pk = row[pkColName];
+      const pk = pkColNames.length === 1 ? row[pkColNames[0]] : pkColNames.map((name) => String(row[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {
@@ -1549,8 +1553,8 @@ class SingleJoinBuilderImpl {
   }
   #decodeJoinRow(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -1561,7 +1565,7 @@ class SingleJoinBuilderImpl {
     }
     const grouped = new Map;
     for (const r of rows) {
-      const pk = r[pkColName];
+      const pk = pkColNames.length === 1 ? r[pkColNames[0]] : pkColNames.map((name) => String(r[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {

package/dist/src/entries/bun-sqlite.js

@@ -211,12 +211,16 @@ function decodeSelectedRow(raw, tbl, keys) {
   }
   return out;
 }
-function findPKKey(tbl) {
+function findPKKeys(tbl) {
+  const keys = [];
   for (const [key, col] of columnEntries(tbl)) {
     if (col.__internal.isPrimaryKey)
-      return key;
+      keys.push(key);
   }
-  throw new FlintValidationError("Table has no primary key column");
+  if (keys.length === 0) {
+    throw new FlintValidationError("Table has no primary key column");
+  }
+  return keys;
 }
 function resolveForeignKeyCondition(parent, parentName, child, childName) {
   for (const [, col] of columnEntries(child)) {
@@ -654,8 +658,8 @@ class JoinBuilderImpl {
   }
   #decodeJoinRows(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -666,7 +670,7 @@ class JoinBuilderImpl {
     }
     const grouped = new Map;
     for (const row of rows) {
-      const pk = row[pkColName];
+      const pk = pkColNames.length === 1 ? row[pkColNames[0]] : pkColNames.map((name) => String(row[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {
@@ -784,8 +788,8 @@ class SingleJoinBuilderImpl {
   }
   #decodeJoinRow(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -796,7 +800,7 @@ class SingleJoinBuilderImpl {
     }
     const grouped = new Map;
     for (const r of rows) {
-      const pk = r[pkColName];
+      const pk = pkColNames.length === 1 ? r[pkColNames[0]] : pkColNames.map((name) => String(r[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {

package/dist/src/entries/expressions.js

@@ -211,12 +211,16 @@ function decodeSelectedRow(raw, tbl, keys) {
   }
   return out;
 }
-function findPKKey(tbl) {
+function findPKKeys(tbl) {
+  const keys = [];
   for (const [key, col] of columnEntries(tbl)) {
     if (col.__internal.isPrimaryKey)
-      return key;
+      keys.push(key);
   }
-  throw new FlintValidationError("Table has no primary key column");
+  if (keys.length === 0) {
+    throw new FlintValidationError("Table has no primary key column");
+  }
+  return keys;
 }
 function resolveForeignKeyCondition(parent, parentName, child, childName) {
   for (const [, col] of columnEntries(child)) {
@@ -654,8 +658,8 @@ class JoinBuilderImpl {
   }
   #decodeJoinRows(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -666,7 +670,7 @@ class JoinBuilderImpl {
     }
     const grouped = new Map;
     for (const row of rows) {
-      const pk = row[pkColName];
+      const pk = pkColNames.length === 1 ? row[pkColNames[0]] : pkColNames.map((name) => String(row[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {
@@ -784,8 +788,8 @@ class SingleJoinBuilderImpl {
   }
   #decodeJoinRow(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -796,7 +800,7 @@ class SingleJoinBuilderImpl {
     }
     const grouped = new Map;
     for (const r of rows) {
-      const pk = r[pkColName];
+      const pk = pkColNames.length === 1 ? r[pkColNames[0]] : pkColNames.map((name) => String(r[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {

package/dist/src/entries/libsql-web.js

@@ -4997,12 +4997,16 @@ function decodeSelectedRow(raw, tbl, keys) {
   }
   return out;
 }
-function findPKKey(tbl) {
+function findPKKeys(tbl) {
+  const keys = [];
   for (const [key, col] of columnEntries(tbl)) {
     if (col.__internal.isPrimaryKey)
-      return key;
+      keys.push(key);
   }
-  throw new FlintValidationError("Table has no primary key column");
+  if (keys.length === 0) {
+    throw new FlintValidationError("Table has no primary key column");
+  }
+  return keys;
 }
 function resolveForeignKeyCondition(parent, parentName, child, childName) {
   for (const [, col] of columnEntries(child)) {
@@ -5440,8 +5444,8 @@ class JoinBuilderImpl {
   }
   #decodeJoinRows(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -5452,7 +5456,7 @@ class JoinBuilderImpl {
     }
     const grouped = new Map;
     for (const row of rows) {
-      const pk = row[pkColName];
+      const pk = pkColNames.length === 1 ? row[pkColNames[0]] : pkColNames.map((name) => String(row[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {
@@ -5570,8 +5574,8 @@ class SingleJoinBuilderImpl {
   }
   #decodeJoinRow(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -5582,7 +5586,7 @@ class SingleJoinBuilderImpl {
     }
     const grouped = new Map;
     for (const r of rows) {
-      const pk = r[pkColName];
+      const pk = pkColNames.length === 1 ? r[pkColNames[0]] : pkColNames.map((name) => String(r[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {

package/dist/src/entries/libsql.js

@@ -6131,12 +6131,16 @@ function decodeSelectedRow(raw, tbl, keys) {
   }
   return out;
 }
-function findPKKey(tbl) {
+function findPKKeys(tbl) {
+  const keys = [];
   for (const [key, col] of columnEntries(tbl)) {
     if (col.__internal.isPrimaryKey)
-      return key;
+      keys.push(key);
   }
-  throw new FlintValidationError("Table has no primary key column");
+  if (keys.length === 0) {
+    throw new FlintValidationError("Table has no primary key column");
+  }
+  return keys;
 }
 function resolveForeignKeyCondition(parent, parentName, child, childName) {
   for (const [, col] of columnEntries(child)) {
@@ -6574,8 +6578,8 @@ class JoinBuilderImpl {
   }
   #decodeJoinRows(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -6586,7 +6590,7 @@ class JoinBuilderImpl {
     }
     const grouped = new Map;
     for (const row of rows) {
-      const pk = row[pkColName];
+      const pk = pkColNames.length === 1 ? row[pkColNames[0]] : pkColNames.map((name) => String(row[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {
@@ -6704,8 +6708,8 @@ class SingleJoinBuilderImpl {
   }
   #decodeJoinRow(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -6716,7 +6720,7 @@ class SingleJoinBuilderImpl {
     }
     const grouped = new Map;
     for (const r of rows) {
-      const pk = r[pkColName];
+      const pk = pkColNames.length === 1 ? r[pkColNames[0]] : pkColNames.map((name) => String(r[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {

package/dist/src/entries/table.js

@@ -291,7 +291,28 @@ function table(name, columns, indexFn) {
     const raw = indexFn(result);
     if (raw.length > 0) {
       const tableObj = result;
-      tableObj.__indexes = raw.map((item) => item.build());
+      const indexes = [];
+      let primaryKeyDef;
+      for (const item of raw) {
+        if (item && typeof item === "object" && "_type" in item) {
+          if (item._type === "primaryKey") {
+            primaryKeyDef = item.build();
+          } else {
+            indexes.push(item.build());
+          }
+        }
+      }
+      if (primaryKeyDef) {
+        for (const [key, col] of Object.entries(columns)) {
+          if (col.__internal.isPrimaryKey) {
+            throw new Error(`Column "${key}" has primaryKey() but table "${name}" also defines a composite primaryKey(). Use one or the other.`);
+          }
+        }
+        tableObj.__primaryKey = primaryKeyDef;
+      }
+      if (indexes.length > 0) {
+        tableObj.__indexes = indexes;
+      }
     }
   }
   return result;
@@ -365,10 +386,28 @@ function snakeCaseTable(tableName, columns, indexFn) {
 var snakeCase = {
   table: snakeCaseTable
 };
+function primaryKey() {
+  let columns = [];
+  const builder = {
+    _type: "primaryKey",
+    on(...cols) {
+      columns = cols;
+      return builder;
+    },
+    build() {
+      if (columns.length === 0) {
+        throw new Error("primaryKey() has no columns \u2014 call .on() before returning");
+      }
+      return { columns: columns.map((c) => c.name) };
+    }
+  };
+  return builder;
+}
 function index(name) {
   let columns = [];
   let isUnique = false;
   const builder = {
+    _type: "index",
     on(...cols) {
       columns = cols;
       return builder;
@@ -395,6 +434,7 @@ export {
   table,
   snakeCase,
   real,
+  primaryKey,
   json,
   integer,
   index,

package/dist/src/entries/turso-sync.js

@@ -2432,12 +2432,16 @@ function decodeSelectedRow(raw, tbl, keys) {
   }
   return out;
 }
-function findPKKey(tbl) {
+function findPKKeys(tbl) {
+  const keys = [];
   for (const [key, col] of columnEntries(tbl)) {
     if (col.__internal.isPrimaryKey)
-      return key;
+      keys.push(key);
   }
-  throw new FlintValidationError("Table has no primary key column");
+  if (keys.length === 0) {
+    throw new FlintValidationError("Table has no primary key column");
+  }
+  return keys;
 }
 function resolveForeignKeyCondition(parent, parentName, child, childName) {
   for (const [, col] of columnEntries(child)) {
@@ -2875,8 +2879,8 @@ class JoinBuilderImpl {
   }
   #decodeJoinRows(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -2887,7 +2891,7 @@ class JoinBuilderImpl {
     }
     const grouped = new Map;
     for (const row of rows) {
-      const pk = row[pkColName];
+      const pk = pkColNames.length === 1 ? row[pkColNames[0]] : pkColNames.map((name) => String(row[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {
@@ -3005,8 +3009,8 @@ class SingleJoinBuilderImpl {
   }
   #decodeJoinRow(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -3017,7 +3021,7 @@ class SingleJoinBuilderImpl {
     }
     const grouped = new Map;
     for (const r of rows) {
-      const pk = r[pkColName];
+      const pk = pkColNames.length === 1 ? r[pkColNames[0]] : pkColNames.map((name) => String(r[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {

package/dist/src/entries/turso.js

@@ -1313,12 +1313,16 @@ function decodeSelectedRow(raw, tbl, keys) {
   }
   return out;
 }
-function findPKKey(tbl) {
+function findPKKeys(tbl) {
+  const keys = [];
   for (const [key, col] of columnEntries(tbl)) {
     if (col.__internal.isPrimaryKey)
-      return key;
+      keys.push(key);
   }
-  throw new FlintValidationError("Table has no primary key column");
+  if (keys.length === 0) {
+    throw new FlintValidationError("Table has no primary key column");
+  }
+  return keys;
 }
 function resolveForeignKeyCondition(parent, parentName, child, childName) {
   for (const [, col] of columnEntries(child)) {
@@ -1756,8 +1760,8 @@ class JoinBuilderImpl {
   }
   #decodeJoinRows(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -1768,7 +1772,7 @@ class JoinBuilderImpl {
     }
     const grouped = new Map;
     for (const row of rows) {
-      const pk = row[pkColName];
+      const pk = pkColNames.length === 1 ? row[pkColNames[0]] : pkColNames.map((name) => String(row[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {
@@ -1886,8 +1890,8 @@ class SingleJoinBuilderImpl {
   }
   #decodeJoinRow(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -1898,7 +1902,7 @@ class SingleJoinBuilderImpl {
     }
     const grouped = new Map;
     for (const r of rows) {
-      const pk = r[pkColName];
+      const pk = pkColNames.length === 1 ? r[pkColNames[0]] : pkColNames.map((name) => String(r[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {

package/dist/src/index.js

@@ -211,12 +211,16 @@ function decodeSelectedRow(raw, tbl, keys) {
   }
   return out;
 }
-function findPKKey(tbl) {
+function findPKKeys(tbl) {
+  const keys = [];
   for (const [key, col] of columnEntries(tbl)) {
     if (col.__internal.isPrimaryKey)
-      return key;
+      keys.push(key);
   }
-  throw new FlintValidationError("Table has no primary key column");
+  if (keys.length === 0) {
+    throw new FlintValidationError("Table has no primary key column");
+  }
+  return keys;
 }
 function resolveForeignKeyCondition(parent, parentName, child, childName) {
   for (const [, col] of columnEntries(child)) {
@@ -654,8 +658,8 @@ class JoinBuilderImpl {
   }
   #decodeJoinRows(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -666,7 +670,7 @@ class JoinBuilderImpl {
     }
     const grouped = new Map;
     for (const row of rows) {
-      const pk = row[pkColName];
+      const pk = pkColNames.length === 1 ? row[pkColNames[0]] : pkColNames.map((name) => String(row[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {
@@ -784,8 +788,8 @@ class SingleJoinBuilderImpl {
   }
   #decodeJoinRow(rows) {
     const parentEntries = columnEntries(this.#parent);
-    const pkKey = findPKKey(this.#parent);
-    const pkColName = getCol(this.#parent, pkKey).name;
+    const pkKeys = findPKKeys(this.#parent);
+    const pkColNames = pkKeys.map((k) => getCol(this.#parent, k).name);
     const childEntryMaps = [];
     for (const j of this.#joins) {
       childEntryMaps.push({
@@ -796,7 +800,7 @@ class SingleJoinBuilderImpl {
     }
     const grouped = new Map;
     for (const r of rows) {
-      const pk = r[pkColName];
+      const pk = pkColNames.length === 1 ? r[pkColNames[0]] : pkColNames.map((name) => String(r[name])).join("||");
       if (!grouped.has(pk)) {
         const parentRow = {};
         for (const [key, col] of parentEntries) {
@@ -1456,7 +1460,28 @@ function table(name, columns, indexFn) {
     const raw = indexFn(result);
     if (raw.length > 0) {
       const tableObj = result;
-      tableObj.__indexes = raw.map((item) => item.build());
+      const indexes = [];
+      let primaryKeyDef;
+      for (const item of raw) {
+        if (item && typeof item === "object" && "_type" in item) {
+          if (item._type === "primaryKey") {
+            primaryKeyDef = item.build();
+          } else {
+            indexes.push(item.build());
+          }
+        }
+      }
+      if (primaryKeyDef) {
+        for (const [key, col] of Object.entries(columns)) {
+          if (col.__internal.isPrimaryKey) {
+            throw new Error(`Column "${key}" has primaryKey() but table "${name}" also defines a composite primaryKey(). Use one or the other.`);
+          }
+        }
+        tableObj.__primaryKey = primaryKeyDef;
+      }
+      if (indexes.length > 0) {
+        tableObj.__indexes = indexes;
+      }
     }
   }
   return result;
@@ -1530,10 +1555,28 @@ function snakeCaseTable(tableName, columns, indexFn) {
 var snakeCase = {
   table: snakeCaseTable
 };
+function primaryKey() {
+  let columns = [];
+  const builder = {
+    _type: "primaryKey",
+    on(...cols) {
+      columns = cols;
+      return builder;
+    },
+    build() {
+      if (columns.length === 0) {
+        throw new Error("primaryKey() has no columns \u2014 call .on() before returning");
+      }
+      return { columns: columns.map((c) => c.name) };
+    }
+  };
+  return builder;
+}
 function index(name) {
   let columns = [];
   let isUnique = false;
   const builder = {
+    _type: "index",
     on(...cols) {
       columns = cols;
       return builder;
@@ -1623,7 +1666,7 @@ function introspectColumns(client, tableName) {
     const col = {
       name: row.name,
       sqlType: normalizeType(row.type),
-      isPrimaryKey: row.pk === 1,
+      isPrimaryKey: row.pk > 0,
       isNotNull: row.notnull === 1,
       isUnique: uniqueColumns.has(row.name),
       hasDefault,
@@ -1639,7 +1682,8 @@ function introspectColumns(client, tableName) {
     }
     return col;
   });
-  return { columns, indexRows };
+  const pkColumns = rows.filter((row) => row.pk > 0).sort((a, b) => a.pk - b.pk).map((row) => row.name);
+  return { columns, indexRows, primaryKeyColumns: pkColumns.length > 1 ? pkColumns : undefined };
 }
 function introspectIndexes(client, indexRows) {
   const indexes = [];
@@ -1660,12 +1704,13 @@ function introspect(client) {
   const tableRows = client.query(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name != '__flint_migrations'`).all();
   const tables = {};
   for (const { name } of tableRows) {
-    const { columns, indexRows } = introspectColumns(client, name);
+    const { columns, indexRows, primaryKeyColumns } = introspectColumns(client, name);
     const indexes = introspectIndexes(client, indexRows);
     tables[name] = {
       name,
       columns,
-      indexes
+      indexes,
+      primaryKeyColumns
     };
   }
   return {
@@ -1680,6 +1725,7 @@ export {
   sql,
   snakeCase,
   real,
+  primaryKey,
   or,
   neq,
   min,

package/dist/src/migration/index.js

@@ -97,7 +97,17 @@ function serializeTable(table) {
       });
     }
   }
-  return { name: tableName, columns, indexes };
+  let primaryKeyColumns;
+  if (tableObj.__primaryKey) {
+    const pkDef = tableObj.__primaryKey;
+    primaryKeyColumns = pkDef.columns;
+    for (const col of columns) {
+      if (col.isPrimaryKey) {
+        throw new Error(`Column "${col.name}" has primaryKey() but table "${tableName}" also defines a composite primaryKey(). Use one or the other.`);
+      }
+    }
+  }
+  return { name: tableName, columns, indexes, primaryKeyColumns };
 }
 function serializeSchema(tables) {
   const tableMap = {};
@@ -262,6 +272,11 @@ function diffTable(tableName, prev, curr) {
   if (unsafe) {
     return [rebuildTable(tableName, prev, curr)];
   }
+  const prevPK = prev.primaryKeyColumns ?? [];
+  const currPK = curr.primaryKeyColumns ?? [];
+  if (JSON.stringify(prevPK) !== JSON.stringify(currPK)) {
+    return [rebuildTable(tableName, prev, curr)];
+  }
   const ops = [...columnOps];
   const prevIndexes = new Map(prev.indexes.map((i) => [i.name, i]));
   const currIndexes = new Map(curr.indexes.map((i) => [i.name, i]));
@@ -466,9 +481,9 @@ __export(exports_sql, {
 function sqlType(col) {
   return col.sqlType.toUpperCase();
 }
-function columnToDDL(col) {
+function columnToDDL(col, isCompositePK = false) {
   const parts = [col.name, sqlType(col)];
-  if (col.isPrimaryKey)
+  if (col.isPrimaryKey && !isCompositePK)
     parts.push("PRIMARY KEY");
   if (col.isAutoIncrement === true)
     parts.push("AUTOINCREMENT");
@@ -515,7 +530,12 @@ function rebuildTableToSQL(op) {
   const tempName = `_flint_rebuild_${tableName}`;
   const stmts = [];
   stmts.push("PRAGMA defer_foreign_keys = 1");
-  const cols = newTable.columns.map(columnToDDL).join(`,
+  const isComposite = newTable.primaryKeyColumns && newTable.primaryKeyColumns.length > 0;
+  const colDefs = newTable.columns.map((c) => columnToDDL(c, isComposite));
+  if (isComposite) {
+    colDefs.push(`PRIMARY KEY(${newTable.primaryKeyColumns.join(", ")})`);
+  }
+  const cols = colDefs.join(`,
   `);
   stmts.push(`CREATE TABLE ${tempName} (
   ${cols}
@@ -542,7 +562,12 @@ function rebuildTableToSQL(op) {
 function operationToSQL(op) {
   switch (op.type) {
     case "addTable": {
-      const cols = op.table.columns.map(columnToDDL).join(`,
+      const isComposite = op.table.primaryKeyColumns && op.table.primaryKeyColumns.length > 0;
+      const colDefs = op.table.columns.map((c) => columnToDDL(c, isComposite));
+      if (isComposite) {
+        colDefs.push(`PRIMARY KEY(${op.table.primaryKeyColumns.join(", ")})`);
+      }
+      const cols = colDefs.join(`,
   `);
       const stmts = [`CREATE TABLE ${op.table.name} (
   ${cols}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "flint-orm",
-  "version": "0.7.2",
+  "version": "0.8.0",
+  "license": "MIT",
   "keywords": [
     "database",
     "libsql",