Source Admin

A local admin workspace for setting up, discovering, and inspecting database sources — MSSQL, MySQL, PostgreSQL, MongoDB, and CSV — with encrypted credentials and zero-config startup.

Run one npx command and get a browser-based admin UI for configuring database sources, running schema discovery, activating a mapping, and browsing tables. Credentials stay encrypted in a local metadata store. Built for a single trusted machine out of the box; hardenable for team or self-hosted deployments.

Table of Contents

• Features
• How It Works
• Quick Start
• Supported Sources
  • MSSQL
  • MySQL
  • PostgreSQL
  • MongoDB
  • CSV
• Configuration
• Self-Hosting & Security Notes
• Development
• Troubleshooting / FAQ
• Project Info

Features

• Five source types in one workspace — MSSQL, MySQL, PostgreSQL, MongoDB, and CSV (read-only) managed from the same UI.
• Schema discovery — each adapter queries native catalogs: information_schema for MySQL and PostgreSQL, pg_class.reltuples for Postgres row estimates, 100-document sampling for MongoDB, and header detection for CSV.
• Mapping activation — save multiple sources, mark one as globally active, and switch without re-entering credentials.
• Table inspector — deferred row counts and large-cell truncation keep the UI responsive on wide tables (src/lib/platform/cell-truncate.ts, src/lib/platform/row-count-cache.ts).
• Row deletion where safe — supported for MSSQL, MySQL, and PostgreSQL; MongoDB and CSV are read-only in this version.
• Encrypted credentials at rest — secrets encrypted with APP_CONFIG_ENCRYPTION_KEY (src/lib/platform/crypto.ts); admin passwords stored as salted scrypt hashes.
• Zero-config local trial — npx @codecanvascollective/source-admin generates runtime secrets automatically and keeps metadata outside the npm cache.
• Single-admin model — the first browser visit creates the admin account; signup closes afterward.

How It Works

1. Run npx @codecanvascollective/source-admin.
2. Open /admin/source, add a source, click Test Connection, then Discover.
3. Activate the source to set it as the globally active mapping.
4. Open /admin/tables to browse discovered tables or collections.

Quick Start

Requirements

• Node.js 24 or newer (see engines.node in package.json).

Run it

npx @codecanvascollective/source-admin

Then open http://127.0.0.1:3000/admin/source.

Override the bind address or port with flags or environment variables:

npx @codecanvascollective/source-admin --port 3001
npx @codecanvascollective/source-admin --host 0.0.0.0 --port 3000

SOURCE_ADMIN_HOST and SOURCE_ADMIN_PORT work as environment-variable equivalents.

First-run checklist

1. Create the local admin account in the browser (one-time; signup then closes).
2. Add a source on /admin/source.
3. Test Connection.
4. Discover the schema.
5. Activate the source.
6. Open /admin/tables to inspect discovered tables.

Supported Sources

Multiple sources can be saved; exactly one is globally active at a time. Credentials are encrypted at rest. When editing an existing source, leave the password or connection-string field blank to keep the stored secret.

MSSQL

SQL Login — most portable option:

Server=localhost\SQLEXPRESS;Database=YourDatabase;User Id=your_login;Password=your_password;Encrypt=false;TrustServerCertificate=true;

Windows Authentication — pick Windows as the auth mode in the UI, set the ODBC driver if needed, and use:

Server=localhost\SQLEXPRESS;Database=YourDatabase;Trusted_Connection=Yes;Encrypt=false;TrustServerCertificate=true;

Windows Auth depends on platform-specific ODBC / native driver setup and the optional msnodesqlv8 dependency.

MySQL

Enter host, port (default 3306), database, user, password, and SSL mode (Disabled, Required, or Verify CA). Schema discovery uses information_schema; approximate row counts come from TABLE_ROWS. Row deletion is supported.

PostgreSQL

Enter host, port (default 5432), database, schema (default public), user, password, and SSL mode. Discovery reads information_schema.columns and pg_class.reltuples for approximate row counts. Row deletion runs as batched DELETE ... WHERE ctid IN (...) statements.

MongoDB

Enter a mongodb:// or mongodb+srv:// connection string, the target database name, an optional auth source, and toggle TLS. Collections play the role of tables. Schema is inferred by sampling 100 documents per collection and flattening nested fields to dotted paths (for example, user.address.city). Read-only in this version.

CSV

Enter a local file path readable by the server process. UTF-8 is expected; the delimiter is auto-detected (comma, tab, pipe, or semicolon). Header rows are used when detected; otherwise Column 1, Column 2, ... are generated. Each file is one read-only table. Read-only in this version.

Configuration

CLI flags

| Flag | Description | | --------- | -------------------------------------------- | | --port | Port to bind (default 3000). | | --host | Host to bind (default 127.0.0.1). |

Environment variables

| Variable | Purpose | | --------------------------- | ----------------------------------------------------------------------------------------- | | NEXTAUTH_URL | Public URL of the deployment (required for hosted use). | | NEXTAUTH_SECRET | NextAuth signing secret. Set a long random value for anything beyond a local trial. | | APP_CONFIG_DB_PATH | Path to the metadata sqlite database. Default lives under the runtime data directory. | | APP_CONFIG_ENCRYPTION_KEY | Key used to encrypt stored source credentials. Set a long random value for hosted use. | | SOURCE_ADMIN_HOME | Runtime data directory (metadata DB, generated secrets). | | SOURCE_ADMIN_HOST | Host to bind (alternative to --host). | | SOURCE_ADMIN_PORT | Port to bind (alternative to --port). | | SOURCE_ADMIN_MYSQL_POOL | MySQL connection pool size (default 20). | | SOURCE_ADMIN_PG_POOL | PostgreSQL connection pool size (default 20). | | DEV_AUTH_BYPASS | Local development only. Skips auth. Never enable on anything reachable off localhost. |

Example .env.local for hosted deployment

NEXTAUTH_URL=https://your-host.example
NEXTAUTH_SECRET=replace-with-a-long-random-secret

APP_CONFIG_DB_PATH=.data/source-admin-metadata.sqlite
APP_CONFIG_ENCRYPTION_KEY=replace-with-a-long-random-secret

Self-Hosting & Security Notes

• Set strong NEXTAUTH_SECRET and APP_CONFIG_ENCRYPTION_KEY values for anything beyond a local trial.
• Do not enable DEV_AUTH_BYPASS on a machine reachable beyond localhost.
• Put the app behind a reverse proxy for any LAN or internet-exposed deployment.
• Docker is not on the first-release path — use npx or any Node 24+ host.
• The first local account becomes the admin account; signup closes after that until the metadata DB is reset.
• Report vulnerabilities privately — see SECURITY.md.

Development

npm install
cp .env.example .env.local
npm run dev

Create the first admin account in the browser, or set DEV_AUTH_BYPASS=true in .env.local for local-only development.

Check commands:

npm run typecheck
npm run lint
npm run test
npm run build

See CONTRIBUTING.md for packaging scripts and additional guidance.

Troubleshooting / FAQ

Port 3000 is already in use. Pass --port 3001 or set SOURCE_ADMIN_PORT=3001.

Signup is closed and I forgot the admin password. Reset the metadata sqlite under SOURCE_ADMIN_HOME (or at the path set by APP_CONFIG_DB_PATH). The next launch re-opens signup.

MSSQL Windows Authentication fails. Windows Auth depends on the optional msnodesqlv8 native driver and a matching ODBC driver on the host. SQL Login with a connection string is usually simpler and more portable.

MSSQL TLS / certificate error on localhost. For local SQL Server instances, use Encrypt=false;TrustServerCertificate=true; in the connection string.

Where is my data stored? Runtime data (metadata DB, generated secrets) lives under the user data directory by default. Override it with SOURCE_ADMIN_HOME. The metadata sqlite path itself is controlled by APP_CONFIG_DB_PATH.

npx fails with a Node version error. Node.js 24 or newer is required (engines.node in package.json). Upgrade Node and retry.

The Tables page feels slow on wide tables. Row counts are deferred and large cell values are truncated by design (src/lib/platform/row-count-cache.ts, src/lib/platform/cell-truncate.ts). Click a truncated cell to view its full value.

Can I expose this on a LAN or the internet? Yes, with strong NEXTAUTH_SECRET and APP_CONFIG_ENCRYPTION_KEY, DEV_AUTH_BYPASS disabled, and a reverse proxy in front. See Self-Hosting & Security Notes.

Row delete is disabled for MongoDB / CSV. Intentional in this version — those sources are treated as read-only.

Project Info

• Security: SECURITY.md
• Contributing: CONTRIBUTING.md
• Issues: https://github.com/CodeCanvasCollective/source-admin/issues
• License: Apache-2.0 — see LICENSE