@luckymingxuan/dbcli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mingxuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,2 @@
+# dbcli
+A personal database CLI giving AI full access to autonomously create, read, and store data.

package/dist/commands/connect.d.ts

@@ -0,0 +1,23 @@
+interface ConnectionInfo {
+    url: string;
+    database: string;
+    host: string;
+    port: number;
+    username: string;
+    password: string;
+    lastConnected: string;
+    enabled: boolean;
+}
+export declare function getConnections(): Map<string, ConnectionInfo>;
+export declare function getActiveConnection(): Promise<ConnectionInfo | null>;
+export declare function getConnectionByName(name: string): Promise<ConnectionInfo | null>;
+export declare function showConnections(): Promise<void>;
+export declare function deleteConnection(name: string): Promise<void>;
+export declare function connect(nameUrl: string, options?: {
+    username?: string;
+    password?: string;
+    current?: boolean;
+}): Promise<void>;
+export declare function disconnect(name: string): Promise<void>;
+export declare function logout(name: string): Promise<void>;
+export {};

package/dist/commands/connect.js

@@ -0,0 +1,220 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { PostgresDriver } from '../drivers/postgres.js';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+const CONFIG_DIR = path.join(os.homedir(), '.dbcli');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'connections.json');
+let connections = new Map();
+async function loadConnections() {
+    try {
+        await fs.mkdir(CONFIG_DIR, { recursive: true });
+        const data = await fs.readFile(CONFIG_FILE, 'utf-8');
+        const parsed = JSON.parse(data);
+        connections = new Map(Object.entries(parsed));
+    }
+    catch {
+        connections = new Map();
+    }
+}
+async function saveConnections() {
+    await fs.mkdir(CONFIG_DIR, { recursive: true });
+    const obj = Object.fromEntries(connections);
+    await fs.writeFile(CONFIG_FILE, JSON.stringify(obj, null, 2), 'utf-8');
+}
+export function getConnections() {
+    return connections;
+}
+export async function getActiveConnection() {
+    await loadConnections();
+    for (const conn of connections.values()) {
+        if (conn.enabled) {
+            return conn;
+        }
+    }
+    return null;
+}
+export async function getConnectionByName(name) {
+    await loadConnections();
+    return connections.get(name) || null;
+}
+async function promptCredentials() {
+    const answers = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'username',
+            message: 'Username:',
+            default: 'postgres',
+        },
+        {
+            type: 'password',
+            name: 'password',
+            message: 'Password:',
+            mask: '*',
+        },
+    ]);
+    return answers;
+}
+function isUrl(str) {
+    return str.includes('://');
+}
+function buildUrl(info, username, password) {
+    return `postgresql://${username}:${password}@${info.host}:${info.port}/${info.database}`;
+}
+export async function showConnections() {
+    await loadConnections();
+    if (connections.size === 0) {
+        console.log(chalk.yellow('No saved connections.'));
+        console.log(chalk.cyan('Use "dbcli connect <url>" to add a new connection.'));
+        return;
+    }
+    const activeConnection = Array.from(connections.values()).find((conn) => conn.enabled);
+    if (activeConnection) {
+        console.log(chalk.green(`Current connected database: "${activeConnection.database}" (user: ${activeConnection.username})`));
+    }
+    else {
+        console.log(chalk.yellow('No database is currently connected.'));
+    }
+    console.log(chalk.cyan('Saved connections:'));
+    const rows = Array.from(connections.entries()).map(([name, info]) => ({
+        username: info.username || '-',
+        database: info.database,
+        host: info.host,
+        port: info.port,
+        status: info.enabled ? 'enabled' : 'disabled',
+        lastConnected: info.lastConnected,
+    }));
+    console.table(rows);
+}
+export async function deleteConnection(name) {
+    await loadConnections();
+    if (!connections.has(name)) {
+        console.error(chalk.red(`Connection "${name}" not found.`));
+        process.exit(1);
+    }
+    connections.delete(name);
+    await saveConnections();
+    console.log(chalk.yellow(`Connection "${name}" deleted.`));
+}
+export async function connect(nameUrl, options) {
+    await loadConnections();
+    let database;
+    let host;
+    let port;
+    let existing = null;
+    let urlUsername = '';
+    let urlPassword = '';
+    if (isUrl(nameUrl)) {
+        const url = new URL(nameUrl);
+        database = url.pathname.slice(1) || 'postgres';
+        host = url.hostname;
+        port = parseInt(url.port) || 5432;
+        urlUsername = url.username;
+        urlPassword = url.password;
+        existing = connections.get(database) || null;
+    }
+    else {
+        database = nameUrl;
+        existing = connections.get(database) || null;
+        if (!existing) {
+            console.error(chalk.red(`Connection "${database}" not found.`));
+            console.log(chalk.cyan('Use "dbcli connect <url>" to add a new connection.'));
+            process.exit(1);
+        }
+        host = existing.host;
+        port = existing.port;
+    }
+    let credentials;
+    if (options?.current) {
+        const activeConn = Array.from(connections.values()).find((conn) => conn.enabled);
+        if (!activeConn) {
+            console.error(chalk.red('No currently connected database found.'));
+            process.exit(1);
+        }
+        credentials = { username: activeConn.username, password: activeConn.password };
+    }
+    else if (options?.username && options?.password) {
+        credentials = { username: options.username, password: options.password };
+    }
+    else if (urlUsername || urlPassword) {
+        credentials = { username: urlUsername, password: urlPassword };
+    }
+    else if (existing && existing.username && existing.password) {
+        const useExisting = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'value',
+                message: `You have an existing account "${existing.username}". Enter "y" to use it or anything else to re-login:`,
+                default: 'y',
+            },
+        ]);
+        if (useExisting.value.toLowerCase() === 'y') {
+            credentials = { username: existing.username, password: existing.password };
+        }
+        else {
+            credentials = await promptCredentials();
+        }
+    }
+    else {
+        credentials = await promptCredentials();
+    }
+    let finalUrl;
+    if (existing) {
+        finalUrl = buildUrl(existing, credentials.username, credentials.password);
+    }
+    else {
+        finalUrl = `postgresql://${credentials.username}:${credentials.password}@${host}:${port}/${database}`;
+    }
+    const driver = new PostgresDriver();
+    try {
+        console.log(chalk.cyan(`Connecting to db("${database}")...`));
+        await driver.connect(finalUrl);
+        for (const conn of connections.values()) {
+            conn.enabled = false;
+        }
+        const connectionInfo = {
+            url: `postgresql://${host}:${port}/${database}`,
+            database,
+            host,
+            port,
+            username: credentials.username,
+            password: credentials.password,
+            lastConnected: new Date().toISOString(),
+            enabled: true,
+        };
+        connections.set(database, connectionInfo);
+        await saveConnections();
+        console.log(chalk.green(`Connected to db("${database}") as user("${credentials.username}") successfully!`));
+        process.exit(0);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(`Connection failed: ${message}`));
+        process.exit(1);
+    }
+}
+export async function disconnect(name) {
+    await loadConnections();
+    if (!connections.has(name)) {
+        console.error(chalk.red(`Connection "${name}" not found.`));
+        process.exit(1);
+    }
+    const conn = connections.get(name);
+    conn.enabled = false;
+    await saveConnections();
+    console.log(chalk.yellow(`Disconnected from "${name}".`));
+}
+export async function logout(name) {
+    await loadConnections();
+    if (!connections.has(name)) {
+        console.error(chalk.red(`Connection "${name}" not found.`));
+        process.exit(1);
+    }
+    const conn = connections.get(name);
+    conn.enabled = false;
+    conn.username = '';
+    conn.password = '';
+    await saveConnections();
+    console.log(chalk.yellow(`Logged out from "${name}". Username and password cleared.`));
+}

package/dist/commands/query.d.ts

@@ -0,0 +1 @@
+export declare function executeQuery(sql: string): Promise<void>;

package/dist/commands/query.js

@@ -0,0 +1,45 @@
+import chalk from 'chalk';
+import { PostgresDriver } from '../drivers/postgres.js';
+import { getActiveConnection } from './connect.js';
+async function getActiveDriver() {
+    const activeConn = await getActiveConnection();
+    if (!activeConn) {
+        return null;
+    }
+    const url = `postgresql://${activeConn.username}:${activeConn.password}@${activeConn.host}:${activeConn.port}/${activeConn.database}`;
+    const driver = new PostgresDriver();
+    await driver.connect(url);
+    const connName = activeConn.database;
+    return { driver, connName };
+}
+export async function executeQuery(sql) {
+    const result = await getActiveDriver();
+    if (!result) {
+        console.log(chalk.red('No active database connection.'));
+        console.log(chalk.cyan('Please use "dbcli connect <url>" to connect to a database first.'));
+        process.exit(1);
+    }
+    const { driver, connName } = result;
+    try {
+        console.log(chalk.gray(`Executing on database "${connName}":`));
+        console.log(chalk.cyan(sql));
+        console.log();
+        const queryResult = await driver.query(sql);
+        if (queryResult.rows.length === 0) {
+            console.log(chalk.yellow(`Query executed successfully. No rows returned.`));
+            console.log(chalk.gray(`Row count: ${queryResult.rowCount}`));
+        }
+        else {
+            console.table(queryResult.rows);
+            console.log(chalk.gray(`Total: ${queryResult.rows.length} row(s)`));
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(`Query failed: ${message}`));
+        process.exit(1);
+    }
+    finally {
+        await driver.disconnect();
+    }
+}

package/dist/commands/tables.d.ts

@@ -0,0 +1,2 @@
+export declare function listTables(): Promise<void>;
+export declare function describeTable(tableName: string): Promise<void>;

package/dist/commands/tables.js

@@ -0,0 +1,67 @@
+import chalk from 'chalk';
+import { PostgresDriver } from '../drivers/postgres.js';
+import { getActiveConnection } from './connect.js';
+async function getActiveDriver() {
+    const activeConn = await getActiveConnection();
+    if (!activeConn) {
+        return null;
+    }
+    const url = `postgresql://${activeConn.username}:${activeConn.password}@${activeConn.host}:${activeConn.port}/${activeConn.database}`;
+    const driver = new PostgresDriver();
+    await driver.connect(url);
+    const connName = activeConn.database;
+    return { driver, connName };
+}
+export async function listTables() {
+    const result = await getActiveDriver();
+    if (!result) {
+        console.log(chalk.red('No active database connection.'));
+        console.log(chalk.cyan('Please use "dbcli connect <url>" to connect to a database first.'));
+        process.exit(1);
+    }
+    const { driver, connName } = result;
+    try {
+        const tables = await driver.listTables();
+        if (tables.length === 0) {
+            console.log(chalk.yellow(`No tables found in database "${connName}".`));
+        }
+        else {
+            console.log(chalk.cyan(`Tables in database "${connName}":`));
+            console.table(tables);
+        }
+    }
+    finally {
+        await driver.disconnect();
+    }
+}
+export async function describeTable(tableName) {
+    const result = await getActiveDriver();
+    if (!result) {
+        console.log(chalk.red('No active database connection.'));
+        console.log(chalk.cyan('Please use "dbcli connect <url>" to connect to a database first.'));
+        process.exit(1);
+    }
+    const { driver, connName } = result;
+    try {
+        const columns = await driver.describeTable('public', tableName);
+        if (columns.length === 0) {
+            console.log(chalk.yellow(`Table "${tableName}" not found in database "${connName}".`));
+        }
+        else {
+            console.log(chalk.cyan(`Structure of table "${tableName}" in database "${connName}":`));
+            console.table(columns);
+            const hasDescriptions = columns.some(col => col.description);
+            if (hasDescriptions) {
+                console.log(chalk.gray('\nColumn descriptions:'));
+                columns.forEach(col => {
+                    if (col.description) {
+                        console.log(`  ${chalk.white(col.name)}: ${chalk.gray(col.description)}`);
+                    }
+                });
+            }
+        }
+    }
+    finally {
+        await driver.disconnect();
+    }
+}

package/dist/drivers/interface.d.ts

@@ -0,0 +1,28 @@
+export interface QueryResult {
+    rows: Record<string, unknown>[];
+    rowCount: number;
+    fields: FieldInfo[];
+}
+export interface FieldInfo {
+    name: string;
+    dataTypeID: number;
+}
+export interface TableInfo {
+    schema: string;
+    name: string;
+}
+export interface ColumnInfo {
+    name: string;
+    dataType: string;
+    isNullable: boolean;
+    defaultValue: string | null;
+    description: string | null;
+}
+export interface DatabaseDriver {
+    connect(url: string): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    query(sql: string): Promise<QueryResult>;
+    listTables(): Promise<TableInfo[]>;
+    describeTable(schema: string, table: string): Promise<ColumnInfo[]>;
+}

package/dist/drivers/interface.js

@@ -0,0 +1 @@
+export {};

package/dist/drivers/postgres.d.ts

@@ -0,0 +1,12 @@
+import type { DatabaseDriver, QueryResult, TableInfo, ColumnInfo } from './interface.js';
+export declare class PostgresDriver implements DatabaseDriver {
+    private client;
+    private pool;
+    private connected;
+    connect(url: string): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    query(sql: string, params?: unknown[]): Promise<QueryResult>;
+    listTables(): Promise<TableInfo[]>;
+    describeTable(schema: string, table: string): Promise<ColumnInfo[]>;
+}

package/dist/drivers/postgres.js

@@ -0,0 +1,86 @@
+/*
+ * @Author: Mingxuan songmingxuan936@gmail.com
+ * @Date: 2026-04-05 17:01:59
+ * @LastEditors: Mingxuan songmingxuan936@gmail.com
+ * @LastEditTime: 2026-04-05 17:42:59
+ * @FilePath: /dbcli/src/drivers/postgres.ts
+ * @Description:
+ *
+ * Copyright (c) 2026 by ${git_name_email}, All Rights Reserved.
+ */
+import pg from 'pg';
+export class PostgresDriver {
+    client = null;
+    pool = null;
+    connected = false;
+    async connect(url) {
+        const connectionUrl = new URL(url);
+        this.pool = new pg.Pool({
+            host: connectionUrl.hostname,
+            port: parseInt(connectionUrl.port) || 5432,
+            user: connectionUrl.username,
+            password: connectionUrl.password,
+            database: connectionUrl.pathname.slice(1) || 'postgres',
+            ssl: connectionUrl.searchParams.get('sslmode') === 'require' ? { rejectUnauthorized: false } : undefined,
+        });
+        this.client = await this.pool.connect();
+        this.connected = true;
+    }
+    async disconnect() {
+        if (this.client) {
+            this.client.release();
+            this.client = null;
+        }
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = null;
+        }
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    async query(sql, params) {
+        if (!this.client) {
+            throw new Error('Not connected to database');
+        }
+        const result = await this.client.query(sql, params);
+        return {
+            rows: result.rows,
+            rowCount: result.rowCount ?? 0,
+            fields: result.fields.map((f) => ({
+                name: f.name,
+                dataTypeID: f.dataTypeID,
+            })),
+        };
+    }
+    async listTables() {
+        const result = await this.query(`
+      SELECT schemaname as schema, tablename as name
+      FROM pg_tables
+      WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+      ORDER BY schemaname, tablename
+    `);
+        return result.rows;
+    }
+    async describeTable(schema, table) {
+        const result = await this.query(`
+      SELECT
+        a.attname as name,
+        format_type(a.atttypid, a.atttypmod) as data_type,
+        CASE WHEN a.attnotnull THEN 'NO' ELSE 'YES' END as is_nullable,
+        pg_get_expr(ad.adbin, a.attrelid) as default_value,
+        col_description(a.attrelid, a.attnum) as description
+      FROM pg_attribute a
+      JOIN pg_class c ON c.oid = a.attrelid
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      LEFT JOIN pg_attrdef ad ON ad.adrelid = a.attrelid AND ad.adnum = a.attnum
+      WHERE n.nspname = $1
+        AND c.relname = $2
+        AND a.attnum > 0
+        AND NOT a.attisdropped
+      ORDER BY a.attnum
+    `, [schema, table]);
+        return result.rows;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,74 @@
+import { Command } from 'commander';
+import { connect, disconnect, logout, showConnections as statusConnections, deleteConnection } from './commands/connect.js';
+import { listTables, describeTable } from './commands/tables.js';
+import { executeQuery } from './commands/query.js';
+const program = new Command();
+program
+    .name('dbcli')
+    .description('Database CLI tool')
+    .version('0.1.0')
+    .addHelpCommand(false);
+program
+    .command('connect')
+    .description('Connect to a database (-u <user> -p <pass> for credentials, -c to use current)')
+    .argument('<db-name|url>', 'Connection name (for existing) or full URL (for new connection)')
+    .option('-u, --username <username>', 'Username for authentication')
+    .option('-p, --password <password>', 'Password for authentication')
+    .option('-c, --current', 'Use credentials from currently connected database')
+    .action(async (nameUrl, options) => {
+    await connect(nameUrl, options);
+});
+program
+    .option('-s, --status', 'Show all saved connections status')
+    .action(async (options, cmd) => {
+    if (cmd.args && cmd.args.length > 0) {
+        console.error(`error: unknown command '${cmd.args[0]}'`);
+        process.exit(1);
+    }
+    if (options.status) {
+        await statusConnections();
+        process.exit(0);
+    }
+});
+program
+    .command('disconnect')
+    .description('Disconnect from a database (keeps credentials)')
+    .argument('<db-name>', 'Connection name to disconnect')
+    .action(async (name) => {
+    await disconnect(name);
+});
+program
+    .command('logout')
+    .description('Logout from a connection (clears credentials)')
+    .argument('<db-name>', 'Connection name to logout')
+    .action(async (name) => {
+    await logout(name);
+});
+program
+    .command('delete')
+    .description('Delete a saved connection completely')
+    .argument('<db-name>', 'Connection name to delete')
+    .action(async (name) => {
+    await deleteConnection(name);
+});
+program
+    .command('tables')
+    .description('List all tables in the connected database')
+    .action(async () => {
+    await listTables();
+});
+program
+    .command('describe')
+    .description('Show the structure of a table')
+    .argument('<table>', 'Table name to describe')
+    .action(async (table) => {
+    await describeTable(table);
+});
+program
+    .command('query')
+    .description('Execute a SQL query')
+    .argument('<sql>', 'SQL query to execute (use quotes for complex queries)')
+    .action(async (sql) => {
+    await executeQuery(sql);
+});
+program.parse();

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@luckymingxuan/dbcli",
+  "version": "0.1.0",
+  "description": "Database CLI tool",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "dbcli": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^11.1.0",
+    "inquirer": "^13.3.2",
+    "pg": "^8.11.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/pg": "^8.10.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  }
+}

package/src/commands/connect.ts

@@ -0,0 +1,259 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { PostgresDriver } from '../drivers/postgres.js';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+
+interface ConnectionInfo {
+  url: string;
+  database: string;
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  lastConnected: string;
+  enabled: boolean;
+}
+
+const CONFIG_DIR = path.join(os.homedir(), '.dbcli');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'connections.json');
+
+let connections: Map<string, ConnectionInfo> = new Map();
+
+async function loadConnections(): Promise<void> {
+  try {
+    await fs.mkdir(CONFIG_DIR, { recursive: true });
+    const data = await fs.readFile(CONFIG_FILE, 'utf-8');
+    const parsed = JSON.parse(data) as Record<string, ConnectionInfo>;
+    connections = new Map(Object.entries(parsed));
+  } catch {
+    connections = new Map();
+  }
+}
+
+async function saveConnections(): Promise<void> {
+  await fs.mkdir(CONFIG_DIR, { recursive: true });
+  const obj = Object.fromEntries(connections);
+  await fs.writeFile(CONFIG_FILE, JSON.stringify(obj, null, 2), 'utf-8');
+}
+
+export function getConnections(): Map<string, ConnectionInfo> {
+  return connections;
+}
+
+export async function getActiveConnection(): Promise<ConnectionInfo | null> {
+  await loadConnections();
+  for (const conn of connections.values()) {
+    if (conn.enabled) {
+      return conn;
+    }
+  }
+  return null;
+}
+
+export async function getConnectionByName(name: string): Promise<ConnectionInfo | null> {
+  await loadConnections();
+  return connections.get(name) || null;
+}
+
+async function promptCredentials(): Promise<{ username: string; password: string }> {
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'username',
+      message: 'Username:',
+      default: 'postgres',
+    },
+    {
+      type: 'password',
+      name: 'password',
+      message: 'Password:',
+      mask: '*',
+    },
+  ]);
+  return answers;
+}
+
+function isUrl(str: string): boolean {
+  return str.includes('://');
+}
+
+function buildUrl(info: ConnectionInfo, username: string, password: string): string {
+  return `postgresql://${username}:${password}@${info.host}:${info.port}/${info.database}`;
+}
+
+export async function showConnections(): Promise<void> {
+  await loadConnections();
+
+  if (connections.size === 0) {
+    console.log(chalk.yellow('No saved connections.'));
+    console.log(chalk.cyan('Use "dbcli connect <url>" to add a new connection.'));
+    return;
+  }
+
+  const activeConnection = Array.from(connections.values()).find((conn) => conn.enabled);
+  if (activeConnection) {
+    console.log(chalk.green(`Current connected database: "${activeConnection.database}" (user: ${activeConnection.username})`));
+  } else {
+    console.log(chalk.yellow('No database is currently connected.'));
+  }
+
+  console.log(chalk.cyan('Saved connections:'));
+  const rows = Array.from(connections.entries()).map(([name, info]) => ({
+    username: info.username || '-',
+    database: info.database,
+    host: info.host,
+    port: info.port,
+    status: info.enabled ? 'enabled' : 'disabled',
+    lastConnected: info.lastConnected,
+  }));
+  console.table(rows);
+}
+
+export async function deleteConnection(name: string): Promise<void> {
+  await loadConnections();
+
+  if (!connections.has(name)) {
+    console.error(chalk.red(`Connection "${name}" not found.`));
+    process.exit(1);
+  }
+
+  connections.delete(name);
+  await saveConnections();
+  console.log(chalk.yellow(`Connection "${name}" deleted.`));
+}
+
+export async function connect(nameUrl: string, options?: { username?: string; password?: string; current?: boolean }): Promise<void> {
+  await loadConnections();
+
+  let database: string;
+  let host: string;
+  let port: number;
+  let existing: ConnectionInfo | null = null;
+  let urlUsername = '';
+  let urlPassword = '';
+
+  if (isUrl(nameUrl)) {
+    const url = new URL(nameUrl);
+    database = url.pathname.slice(1) || 'postgres';
+    host = url.hostname;
+    port = parseInt(url.port) || 5432;
+    urlUsername = url.username;
+    urlPassword = url.password;
+    existing = connections.get(database) || null;
+  } else {
+    database = nameUrl;
+    existing = connections.get(database) || null;
+    if (!existing) {
+      console.error(chalk.red(`Connection "${database}" not found.`));
+      console.log(chalk.cyan('Use "dbcli connect <url>" to add a new connection.'));
+      process.exit(1);
+    }
+    host = existing.host;
+    port = existing.port;
+  }
+
+  let credentials: { username: string; password: string };
+
+  if (options?.current) {
+    const activeConn = Array.from(connections.values()).find((conn) => conn.enabled);
+    if (!activeConn) {
+      console.error(chalk.red('No currently connected database found.'));
+      process.exit(1);
+    }
+    credentials = { username: activeConn.username, password: activeConn.password };
+  } else if (options?.username && options?.password) {
+    credentials = { username: options.username, password: options.password };
+  } else if (urlUsername || urlPassword) {
+    credentials = { username: urlUsername, password: urlPassword };
+  } else if (existing && existing.username && existing.password) {
+    const useExisting = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'value',
+        message: `You have an existing account "${existing.username}". Enter "y" to use it or anything else to re-login:`,
+        default: 'y',
+      },
+    ]);
+
+    if (useExisting.value.toLowerCase() === 'y') {
+      credentials = { username: existing.username, password: existing.password };
+    } else {
+      credentials = await promptCredentials();
+    }
+  } else {
+    credentials = await promptCredentials();
+  }
+
+  let finalUrl: string;
+  if (existing) {
+    finalUrl = buildUrl(existing, credentials.username, credentials.password);
+  } else {
+    finalUrl = `postgresql://${credentials.username}:${credentials.password}@${host}:${port}/${database}`;
+  }
+
+  const driver = new PostgresDriver();
+
+  try {
+    console.log(chalk.cyan(`Connecting to db("${database}")...`));
+    await driver.connect(finalUrl);
+
+    for (const conn of connections.values()) {
+      conn.enabled = false;
+    }
+
+    const connectionInfo: ConnectionInfo = {
+      url: `postgresql://${host}:${port}/${database}`,
+      database,
+      host,
+      port,
+      username: credentials.username,
+      password: credentials.password,
+      lastConnected: new Date().toISOString(),
+      enabled: true,
+    };
+
+    connections.set(database, connectionInfo);
+    await saveConnections();
+
+    console.log(chalk.green(`Connected to db("${database}") as user("${credentials.username}") successfully!`));
+    process.exit(0);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk.red(`Connection failed: ${message}`));
+    process.exit(1);
+  }
+}
+
+export async function disconnect(name: string): Promise<void> {
+  await loadConnections();
+
+  if (!connections.has(name)) {
+    console.error(chalk.red(`Connection "${name}" not found.`));
+    process.exit(1);
+  }
+
+  const conn = connections.get(name)!;
+  conn.enabled = false;
+  await saveConnections();
+
+  console.log(chalk.yellow(`Disconnected from "${name}".`));
+}
+
+export async function logout(name: string): Promise<void> {
+  await loadConnections();
+
+  if (!connections.has(name)) {
+    console.error(chalk.red(`Connection "${name}" not found.`));
+    process.exit(1);
+  }
+
+  const conn = connections.get(name)!;
+  conn.enabled = false;
+  conn.username = '';
+  conn.password = '';
+  await saveConnections();
+
+  console.log(chalk.yellow(`Logged out from "${name}". Username and password cleared.`));
+}

package/src/commands/query.ts

@@ -0,0 +1,51 @@
+import chalk from 'chalk';
+import { PostgresDriver } from '../drivers/postgres.js';
+import { getActiveConnection } from './connect.js';
+
+async function getActiveDriver(): Promise<{ driver: PostgresDriver; connName: string } | null> {
+  const activeConn = await getActiveConnection();
+  if (!activeConn) {
+    return null;
+  }
+
+  const url = `postgresql://${activeConn.username}:${activeConn.password}@${activeConn.host}:${activeConn.port}/${activeConn.database}`;
+  const driver = new PostgresDriver();
+  await driver.connect(url);
+
+  const connName = activeConn.database;
+  return { driver, connName };
+}
+
+export async function executeQuery(sql: string): Promise<void> {
+  const result = await getActiveDriver();
+
+  if (!result) {
+    console.log(chalk.red('No active database connection.'));
+    console.log(chalk.cyan('Please use "dbcli connect <url>" to connect to a database first.'));
+    process.exit(1);
+  }
+
+  const { driver, connName } = result;
+
+  try {
+    console.log(chalk.gray(`Executing on database "${connName}":`));
+    console.log(chalk.cyan(sql));
+    console.log();
+
+    const queryResult = await driver.query(sql);
+
+    if (queryResult.rows.length === 0) {
+      console.log(chalk.yellow(`Query executed successfully. No rows returned.`));
+      console.log(chalk.gray(`Row count: ${queryResult.rowCount}`));
+    } else {
+      console.table(queryResult.rows);
+      console.log(chalk.gray(`Total: ${queryResult.rows.length} row(s)`));
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk.red(`Query failed: ${message}`));
+    process.exit(1);
+  } finally {
+    await driver.disconnect();
+  }
+}

package/src/commands/tables.ts

@@ -0,0 +1,77 @@
+import chalk from 'chalk';
+import { PostgresDriver } from '../drivers/postgres.js';
+import { getActiveConnection } from './connect.js';
+
+async function getActiveDriver(): Promise<{ driver: PostgresDriver; connName: string } | null> {
+  const activeConn = await getActiveConnection();
+  if (!activeConn) {
+    return null;
+  }
+
+  const url = `postgresql://${activeConn.username}:${activeConn.password}@${activeConn.host}:${activeConn.port}/${activeConn.database}`;
+  const driver = new PostgresDriver();
+  await driver.connect(url);
+
+  const connName = activeConn.database;
+  return { driver, connName };
+}
+
+export async function listTables(): Promise<void> {
+  const result = await getActiveDriver();
+
+  if (!result) {
+    console.log(chalk.red('No active database connection.'));
+    console.log(chalk.cyan('Please use "dbcli connect <url>" to connect to a database first.'));
+    process.exit(1);
+  }
+
+  const { driver, connName } = result;
+
+  try {
+    const tables = await driver.listTables();
+
+    if (tables.length === 0) {
+      console.log(chalk.yellow(`No tables found in database "${connName}".`));
+    } else {
+      console.log(chalk.cyan(`Tables in database "${connName}":`));
+      console.table(tables);
+    }
+  } finally {
+    await driver.disconnect();
+  }
+}
+
+export async function describeTable(tableName: string): Promise<void> {
+  const result = await getActiveDriver();
+
+  if (!result) {
+    console.log(chalk.red('No active database connection.'));
+    console.log(chalk.cyan('Please use "dbcli connect <url>" to connect to a database first.'));
+    process.exit(1);
+  }
+
+  const { driver, connName } = result;
+
+  try {
+    const columns = await driver.describeTable('public', tableName);
+
+    if (columns.length === 0) {
+      console.log(chalk.yellow(`Table "${tableName}" not found in database "${connName}".`));
+    } else {
+      console.log(chalk.cyan(`Structure of table "${tableName}" in database "${connName}":`));
+      console.table(columns);
+
+      const hasDescriptions = columns.some(col => col.description);
+      if (hasDescriptions) {
+        console.log(chalk.gray('\nColumn descriptions:'));
+        columns.forEach(col => {
+          if (col.description) {
+            console.log(`  ${chalk.white(col.name)}: ${chalk.gray(col.description)}`);
+          }
+        });
+      }
+    }
+  } finally {
+    await driver.disconnect();
+  }
+}

package/src/drivers/interface.ts

@@ -0,0 +1,42 @@
+/*
+ * @Author: Mingxuan songmingxuan936@gmail.com
+ * @Date: 2026-04-04 13:28:20
+ * @LastEditors: Mingxuan songmingxuan936@gmail.com
+ * @LastEditTime: 2026-04-04 13:28:41
+ * @FilePath: /dbcli/src/drivers/interface.ts
+ * @Description: 
+ * 
+ * Copyright (c) 2026 by ${git_name_email}, All Rights Reserved. 
+ */
+export interface QueryResult {
+  rows: Record<string, unknown>[];
+  rowCount: number;
+  fields: FieldInfo[];
+}
+
+export interface FieldInfo {
+  name: string;
+  dataTypeID: number;
+}
+
+export interface TableInfo {
+  schema: string;
+  name: string;
+}
+
+export interface ColumnInfo {
+  name: string;
+  dataType: string;
+  isNullable: boolean;
+  defaultValue: string | null;
+  description: string | null;
+}
+
+export interface DatabaseDriver {
+  connect(url: string): Promise<void>;
+  disconnect(): Promise<void>;
+  isConnected(): boolean;
+  query(sql: string): Promise<QueryResult>;
+  listTables(): Promise<TableInfo[]>;
+  describeTable(schema: string, table: string): Promise<ColumnInfo[]>;
+}

package/src/drivers/postgres.ts

@@ -0,0 +1,97 @@
+/*
+ * @Author: Mingxuan songmingxuan936@gmail.com
+ * @Date: 2026-04-05 17:01:59
+ * @LastEditors: Mingxuan songmingxuan936@gmail.com
+ * @LastEditTime: 2026-04-05 17:42:59
+ * @FilePath: /dbcli/src/drivers/postgres.ts
+ * @Description: 
+ * 
+ * Copyright (c) 2026 by ${git_name_email}, All Rights Reserved. 
+ */
+import pg from 'pg';
+import type { DatabaseDriver, QueryResult, TableInfo, ColumnInfo } from './interface.js';
+
+export class PostgresDriver implements DatabaseDriver {
+  private client: pg.PoolClient | null = null;
+  private pool: pg.Pool | null = null;
+  private connected = false;
+
+  async connect(url: string): Promise<void> {
+    const connectionUrl = new URL(url);
+
+    this.pool = new pg.Pool({
+      host: connectionUrl.hostname,
+      port: parseInt(connectionUrl.port) || 5432,
+      user: connectionUrl.username,
+      password: connectionUrl.password,
+      database: connectionUrl.pathname.slice(1) || 'postgres',
+      ssl: connectionUrl.searchParams.get('sslmode') === 'require' ? { rejectUnauthorized: false } : undefined,
+    });
+
+    this.client = await this.pool.connect();
+    this.connected = true;
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.client) {
+      this.client.release();
+      this.client = null;
+    }
+    if (this.pool) {
+      await this.pool.end();
+      this.pool = null;
+    }
+    this.connected = false;
+  }
+
+  isConnected(): boolean {
+    return this.connected && this.client !== null;
+  }
+
+  async query(sql: string, params?: unknown[]): Promise<QueryResult> {
+    if (!this.client) {
+      throw new Error('Not connected to database');
+    }
+
+    const result = await this.client.query(sql, params);
+    return {
+      rows: result.rows,
+      rowCount: result.rowCount ?? 0,
+      fields: result.fields.map((f: pg.FieldDef) => ({
+        name: f.name,
+        dataTypeID: f.dataTypeID,
+      })),
+    };
+  }
+
+  async listTables(): Promise<TableInfo[]> {
+    const result = await this.query(`
+      SELECT schemaname as schema, tablename as name
+      FROM pg_tables
+      WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+      ORDER BY schemaname, tablename
+    `);
+    return result.rows as unknown as TableInfo[];
+  }
+
+  async describeTable(schema: string, table: string): Promise<ColumnInfo[]> {
+    const result = await this.query(`
+      SELECT
+        a.attname as name,
+        format_type(a.atttypid, a.atttypmod) as data_type,
+        CASE WHEN a.attnotnull THEN 'NO' ELSE 'YES' END as is_nullable,
+        pg_get_expr(ad.adbin, a.attrelid) as default_value,
+        col_description(a.attrelid, a.attnum) as description
+      FROM pg_attribute a
+      JOIN pg_class c ON c.oid = a.attrelid
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      LEFT JOIN pg_attrdef ad ON ad.adrelid = a.attrelid AND ad.adnum = a.attnum
+      WHERE n.nspname = $1
+        AND c.relname = $2
+        AND a.attnum > 0
+        AND NOT a.attisdropped
+      ORDER BY a.attnum
+    `, [schema, table]);
+    return result.rows as unknown as ColumnInfo[];
+  }
+}

package/src/index.ts

@@ -0,0 +1,85 @@
+import { Command } from 'commander';
+import { connect, disconnect, logout, showConnections as statusConnections, deleteConnection } from './commands/connect.js';
+import { listTables, describeTable } from './commands/tables.js';
+import { executeQuery } from './commands/query.js';
+
+const program = new Command();
+
+program
+  .name('dbcli')
+  .description('Database CLI tool')
+  .version('0.1.0')
+  .addHelpCommand(false);
+
+program
+  .command('connect')
+  .description('Connect to a database (-u <user> -p <pass> for credentials, -c to use current)')
+  .argument('<db-name|url>', 'Connection name (for existing) or full URL (for new connection)')
+  .option('-u, --username <username>', 'Username for authentication')
+  .option('-p, --password <password>', 'Password for authentication')
+  .option('-c, --current', 'Use credentials from currently connected database')
+  .action(async (nameUrl: string, options) => {
+    await connect(nameUrl, options);
+  });
+
+program
+  .option('-s, --status', 'Show all saved connections status')
+  .action(async (options, cmd) => {
+    if (cmd.args && cmd.args.length > 0) {
+      console.error(`error: unknown command '${cmd.args[0]}'`);
+      process.exit(1);
+    }
+    if (options.status) {
+      await statusConnections();
+      process.exit(0);
+    }
+  });
+
+program
+  .command('disconnect')
+  .description('Disconnect from a database (keeps credentials)')
+  .argument('<db-name>', 'Connection name to disconnect')
+  .action(async (name: string) => {
+    await disconnect(name);
+  });
+
+program
+  .command('logout')
+  .description('Logout from a connection (clears credentials)')
+  .argument('<db-name>', 'Connection name to logout')
+  .action(async (name: string) => {
+    await logout(name);
+  });
+
+program
+  .command('delete')
+  .description('Delete a saved connection completely')
+  .argument('<db-name>', 'Connection name to delete')
+  .action(async (name: string) => {
+    await deleteConnection(name);
+  });
+
+program
+  .command('tables')
+  .description('List all tables in the connected database')
+  .action(async () => {
+    await listTables();
+  });
+
+program
+  .command('describe')
+  .description('Show the structure of a table')
+  .argument('<table>', 'Table name to describe')
+  .action(async (table: string) => {
+    await describeTable(table);
+  });
+
+program
+  .command('query')
+  .description('Execute a SQL query')
+  .argument('<sql>', 'SQL query to execute (use quotes for complex queries)')
+  .action(async (sql: string) => {
+    await executeQuery(sql);
+  });
+
+program.parse();

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}