@sqlanvil/core 1.32.9 → 1.33.0

package/configs.proto

@@ -268,7 +268,8 @@ message ActionConfig {
   }
 
   message TableConfig {
-    // The name of the table.
+    // The name of the table. Defaults to the file's name, without the extension; set it to
+    // override. Other actions `ref()` the table by this name.
     string name = 1;
 
     // The dataset (schema) of the table.
@@ -377,7 +378,8 @@ message ActionConfig {
   }
 
   message ViewConfig {
-    // The name of the view.
+    // The name of the view. Defaults to the file's name, without the extension; set it to
+    // override. Other actions `ref()` the view by this name.
     string name = 1;
 
     // The dataset (schema) of the view.
@@ -493,7 +495,8 @@ message ActionConfig {
   }
 
   message IncrementalTableConfig {
-    // The name of the incremental table.
+    // The name of the incremental table. Defaults to the file's name, without the extension; set
+    // it to override. Other actions `ref()` the table by this name.
     string name = 1;
 
     // The dataset (schema) of the incremental table.
@@ -617,7 +620,8 @@ message ActionConfig {
   }
 
   message AssertionConfig {
-    // The name of the assertion.
+    // The name of the assertion. Defaults to the file's name, without the extension; set it to
+    // override. Other actions refer to the assertion by this name, for example in `dependencies`.
     string name = 1;
 
     // The dataset (schema) of the assertion.
@@ -663,7 +667,9 @@ message ActionConfig {
   }
 
   message OperationConfig {
-    // The name of the operation.
+    // The name of the operation. Defaults to the file's name, without the extension; set it to
+    // override. Other actions refer to it by this name in `dependencies`, or with `ref()` if
+    // `hasOutput` is true.
     string name = 1;
 
     // The dataset (schema) of the operation.
@@ -731,7 +737,9 @@ message ActionConfig {
   // Configuration for a `type: "export"` action: writes a SELECT result to a
   // Parquet/CSV/JSON file at a cloud or local location.
   message ExportConfig {
-    // The name of the export.
+    // The name of the export. Defaults to the file's name, without the extension; set it to
+    // override. Unless `export.filename` is set, this is also the base name of the file the export
+    // writes.
     string name = 1;
 
     // The dataset (schema) used to qualify the export's target name.
@@ -780,7 +788,8 @@ message ActionConfig {
   // Configuration for a `type: "import"` action: loads a Parquet/CSV/JSON file into a table in
   // the warehouse (the inverse of `type: "export"`). The resulting table is ref()-able.
   message ImportConfig {
-    // The name of the import (the destination table name).
+    // The name of the import (the destination table name). Defaults to the file's name, without
+    // the extension; set it to override. Other actions `ref()` the loaded table by this name.
     string name = 1;
 
     // The dataset (schema) used to qualify the import's target name.
@@ -812,7 +821,9 @@ message ActionConfig {
   }
 
   message DeclarationConfig {
-    // The name of the declaration.
+    // The name of the declaration, which must match the existing table it points at. In a SQLX
+    // file it defaults to the file's name, without the extension; in an action configs file or the
+    // JavaScript API it is required.
     string name = 1;
 
     // The dataset (schema) of the declaration.
@@ -843,7 +854,8 @@ message ActionConfig {
   }
 
   message NotebookConfig {
-    // The name of the notebook.
+    // The name of the notebook. Defaults to the notebook file's name, without the extension; set
+    // it to override, for example to run one notebook file as several actions.
     string name = 1;
 
     // The Google Cloud location of the notebook.
@@ -878,7 +890,9 @@ message ActionConfig {
   }
 
   message DataPreparationConfig {
-    // The name of the data preparation.
+    // The name of the data preparation, which is also the name of the table it writes. Defaults to
+    // the file's name without its `.dp.yaml`, `.dp.sqlx`, `.yaml` or `.sqlx` extension; set it to
+    // override.
     string name = 1;
 
     // The dataset (schema) of the destination table.
@@ -928,7 +942,9 @@ message ActionConfig {
   // sugar that normalizes to `script: { language: "python", ... }`. Scripts never receive
   // warehouse credentials; they produce files, and `type: "import"` is the loading boundary.
   message ScriptConfig {
-    // The name of the script action (how downstream actions depend on it).
+    // The name of the script action (how downstream actions depend on it). Defaults to the script
+    // file's name, without the extension; set it to override, for example to run one script file
+    // as several actions.
     string name = 1;
 
     // The dataset (schema) used to qualify the script's target name.
@@ -992,6 +1008,9 @@ message ActionConfig {
   }
 
   message RlsPolicyConfig {
+    // The name of the Postgres policy that `CREATE POLICY` creates. Set it explicitly; unlike most
+    // actions, it is not taken from the file name. The action itself is named
+    // `{table}_policy_{name}`.
     string name = 1;
     string table = 2;
     string command = 3;
@@ -1003,6 +1022,8 @@ message ActionConfig {
   }
 
   message RealtimePublicationConfig {
+    // The Postgres publication to add the table to. Optional; defaults to `supabase_realtime`, not
+    // to the file name. The action itself is named `{table}_realtime_{name}`.
     string name = 1;
     string table = 2;
     repeated string events = 3;
@@ -1010,7 +1031,11 @@ message ActionConfig {
     repeated Target dependency_targets = 5;
   }
 
+  // Not usable in actions.yaml: a wrapper needs provider, credential and foreignTables, which
+  // this config lacks. Define wrappers with `wrapper({ ... })` in a definitions/*.js file.
   message ForeignWrapperConfig {
+    // The name of the wrapper action. Set it explicitly; unlike most actions, it is not taken from
+    // the file name. The Postgres foreign server's name is set separately by `server`.
     string name = 1;
     string wrapper = 2;
     string server = 3;
@@ -1020,6 +1045,8 @@ message ActionConfig {
   }
 
   message VectorIndexConfig {
+    // The name of the Postgres index. Set it explicitly; unlike most actions, it is not taken from
+    // the file name. The action itself is named `{table}_idx_{name}`.
     string name = 1;
     string table = 2;
     string column = 3;
@@ -1246,39 +1273,43 @@ message MysqlOptions {
 }
 
 // SupabaseOptions — Supabase-specific platform features layered on top of
-// standard Postgres. Used as a peer of `postgres: {...}` for projects
-// targeting `warehouse: { kind: supabase }`.
+// standard Postgres. Used as a peer of `postgres: {...}` on table and incremental table configs,
+// and only valid with `warehouse: supabase`. The settings are applied each time the table is
+// created (every run for a table; the first run or a full refresh for an incremental table),
+// after its indexes and before its post_operations.
 message SupabaseOptions {
   // Standard Postgres options apply. Set these via `postgres:` directly or
-  // nest under `supabase.postgres:` — either is accepted.
+  // nest under `supabase.postgres:` — either is accepted; `postgres:` wins if both are set.
   PostgresOptions postgres = 1;
 
+  // ALTER TABLE <this> REPLICA IDENTITY FULL, then
   // ALTER PUBLICATION supabase_realtime ADD TABLE <this>.
-  // Implicitly sets REPLICA IDENTITY appropriately.
   bool publish_to_realtime = 2;
 
   // ALTER TABLE <this> ENABLE ROW LEVEL SECURITY.
-  // Note: only enables RLS — policies are declared via the `rlsPolicy`
-  // action type (see Phase 5).
+  // Note: only enables RLS — declare policies with `rlsPolicy()`.
   bool enable_rls = 3;
 
-  // OWNER TO <role>. Typically "postgres" or "service_role".
+  // ALTER TABLE <this> OWNER TO <role>. Typically "postgres" or "service_role".
   string owner_role = 4;
 
-  // pgvector convenience config. Equivalent to declaring a
-  // PostgresOptions.Index with method=HNSW or method=GIST + ivfflat ops,
-  // but more ergonomic for RAG pipelines.
+  // pgvector index on a vector column, named <table>_<column>_idx. Creates the `vector`
+  // extension if needed (the column's type must already exist when the table is created).
   message VectorConfig {
+    // The vector column to index. Required.
     string column = 1;
+    // Informational; the column's declared type sets the dimensions.
     uint32 dimensions = 2;
 
     enum IndexType {
       IVFFLAT = 0;
       HNSW = 1;
     }
+    // "hnsw" (the default when omitted) or "ivfflat", in any case.
     IndexType index_type = 3;
 
-    // ivfflat: { lists }, hnsw: { m, ef_construction }.
+    // `opclass` sets the operator class (default vector_cosine_ops); every other key becomes
+    // an index storage parameter. ivfflat: { lists }, hnsw: { m, ef_construction }.
     map<string, string> params = 4;
   }
   repeated VectorConfig vectors = 5;

package/package.json

@@ -49,7 +49,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "version": "1.32.9",
+    "version": "1.33.0",
     "name": "@sqlanvil/core",
     "description": "sqlanvil core API.",
     "main": "bundle.js"