supabase-test 0.0.13 → 0.0.14

package/README.md

@@ -56,7 +56,6 @@ Part of the [LaunchQL](https://github.com/launchql) ecosystem, `pgsql-test` is b
    * [Programmatic Seeding](#-programmatic-seeding)
    * [CSV Seeding](#️-csv-seeding)
    * [JSON Seeding](#️-json-seeding)
-   * [Sqitch Seeding](#️-sqitch-seeding)
    * [LaunchQL Seeding](#-launchql-seeding)
 7. [`getConnections() Options` ](#getconnections-options)
 8. [Disclaimer](#disclaimer)
@@ -238,16 +237,48 @@ This array lets you fully customize how your test database is seeded. You can co
 * [`seed.fn()`](#-programmatic-seeding) – Run JavaScript/TypeScript logic to programmatically insert data
 * [`seed.csv()`](#️-csv-seeding) – Load tabular data from CSV files
 * [`seed.json()`](#️-json-seeding) – Use in-memory objects as seed data
-* [`seed.sqitch()`](#️-sqitch-seeding) – Deploy a Sqitch-compatible migration project
-* [`seed.launchql()`](#-launchql-seeding) – Apply a LaunchQL module using `deployFast()` (compatible with sqitch)
+* [`seed.launchql()`](#-launchql-seeding) – Apply a LaunchQL project or set of packages (compatible with sqitch)
 
 > ✨ **Default Behavior:** If no `SeedAdapter[]` is passed, LaunchQL seeding is assumed. This makes `supabase-test` zero-config for LaunchQL-based projects.
 
 This composable system allows you to mix-and-match data setup strategies for flexible, realistic, and fast database tests.
 
+#### Two Seeding Patterns
+
+You can seed data using either approach:
+
+**1. Adapter Pattern** (setup phase via `getConnections`)
+```ts
+const { db, teardown } = await getConnections({}, [
+  seed.json({ 'users': [{ id: 1, name: 'Alice' }] })
+]);
+```
+
+**2. Direct Load Methods** (runtime via `PgTestClient`)
+```ts
+await db.loadJson({ 'users': [{ id: 1, name: 'Alice' }] });
+await db.loadCsv({ 'users': '/path/to/users.csv' });
+await db.loadSql(['/path/to/schema.sql']);
+```
+
+> **Note:** `loadCsv()` and `loadLaunchql()` do not apply RLS context (PostgreSQL limitation). Use `loadJson()` or `loadSql()` for RLS-aware seeding.
+
 ### 🔌 SQL File Seeding
 
-Use `.sql` files to set up your database state before tests:
+**Adapter Pattern:**
+```ts
+const { db, teardown } = await getConnections({}, [
+  seed.sqlfile(['schema.sql', 'fixtures.sql'])
+]);
+```
+
+**Direct Load Method:**
+```ts
+await db.loadSql(['schema.sql', 'fixtures.sql']);
+```
+
+<details>
+<summary>Full example</summary>
 
 ```ts
 import path from 'path';
@@ -272,9 +303,27 @@ afterAll(async () => {
 });
 ```
 
+</details>
+
 ### 🧠 Programmatic Seeding
 
-Use JavaScript functions to insert seed data:
+**Adapter Pattern:**
+```ts
+const { db, teardown } = await getConnections({}, [
+  seed.fn(async ({ pg }) => {
+    await pg.query(`INSERT INTO users (name) VALUES ('Seeded User')`);
+  })
+]);
+```
+
+**Direct Load Method:**
+```ts
+// Use any PgTestClient method directly
+await db.query(`INSERT INTO users (name) VALUES ('Seeded User')`);
+```
+
+<details>
+<summary>Full example</summary>
 
 ```ts
 import { getConnections, seed } from 'supabase-test';
@@ -293,8 +342,33 @@ beforeAll(async () => {
 });
 ```
 
+</details>
+
 ## 🗃️ CSV Seeding
 
+**Adapter Pattern:**
+```ts
+const { db, teardown } = await getConnections({}, [
+  seed.csv({
+    'users': '/path/to/users.csv',
+    'posts': '/path/to/posts.csv'
+  })
+]);
+```
+
+**Direct Load Method:**
+```ts
+await db.loadCsv({
+  'users': '/path/to/users.csv',
+  'posts': '/path/to/posts.csv'
+});
+```
+
+> **Note:** CSV loading uses PostgreSQL COPY which does not support RLS context.
+
+<details>
+<summary>Full example</summary>
+
 You can load tables from CSV files using `seed.csv({ ... })`. CSV headers must match the table column names exactly. This is useful for loading stable fixture data for integration tests or CI environments.
 
 ```ts
@@ -344,8 +418,35 @@ it('has loaded rows', async () => {
 });
 ```
 
+</details>
+
 ## 🗃️ JSON Seeding
 
+**Adapter Pattern:**
+```ts
+const { db, teardown } = await getConnections({}, [
+  seed.json({
+    'custom.users': [
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' }
+    ]
+  })
+]);
+```
+
+**Direct Load Method:**
+```ts
+await db.loadJson({
+  'custom.users': [
+    { id: 1, name: 'Alice' },
+    { id: 2, name: 'Bob' }
+  ]
+});
+```
+
+<details>
+<summary>Full example</summary>
+
 You can seed tables using in-memory JSON objects. This is useful when you want fast, inline fixtures without managing external files.
 
 ```ts
@@ -399,28 +500,32 @@ it('has loaded rows', async () => {
 });
 ```
 
-## 🏗️ Sqitch Seeding
+</details>
 
-*Note: While compatible with Sqitch syntax, LaunchQL uses its own high-performance [TypeScript-based deploy engine.](#-launchql-seeding) that we encourage using for sqitch projects*
-
-You can seed your test database using a Sqitch project but with significantly improved performance by leveraging LaunchQL's TypeScript deployment engine:
+## 🚀 LaunchQL Seeding
 
+**Zero Configuration (Default):**
 ```ts
-import path from 'path';
-import { getConnections, seed } from 'supabase-test';
+// LaunchQL migrate is used automatically
+const { db, teardown } = await getConnections();
+```
 
-const cwd = path.resolve(__dirname, '../path/to/sqitch');
+**Adapter Pattern (Custom Path):**
+```ts
+const { db, teardown } = await getConnections({}, [
+  seed.launchql('/path/to/launchql', true) // with cache
+]);
+```
 
-beforeAll(async () => {
-  ({ db, teardown } = await getConnections({}, [
-    seed.sqitch(cwd)
-  ]));
-});
+**Direct Load Method:**
+```ts
+await db.loadLaunchql('/path/to/launchql', true); // with cache
 ```
 
-This works for any Sqitch-compatible module, now accelerated by LaunchQL's deployment tooling.
+> **Note:** LaunchQL deployment has its own client handling and does not apply RLS context.
 
-## 🚀 LaunchQL Seeding
+<details>
+<summary>Full example</summary>
 
 If your project uses LaunchQL modules with a precompiled `launchql.plan`, you can use `supabase-test` with **zero configuration**. Just call `getConnections()` — and it *just works*:
 
@@ -430,14 +535,13 @@ import { getConnections } from 'supabase-test';
 let db, teardown;
 
 beforeAll(async () => {
-  ({ db, teardown } = await getConnections()); // 🚀 LaunchQL deployFast() is used automatically - up to 10x faster than traditional Sqitch!
+  ({ db, teardown } = await getConnections()); // LaunchQL module is deployed automatically
 });
 ```
 
-This works out of the box because `supabase-test` uses the high-speed `deployFast()` function by default, applying any compiled LaunchQL schema located in the current working directory (`process.cwd()`).
-
-If you want to specify a custom path to your LaunchQL module, use `seed.launchql()` explicitly:
+LaunchQL uses Sqitch-compatible syntax with a TypeScript-based migration engine. By default, `supabase-test` automatically deploys any LaunchQL module found in the current working directory (`process.cwd()`).
 
+To specify a custom path to your LaunchQL module, use `seed.launchql()` explicitly:
 
 ```ts
 import path from 'path';
@@ -447,11 +551,24 @@ const cwd = path.resolve(__dirname, '../path/to/launchql');
 
 beforeAll(async () => {
   ({ db, teardown } = await getConnections({}, [
-    seed.launchql(cwd) // uses deployFast() - up to 10x faster than traditional Sqitch!
+    seed.launchql(cwd)
   ]));
 });
 ```
 
+</details>
+
+## Why LaunchQL's Approach?
+
+LaunchQL provides the best of both worlds:
+
+1. **Sqitch Compatibility**: Keep your familiar Sqitch syntax and migration approach
+2. **TypeScript Performance**: Our TS-rewritten deployment engine delivers up to 10x faster schema deployments
+3. **Developer Experience**: Tight feedback loops with near-instant schema setup for tests
+4. **CI Optimization**: Dramatically reduced test suite run times with optimized deployment
+
+By maintaining Sqitch compatibility while supercharging performance, LaunchQL enables you to keep your existing migration patterns while enjoying the speed benefits of our TypeScript engine.
+
 ## Why LaunchQL's Approach?
 
 LaunchQL provides the best of both worlds:
@@ -472,7 +589,7 @@ This table documents the available options for the `getConnections` function. Th
 | Option                   | Type       | Default          | Description                                                                 |
 | ------------------------ | ---------- | ---------------- | --------------------------------------------------------------------------- |
 | `db.extensions`          | `string[]` | `[]`             | Array of PostgreSQL extensions to include in the test database              |
-| `db.cwd`                 | `string`   | `process.cwd()`  | Working directory used for LaunchQL/Sqitch projects                         |
+| `db.cwd`                 | `string`   | `process.cwd()`  | Working directory used for LaunchQL or Sqitch projects                         |
 | `db.connection.user`     | `string`   | `'app_user'`     | User for simulating RLS via `setContext()`                                  |
 | `db.connection.password` | `string`   | `'app_password'` | Password for RLS test user                                                  |
 | `db.connection.role`     | `string`   | `'anonymous'`    | Default role used during `setContext()`                                     |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supabase-test",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "author": "Interweb <developers@interweb.io>",
   "description": "supabase-test offers isolated, role-aware, and rollback-friendly PostgreSQL environments for integration tests with Supabase defaults baked in",
   "main": "index.js",
@@ -52,9 +52,9 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@launchql/types": "^2.6.3",
+    "@launchql/types": "^2.7.0",
     "pg-env": "^1.1.1",
-    "pgsql-test": "^2.11.13"
+    "pgsql-test": "^2.12.0"
   },
-  "gitHead": "ab60dc92d8b8a620cf59f7962c213ca70d735406"
+  "gitHead": "7a71d63b0ac5b0ea13f2c55cbb09d5fc0957a4f5"
 }