Description
Plug Database n8n Workspace
Agent Action I/O and SQL Extensions provide faithful binary actions, source
inspection and durable SQL operations over REST, Socket and relay. Start with
communication patterns for channel selection and
workflow use and safety for credentials and recovery.
node/actions/workflows/publish.yml/badge.svg?branch=main”>
!docs/socket, including SQL over Socket, custom events, the continuous trigger, PayloadFrame, examples, and troubleshooting.
Local Development
Recommended Node.js version:
24.18.0 (see .nvmrc / .node-version; workspace engines is >=24.18.0 <25)Main commands:
npm install --global [email protected]
npm ci
npm run verify
npm run test:e2e
npm run pack:check
Useful commands:
npm run changeset
npm run changeset:status
npm run test:coverage
npm run scan:public
AI capabilities and compatibility
Plug MCP Server validates and executes authored capabilities; Plug AI Hub emits prompts and governance wiring. This is an n8n contract, not an HTTP/stdio MCP daemon. See MCP Hub.
Packaged installation checks cover n8n-workflow 2.16.0 and 2.45.4, including a native-runtime profile on 2.45.4. The wildcard peer dependency follows host installation conventions; it is not evidence of compatibility with every host version. See testing strategy.
Documentation
Verification Path
n8n-nodes-plug-database now ships the full Plug surface, including Socket and local tool runtime dependencies. scan:public is still useful, but do not read it as an n8n Cloud verification guarantee.
After GitHub Actions verifies a newly published npm version, the dedicated Scan Public Package workflow runs automatically. You can also run it manually or execute:
npm run scan:public
This runs the official @n8n/scan-community-package check against the published npm package.
Project Rules
Read AGENTS.md first, then the source rules in .cursor/rules.
<br />
<a href=){kind=link}
</code></li>
<li><code>Password</code></li>
<li>optional <code>Default Agent ID</code></li>
<li>optional <code>Default Client Token</code></li>
<li>optional <code>Payload Signing Key</code></li>
<li>optional <code>Payload Signing Key ID</code></li>
<p>All authenticated Plug surfaces share:</p>
<li><code>Plug Database Account API</code></li>
<p>Saved credentials created by older package versions remain supported through compatibility aliases. The legacy internal credential names <code>plugDatabaseApi</code>, <code>plugDatabaseAdvancedApi</code>, <code>plugDatabaseClientApi</code>, and <code>plugDatabaseUserApi</code> extend <code>plugDatabaseAccountApi</code>, so n8n can still show previously saved credentials in nodes that use the shared account credential.</p>
<p>Saved workflows that reference removed advanced node type names must be migrated:</p>
<li><code>plugDatabaseAdvanced</code> -> <code>plugDatabase</code></li>
<li><code>plugDatabaseAdvancedSocketEventTrigger</code> -> <code>plugDatabaseSocketEventTrigger</code></li>
<li><code>plugDatabaseAdvancedPdf</code> and <code>plugDatabaseAdvancedBarcode</code> -> <code>Plug Database</code> with <code>Resource = Tools</code></li>
<p>For exported n8n workflow JSON files, run a dry run first and then write changes after reviewing the output:</p>
<pre><code>npm run migrate:workflows -- ./workflow.json
npm run migrate:workflows -- --write ./workflow.json
</code></pre>
<p>The migrator updates legacy node <code>type</code> values, maps legacy credential keys (<code>plugDatabaseAdvancedApi</code>, <code>plugDatabaseApi</code>, <code>plugDatabaseClientApi</code>, <code>plugDatabaseUserApi</code>) to <code>plugDatabaseAccountApi</code> on each node, and can normalize hidden PDF/barcode nodes into <code>Plug Database</code> tools.</p>
<li><code>--check</code> exits with code <code>1</code> when any migration would apply (use in CI to ensure exports are already migrated).</li>
<li><code>--backup</code> with <code>--write</code> writes <code><file>.bak</code> before overwriting each in-place export.</li>
<li><code>--write --output-dir <dir></code> writes migrated JSON under <code><dir></code> while preserving paths relative to the current working directory; originals are left unchanged.</li>
<p>Credential remapping keeps the same n8n credential <code>id</code>; ensure the instance still has a compatible saved credential for <code>Plug Database Account API</code>.</p>
<p>The API base URL is fixed to:</p>
<li><code>https://plug-server.se7esistemassinop.com.br/api/v1</code></li>
<p>The implementation handles login, token refresh, REST execution, consumer Socket execution, binary frame decoding, gzip handling, and normalized JSON output.</p>
<p><code>Plug Database</code> starts with <code>Resource</code>, then <code>Operation</code>.</p>
<p>Resources:</p>
<li><code>SQL</code></li>
<li><code>Client Access</code></li>
<li><code>User Access</code></li>
<li><code>Tools</code></li>
<p>For SQL, <code>Channel = Socket</code> prefers <code>agents:command</code> on <code>/consumers</code>, with relay fallback when the newer transport does not answer. Large Socket streams are protected by local buffer guardrails.</p>
<p>Tools include PDF/document conversion, image operations, barcode read/generation, CPF/CNPJ and UUID helpers, JSON/data utilities, security helpers, date/value helpers, SQL/socket payload helpers, REST or Socket custom event publishing, and one-shot Socket Event waiting.</p>
<p>Triggers stay as separate n8n nodes because n8n activates them through <code>trigger()</code> or webhook lifecycle methods, while <code>Plug Database</code> is an execution node that runs through <code>execute()</code>. They share the same package and naming prefix, but cannot be embedded as normal operations without losing trigger behavior.</p>
<p><code>Plug Database Socket Event Trigger</code> listens on <code>/consumers</code> for exact <code>client:custom.*</code> events or <code>client:agent.profile.updated</code>.</p>
<p><code>Plug Database Plura.ai Automations Trigger</code> receives webhook events when a Plura.ai automation node executes.</p>
<p>Detailed Socket documentation is available in <a href=){kind=link}