@xeplr/actions 2.2.3 → 2.2.5

package/README.md

@@ -122,7 +122,7 @@ The input is checked exactly as a run checks it.
 
 | previewed (reads, up to 5) | example only (writes or sends; never run) |
 |---|---|
-| `db-fetch` (through the run's own cursor, then stops; nothing spooled), `db-list-tables` / `-views` / `-procedures` / `-columns`, `file-list`, `file-read`, `data-operation` (the run itself: it only computes), `email-read` (the mailbox opened **read-only**, IMAP `EXAMINE`, so nothing is marked read) | `file-move`, `file-delete`, `email-send`, `push-send`, `email-move`, `email-delete`, `email-download-email`, `email-download-attachments`, `export-table`, `export-pages`, `db-procedure` (a procedure may write) |
+| `db-fetch` (through the run's own cursor, then stops; nothing spooled), `db-list-tables` / `-views` / `-procedures` / `-columns` / `-foreign-keys`, `file-list`, `file-read`, `data-operation` (the run itself: it only computes), `email-read` (the mailbox opened **read-only**, IMAP `EXAMINE`, so nothing is marked read) | `file-move`, `file-delete`, `email-send`, `push-send`, `email-move`, `email-delete`, `email-download-email`, `email-download-attachments`, `export-table`, `export-pages`, `db-procedure` (a procedure may write) |
 
 Neither: `db-push`, `db-move`, `http-request` (an outside system, which may change something), `spawn-program`, `file-upload`; a designer asks for an example by hand. `test/previews.test.js` checks it on a real folder, file and Postgres: five rows read and no file spooled, the real count kept, a deleting step's file still there.
 
@@ -138,12 +138,13 @@ Register the ones you want (`register(actions.builtins.dbFetch)`) or pass a modu
 | `dbFetch` | `db-fetch` | Stream rows from a table (`mode: 'table'`) or SQL (`mode: 'query'`, `params`). Default `streaming_mode: true` → NDJSON file `{ filePath, format: 'jsonl', bytes, rows }`; `false` → `{ rows, rowCount }`. |
 | `dbPush` | `db-push` | Write `rows` or an NDJSON `filePath` into `targetTable` through the uploader. `primaryKeys` → upsert. |
 | `dbMove` | `db-move` | One window of rows from a source table, query or procedure into a target table in one streamed pass. See [db-move](#db-move). |
-| `dbDump` | `db-dump` | A whole database to one backup file with its own dump program: `pg_dump -Fc` (Postgres, `.dump`) or `mysqldump` (MySQL, `.sql.gz`). See [Backups](#backups-db-dump-and-s3-upload). |
+| `dbDump` | `db-dump` | A whole database to one backup file with its own dump program: `pg_dump -Fc` (Postgres, `.dump`) or `mysqldump` (MySQL, `.sql.gz`). See [Backups](#backups-db-dump-folder-archive-and-s3-upload). |
 | `dbProcedure` | `db-procedure` | Call a stored procedure; returns `{ rows, rowCount, procedure, sql }`. See [db-procedure](#db-procedure). |
 | `dbListTables` | `db-list-tables` | `{ tables }` — base tables in a schema/database. |
 | `dbListViews` | `db-list-views` | `{ views }`. |
 | `dbListProcedures` | `db-list-procedures` | `{ procedures }` (functions excluded). |
 | `dbListColumns` | `db-list-columns` | `{ columns }` — `name`, `dataType`, `udtName` and `maxLength` (characters; `-1` is SQL Server `(max)`, `null` when it has none) for one table. |
+| `dbListForeignKeys` | `db-list-foreign-keys` | `{ foreignKeys }` — each foreign key between the tables of a schema/database: `{ name, table, columns, refTable, refColumns }`, a composite key's columns in key order. Only keys whose **both** tables are in the schema `db-list-tables` lists, so every name is one it returns. Postgres (`public`), MySQL (the connection's database), SQL Server (every schema unless `schema`), DuckDB (`main`). What the BI dataset canvas joins two tables on without asking. |
 | `fileUpload` | `file-upload` | Read a file (`sourceType`, `sourcePath`), parse it (`format`), load it into `targetTable` (`dbType`, `dbConnection`) as a New table, Append or Replace (`mode`, see [Import modes](#import-modes)). Passes `system.onProgress` (`{ rowsRead, batches, rowsWritten }`, per batch) and `system.signal` (stop) to the uploader, as `db-move` does. |
 | `sendEmail` | `email-send` | Send one message. See [Email](#email). |
 | `pushSend` | `push-send` | A push notification on people's phones and computers, even with the app closed, by `emails` and/or `userIds`: `title` (required), `body`, `url` (a page of the app a tap opens), `tag`. Returns `{ devices, sent, removed, failed }`. Through [`@xeplr/push`](https://www.npmjs.com/package/@xeplr/push), which the host sets up. |
@@ -153,7 +154,8 @@ Register the ones you want (`register(actions.builtins.dbFetch)`) or pass a modu
 | `emailDownloadEmail` | `email-download-email` | Stream the raw message to an `.eml` file, named by `fileName`. `{ count, saved[], path, existing[] }`. |
 | `emailDownloadAttachments` | `email-download-attachments` | Save attachments, optionally filtered by `extension` / `filenameContains`, named by `fileName` (see [Saving files](#saving-files-names-and-a-name-already-taken)). `{ count, saved[], path, skipped, existing[] }`. |
 | `fileList` | `file-list` | The files in a folder, optionally matching `pattern` (`*.csv`, `Bank-2026-??.pdf`), sorted by name or date. `{ files[{ name, path, size, modifiedAt }], count }`. "Is it there?" is the exact name and `count`. See [Where files are](#where-files-are-one-data-root-a-folder-per-tenant). |
-| `s3Upload` | `s3-upload` | One file to an S3 bucket (or an S3-compatible `endpoint`), in parts, with a SHA-256 checksum. Only writes. See [Backups](#backups-db-dump-and-s3-upload). |
+| `s3Upload` | `s3-upload` | One file to an S3 bucket (or an S3-compatible `endpoint`), in parts, with a SHA-256 checksum. Only writes. See [Backups](#backups-db-dump-folder-archive-and-s3-upload). |
+| `folderArchive` | `folder-archive` | A folder of the tenant's own data folder to one `.tar.gz` (`tar`, no shell); its `backups/` and `tmp/` always left out. See [Backups](#backups-db-dump-folder-archive-and-s3-upload). |
 | `fileRead` | `file-read` | A CSV, text, Excel, JSON or NDJSON file as rows (format from the extension). `{ rows, count, columns, truncated }`, at most `maxRows` (50,000). |
 | `fileMove` | `file-move` | Move or copy a file into a folder (made if missing) or to a new name; `ifExists` as every saving step. `{ path, name, moved, skipped }`. |
 | `fileDelete` | `file-delete` | Delete one file, **permanently** (no trash; `file-move` to a "processed" folder is the reversible one). Never a folder. `ifMissing`: `fail` (default) or `skip`. `{ path, deleted, skipped }`. |
@@ -208,9 +210,9 @@ For `mode: 'table'` the source's declared column types (`getTableSchema`) are pa
 
 Message ids are IMAP UIDs **scoped to `folder`**, and a move changes the id — download and delete before moving.
 
-## Backups: `db-dump` and `s3-upload`
+## Backups: `db-dump`, `folder-archive` and `s3-upload`
 
-A database's backup is two steps: dump it to a file, then send the file away.
+A backup is two steps: make one file — a database's dump, or a folder's archive — then send the file away.
 
 ```js
 var dumped = await runAction({ name: 'db-dump', input: {
@@ -242,6 +244,20 @@ await runAction({ name: 's3-upload', input: {
 - **Written under `<name>.partial`, renamed only when the program ends cleanly.** A failure removes it and fails the step with the end of what the program said, the password taken out. A program that is not installed is named ("pg_dump is not installed on this server").
 - `system.signal` stops it (the program is killed); `system.onProgress({ bytes })` every second.
 
+**folder-archive**
+
+| input | |
+|---|---|
+| `folder` | A folder in the tenant's own folder, checked like every file step's (outside, `../`, a link pointing out: refused). Blank or `.`: all of it. |
+| `exclude` | Patterns left out, comma separated (`node_modules, *.log`) — tar's `--exclude`. One starting with `-` is refused. |
+| `fileName` | Default `<folder>-<UTC time>.tar.gz` (`all-…` for the whole folder), in the tenant's `backups/`. A name, not a path. |
+
+→ `{ filePath, fileName, bytes, sha256, folder, warning }`
+
+- **An app backs up only its own files.** The folder is inside the tenant's folder like every file step's, so an app (or the monitor) embedding this can never archive anything else on the server.
+- **Never its own `backups/` and `tmp/`:** the whole folder is archived entry by entry without them, and naming either (or a folder in them) is refused — a backup must not hold the backups before it.
+- `tar -czf` with an argument list, no shell; written as `<name>.partial`, renamed when tar ends. Exit 1 — GNU tar's "a file changed while it was read", the archive still whole — succeeds with `warning`; anything else removes the file and fails with the end of what tar said. `system.signal` kills tar.
+
 **s3-upload**
 
 | input | |
@@ -260,7 +276,7 @@ await runAction({ name: 's3-upload', input: {
   ```
 - Peers, optional: `@aws-sdk/client-s3` and `@aws-sdk/lib-storage` (`^3`). Missing → the step says to install them.
 
-`test/backup/` checks both: the dump programs with a stand-in on `PATH` (arguments, password only in the environment, a failure leaving no file), a real `pg_dump` restored with `pg_restore --list` when Postgres is here, and the upload against an S3 stand-in (one PUT, then parts, a SHA-256 checksum, never a read).
+`test/backup/` checks all three: `folder-archive` with a real `tar` (patterns left out, `backups/` and `tmp/` never in it, outside paths and links refused); the dump programs with a stand-in on `PATH` (arguments, password only in the environment, a failure leaving no file), a real `pg_dump` restored with `pg_restore --list` when Postgres is here, and the upload against an S3 stand-in (one PUT, then parts, a SHA-256 checksum, never a read).
 
 ## Data operation
 

package/lib/builtins/db/list-foreign-keys.js

@@ -0,0 +1,41 @@
+// db-list-foreign-keys action — the foreign keys between the tables of one
+// schema/database, each with its columns in key order: { name, table,
+// columns, refTable, refColumns }. What an app joins two tables on without
+// asking (the BI dataset canvas does). Only keys whose both tables are in the
+// schema db-list-tables lists. A small catalogue read, like db-list-tables.
+
+var dbDrivers = require('../../drivers/db');
+
+module.exports = {
+  name: 'db-list-foreign-keys',
+  description: 'List foreign keys between tables of a schema/database. Routes to the driver named by input.dbType.',
+  requires: [],   // per-driver requires checked at runtime once dbType is known
+
+  inputSchema: [
+    { name: 'dbType',     type: 'string', required: true, default: 'postgres', order: 1,
+      description: 'postgres | mysql | mssql | duckdb' },
+    { name: 'connection', type: 'object', required: true, order: 2,
+      description: 'Connection config: { host, port, user, password, database } (duckdb: { file })' },
+    { name: 'schema',     type: 'string', order: 3,
+      description: 'Schema to read (postgres public, duckdb main, mssql every schema, mysql the connection database by default)' }
+  ],
+
+  // Only reads the database's own catalogue, so the preview is the run.
+  preview: async function(ctx) { return { output: await module.exports.execute(ctx) }; },
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var driver = dbDrivers.getDriver(input.dbType);
+    dbDrivers.checkDriverRequires('db-list-foreign-keys', input.dbType, driver);
+    if (typeof driver.listForeignKeys !== 'function') {
+      throw new Error('db-list-foreign-keys: driver "' + input.dbType + '" does not implement listForeignKeys');
+    }
+
+    var pool = await driver.connect(input.connection);
+    try {
+      return { foreignKeys: await driver.listForeignKeys(pool, input.schema) };
+    } finally {
+      await driver.close(pool);
+    }
+  }
+};

package/lib/builtins/file/archive.js

@@ -0,0 +1,151 @@
+// folder-archive action — a folder of this company's data folder, packed into
+// one .tar.gz backup file (then s3-upload sends it away).
+//
+//   folder    inside the tenant's own folder (lib/dataDir.js), checked like
+//             every file step's: a path outside, ../ or a link pointing out is
+//             refused. '' or '.' is the whole tenant folder
+//   never     the tenant's own backups/ and tmp/ — a backup must not hold the
+//             backups before it, nor half-written spools. Archiving the whole
+//             folder names every other entry; naming backups/ or tmp/ (or a
+//             folder inside them) is refused
+//   exclude   patterns left out ("node_modules, *.log"), tar's --exclude; none
+//             may start with "-", which tar would read as an option
+//
+// `tar -czf` is RUN WITH AN ARGUMENT LIST, never a shell. The file is written
+// as <name>.partial and renamed only once tar ends: exit 0, or 1 — GNU tar's
+// "a file changed while it was read" (a log being written), where the archive
+// is whole — which comes back as `warning`. Anything else removes the file and
+// fails the step with the end of what tar said. A stop (system.signal) kills
+// tar. Written to the tenant's backups/: <slug>-<UTC time>.tar.gz.
+
+var fs = require('fs');
+var path = require('path');
+var crypto = require('crypto');
+var { spawn } = require('child_process');
+var dataDir = require('../../dataDir');
+
+var OUT_FOLDER = 'backups';
+var NEVER = ['backups', 'tmp'];
+var STDERR_KEEP = 2048;
+
+function refuse(message, code) {
+  var err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+function stamp(date) {
+  return date.toISOString().slice(0, 19).replace(/:/g, '-');
+}
+
+/** "uploads/2026" → "uploads-2026"; the whole folder → "all". */
+function slugOf(rel) {
+  return String(rel).replace(/^[./]+|\/+$/g, '').replace(/[^A-Za-z0-9._-]+/g, '-') || 'all';
+}
+
+/** "node_modules, *.log" → the patterns; one starting with "-" is refused. */
+function excludesOf(text) {
+  var list = (Array.isArray(text) ? text : String(text || '').split(/[\n,]/)).map(function(p) { return String(p).trim(); }).filter(Boolean);
+  list.forEach(function(p) {
+    if (p[0] === '-') throw refuse('folder-archive: the pattern "' + p + '" cannot start with "-".', 'BAD_ARGUMENT');
+  });
+  return list;
+}
+
+/** What tar is asked to pack: from the tenant folder, its entries except backups/ and tmp/; else the folder itself. */
+function targetOf(input) {
+  var root = fs.realpathSync(dataDir.tenantFolder());
+  var asked = String(input.folder === undefined || input.folder === null ? '' : input.folder).trim();
+  var dir = asked === '' || asked === '.' ? root : dataDir.resolve(asked, 'The folder');
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) throw refuse('"' + asked + '" is not a folder that exists.', 'NOT_A_FOLDER');
+  var rel = path.relative(root, dir);
+  var top = rel.split(path.sep)[0];
+  if (rel && NEVER.indexOf(top) >= 0) {
+    throw refuse('folder-archive: ' + top + '/ holds the backups and temporary files themselves — name a folder beside it.', 'PATH_NOT_ALLOWED');
+  }
+  if (!rel) {
+    var entries = fs.readdirSync(root).filter(function(n) { return NEVER.indexOf(n) < 0; }).sort();
+    if (!entries.length) throw refuse('folder-archive: there is nothing in this company\'s folder to back up.', 'NOTHING_TO_ARCHIVE');
+    return { dir: root, rel: '', cwd: root, members: entries };
+  }
+  return { dir: dir, rel: rel, cwd: path.dirname(dir), members: [path.basename(dir)] };
+}
+
+module.exports = {
+  name: 'folder-archive',
+  example: { filePath: '/data/app/backups/uploads-2026-11-13T02-00-05.tar.gz', fileName: 'uploads-2026-11-13T02-00-05.tar.gz', bytes: 10485760,
+    sha256: '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08', folder: 'uploads', warning: null },
+  description: 'Pack a folder of this company\'s data folder into one .tar.gz backup file (its backups/ and tmp/ always left out). Returns { filePath, fileName, bytes, sha256, folder, warning }.',
+  requires: [],   // tar is checked when it runs
+
+  inputSchema: [
+    { name: 'folder', type: 'string', order: 1,
+      description: 'A folder in this company\'s data folder, e.g. uploads. Blank or "." for all of it.' },
+    { name: 'exclude', type: 'string', order: 2,
+      description: 'Names or patterns to leave out, comma separated — e.g. node_modules, *.log.' },
+    { name: 'fileName', type: 'string', order: 3, group: 'File',
+      description: 'The archive\'s name. Default: <folder>-<time>.tar.gz.' }
+  ],
+  outputSchema: [
+    { name: 'filePath', type: 'string' }, { name: 'fileName', type: 'string' }, { name: 'bytes', type: 'number' },
+    { name: 'sha256', type: 'string' }, { name: 'folder', type: 'string' }, { name: 'warning', type: 'string' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var system = ctx.system || {};
+    var target = targetOf(input);
+    var excludes = excludesOf(input.exclude);
+    var outDir = dataDir.resolve(OUT_FOLDER, 'The backup folder');
+    fs.mkdirSync(outDir, { recursive: true });
+    var name = input.fileName ? String(input.fileName) : slugOf(target.rel) + '-' + stamp(new Date()) + '.tar.gz';
+    var filePath = dataDir.resolve(path.join(outDir, name), 'The backup file');
+    if (path.dirname(filePath) !== fs.realpathSync(outDir)) throw refuse('folder-archive: fileName "' + name + '" must be a name, not a path.', 'PATH_NOT_ALLOWED');
+    var partial = filePath + '.partial';
+
+    var args = ['-czf', partial].concat(excludes.map(function(p) { return '--exclude=' + p; }), ['-C', target.cwd, '--'], target.members);
+    var stderr = '';
+    var child;
+    var code = await new Promise(function(resolve, reject) {
+      try {
+        child = spawn('tar', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+      } catch (e) {
+        reject(e);
+        return;
+      }
+      child.on('error', function(e) { reject(e.code === 'ENOENT' ? refuse('tar is not installed on this server.', 'PROGRAM_NOT_FOUND') : e); });
+      child.stderr.on('data', function(d) { stderr = (stderr + d.toString()).slice(-STDERR_KEEP); });
+      var onAbort = function() { if (child.exitCode === null) child.kill('SIGTERM'); };
+      if (system.signal) {
+        if (system.signal.aborted) onAbort();
+        else system.signal.addEventListener('abort', onAbort, { once: true });
+      }
+      child.on('close', function(c, signal) {
+        if (system.signal) system.signal.removeEventListener('abort', onAbort);
+        if (signal) return reject(refuse('tar was stopped (' + signal + ').', 'ARCHIVE_FAILED'));
+        resolve(c);
+      });
+    }).catch(function(err) {
+      try { fs.unlinkSync(partial); } catch (_) {}
+      throw err;
+    });
+    var said = stderr.trim().split('\n').slice(-3).join(' ');
+    if (code !== 0 && code !== 1) {
+      try { fs.unlinkSync(partial); } catch (_) {}
+      throw refuse('tar ended with code ' + code + (said ? ': ' + said : ''), 'ARCHIVE_FAILED');
+    }
+    fs.renameSync(partial, filePath);
+    var hash = crypto.createHash('sha256');
+    await new Promise(function(resolve, reject) {
+      fs.createReadStream(filePath).on('data', function(d) { hash.update(d); }).on('end', resolve).on('error', reject);
+    });
+    return {
+      filePath: filePath, fileName: path.basename(filePath), bytes: fs.statSync(filePath).size, sha256: hash.digest('hex'),
+      folder: target.rel || '.', warning: code === 1 ? (said || 'some files changed while they were read') : null
+    };
+  },
+
+  // For tests.
+  _targetOf: targetOf,
+  _excludesOf: excludesOf
+};

package/lib/builtins/index.js

@@ -49,6 +49,8 @@ module.exports = {
   dbListViews:      require('./db/list-views'),
   dbListProcedures: require('./db/list-procedures'),
   dbListColumns:    require('./db/list-columns'),
+  // The foreign keys between a schema's tables, composite ones in key order.
+  dbListForeignKeys: require('./db/list-foreign-keys'),
 
   // File actions — factory-shaped for the same reason (meta store binding).
   fileUpload:   require('./file/upload'),
@@ -59,6 +61,9 @@ module.exports = {
   // One file to an S3 bucket, in parts, write-only. Peers: @aws-sdk/client-s3
   // and @aws-sdk/lib-storage — optional, lazy-required.
   s3Upload:     require('./file/s3-upload'),
+  // A folder of the tenant's own data folder to one .tar.gz backup file (tar,
+  // no shell; its backups/ and tmp/ always left out).
+  folderArchive: require('./file/archive'),
 
   // Email actions. Inbound routes to getInboundProvider(input.emailType)
   // (imap today), outbound to getOutboundProvider (smtp) — see

package/lib/drivers/db/duckdb.js

@@ -354,6 +354,7 @@ async function acquire(entry) {
 // own connection, and the time limit is a timer that does the same. A query
 // still waiting for a free connection is let go of before it ever runs.
 var stop = require('./stop');
+var foreignKeys = require('./foreignKeys');
 
 /** acquire(), unless the stop comes first; a connection that arrives too late goes straight back. */
 function acquireUnlessStopped(entry, signal) {
@@ -658,6 +659,28 @@ async function listTables(pool, schema) {
   return r.rows.map(function(row) { return row.table_name; });
 }
 
+// Foreign keys between this schema's tables — see foreignKeys.js.
+async function listForeignKeys(pool, schema) {
+  var r = await query(pool,
+    "SELECT constraint_index, table_name, constraint_column_names, referenced_table, referenced_column_names " +
+    "FROM duckdb_constraints() WHERE constraint_type = 'FOREIGN KEY' AND schema_name = $1 " +
+    'ORDER BY table_name, constraint_index',
+    [schema || 'main']);
+  var rows = [];
+  r.rows.forEach(function(row) {
+    // LIST columns: this driver hands them back as arrays.
+    var cols = row.constraint_column_names || [];
+    var refs = row.referenced_column_names || [];
+    cols.forEach(function(col, i) {
+      rows.push({ name: row.table_name + '_fk_' + row.constraint_index, table: row.table_name,
+        refTable: row.referenced_table, column: col, refColumn: refs[i] });
+    });
+  });
+  return foreignKeys.group(rows);
+}
+
+
+
 async function listViews(pool, schema) {
   var r = await query(pool,
     'SELECT table_name FROM information_schema.views WHERE table_schema = $1 ORDER BY table_name',
@@ -1039,6 +1062,7 @@ module.exports = {
 
   getTableSchema:  getTableSchema,
   listTables:      listTables,
+  listForeignKeys: listForeignKeys,
   listViews:       listViews,
   listProcedures:  listProcedures,
 

package/lib/drivers/db/foreignKeys.js

@@ -0,0 +1,26 @@
+// Foreign keys between the tables of one schema, as every SQL driver's
+// listForeignKeys returns them — what the BI dataset canvas joins two tables
+// on without asking. One entry per constraint, its columns in key order (a
+// composite key keeps every pair): { name, table, columns, refTable,
+// refColumns }. Each driver reads its own catalogue one row per column pair
+// and hands the rows here; only keys whose BOTH tables are in the schema
+// listTables lists, so every name is one listTables also returns.
+
+/** Rows of { name, table, refTable, column, refColumn }, in key order → one entry per key. */
+function group(rows) {
+  var byKey = {};
+  var out = [];
+  (rows || []).forEach(function(r) {
+    var key = r.table + '\u0000' + r.name;
+    var fk = byKey[key];
+    if (!fk) {
+      fk = byKey[key] = { name: r.name, table: r.table, columns: [], refTable: r.refTable, refColumns: [] };
+      out.push(fk);
+    }
+    fk.columns.push(r.column);
+    fk.refColumns.push(r.refColumn);
+  });
+  return out;
+}
+
+module.exports = { group: group };

package/lib/drivers/db/mssql.js

@@ -57,6 +57,7 @@ var NATIVE_TO_LOGICAL = {
 
 // Dates and times: one shared rule for every driver (dateValues.js).
 var dateValues = require('./dateValues');
+var foreignKeys = require('./foreignKeys');
 
 var INTERNAL_ID_COL       = '__xeplr_id__';
 var INTERNAL_MOVEMENT_COL = '__xeplr_movement_id__';
@@ -348,6 +349,25 @@ async function listTables(pool, schema) {
   return r.rows.map(function(row) { return row.name; });
 }
 
+// Foreign keys between this schema's tables — see foreignKeys.js.
+async function listForeignKeys(pool, schema) {
+  var r = await query(pool,
+    'SELECT fk.name AS name, t.name AS [table], rt.name AS refTable, ' +
+    'c.name AS [column], rc.name AS refColumn ' +
+    'FROM sys.foreign_keys fk ' +
+    'JOIN sys.foreign_key_columns fkc ON fkc.constraint_object_id = fk.object_id ' +
+    'JOIN sys.tables t ON t.object_id = fk.parent_object_id ' +
+    'JOIN sys.tables rt ON rt.object_id = fk.referenced_object_id ' +
+    'JOIN sys.columns c ON c.object_id = fkc.parent_object_id AND c.column_id = fkc.parent_column_id ' +
+    'JOIN sys.columns rc ON rc.object_id = fkc.referenced_object_id AND rc.column_id = fkc.referenced_column_id ' +
+    'WHERE (@p0 IS NULL OR (SCHEMA_NAME(t.schema_id) = @p0 AND SCHEMA_NAME(rt.schema_id) = @p0)) ' +
+    'ORDER BY t.name, fk.name, fkc.constraint_column_id',
+    [schema || null]
+  );
+  return foreignKeys.group(r.rows);
+}
+
+
 async function listViews(pool, schema) {
   var r = await query(pool,
     'SELECT TABLE_NAME AS name FROM INFORMATION_SCHEMA.TABLES ' +
@@ -545,6 +565,7 @@ module.exports = {
   // Introspection (used by uploader.reconcile + the db-list-* actions) + rollback
   getTableSchema:   getTableSchema,
   listTables:       listTables,
+  listForeignKeys: listForeignKeys,
   listViews:        listViews,
   listProcedures:   listProcedures,
   rollbackMovement: rollbackMovement,

package/lib/drivers/db/mysql.js

@@ -55,6 +55,7 @@ var NATIVE_TO_LOGICAL = {
 
 // Dates and times: one shared rule for every driver (dateValues.js).
 var dateValues = require('./dateValues');
+var foreignKeys = require('./foreignKeys');
 
 var INTERNAL_ID_COL       = '__xeplr_id__';
 var INTERNAL_MOVEMENT_COL = '__xeplr_movement_id__';
@@ -383,6 +384,21 @@ async function listTables(pool, schema) {
   return r.rows.map(function(row) { return row.name; });
 }
 
+// Foreign keys between this schema's tables — see foreignKeys.js.
+async function listForeignKeys(pool, schema) {
+  var r = await query(pool,
+    'SELECT CONSTRAINT_NAME AS name, TABLE_NAME AS `table`, REFERENCED_TABLE_NAME AS refTable, ' +
+    'COLUMN_NAME AS `column`, REFERENCED_COLUMN_NAME AS refColumn ' +
+    'FROM information_schema.KEY_COLUMN_USAGE ' +
+    'WHERE TABLE_SCHEMA = COALESCE(?, DATABASE()) AND REFERENCED_TABLE_NAME IS NOT NULL ' +
+    'AND REFERENCED_TABLE_SCHEMA = TABLE_SCHEMA ' +
+    'ORDER BY TABLE_NAME, CONSTRAINT_NAME, ORDINAL_POSITION',
+    [schema || null]
+  );
+  return foreignKeys.group(r.rows);
+}
+
+
 async function listViews(pool, schema) {
   var r = await query(pool,
     "SELECT TABLE_NAME AS name FROM information_schema.TABLES " +
@@ -577,6 +593,7 @@ module.exports = {
   // Introspection (used by uploader.reconcile + the db-list-* actions) + rollback
   getTableSchema:   getTableSchema,
   listTables:       listTables,
+  listForeignKeys: listForeignKeys,
   listViews:        listViews,
   listProcedures:   listProcedures,
   rollbackMovement: rollbackMovement,

package/lib/drivers/db/postgres.js

@@ -89,6 +89,7 @@ async function close(pool) {
 // time limit is statement_timeout, so Postgres enforces it even if this
 // process dies; our own timer, a little later, is only the backstop.
 var stop = require('./stop');
+var foreignKeys = require('./foreignKeys');
 var QUERY_CANCELED = '57014';
 var BACKSTOP_MS = 2000;
 
@@ -381,6 +382,25 @@ async function listTables(pool, schema) {
   return r.rows.map(function(row) { return row.table_name; });
 }
 
+// Foreign keys between this schema's tables — see foreignKeys.js.
+async function listForeignKeys(pool, schema) {
+  var r = await pool.query(
+    'SELECT c.conname AS name, t.relname AS "table", rt.relname AS "refTable", ' +
+    'a.attname AS "column", ra.attname AS "refColumn" ' +
+    'FROM pg_constraint c ' +
+    'JOIN pg_class t ON t.oid = c.conrelid JOIN pg_namespace n ON n.oid = t.relnamespace ' +
+    'JOIN pg_class rt ON rt.oid = c.confrelid JOIN pg_namespace rn ON rn.oid = rt.relnamespace ' +
+    'CROSS JOIN LATERAL unnest(c.conkey, c.confkey) WITH ORDINALITY AS k(col, refcol, ord) ' +
+    'JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.col ' +
+    'JOIN pg_attribute ra ON ra.attrelid = c.confrelid AND ra.attnum = k.refcol ' +
+    "WHERE c.contype = 'f' AND n.nspname = $1 AND rn.nspname = $1 " +
+    'ORDER BY t.relname, c.conname, k.ord',
+    [schema || 'public']
+  );
+  return foreignKeys.group(r.rows);
+}
+
+
 async function listViews(pool, schema) {
   var r = await pool.query(
     "SELECT table_name FROM information_schema.views " +
@@ -546,6 +566,7 @@ module.exports = {
   // Introspection (used by uploader.reconcile + the db-list-* actions)
   getTableSchema:  getTableSchema,
   listTables:      listTables,
+  listForeignKeys: listForeignKeys,
   listViews:       listViews,
   listProcedures:  listProcedures,
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/actions",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "description": "Named-action registry with typed inputs and safe invocation — plus built-in actions for HTTP, DB, files, email, spawn",
   "main": "index.js",
   "scripts": {