tomsdb

Node.js client for tomsdb database server.

Install

npm install tomsdb

Quick Start

const tomsdb = require('tomsdb');

const db = await tomsdb.createConnection({
  host: 'localhost',
  port: 5432,
  user: 'admin',
  password: 'admin123',
  database: 'myapp'
});

await db.query('CREATE TABLE users (id INT AUTO_INCREMENT, name STRING REQUIRED, age INT)');
await db.query('INSERT INTO users (name, age) VALUES ("Alice", 25)');

const result = await db.query('SELECT * FROM users');
console.log(result);

db.end();

API

tomsdb.createConnection(options) → Promise<Connection>

Creates and returns a connected, authenticated connection.

const db = await tomsdb.createConnection({
  host: 'localhost',       // default: 'localhost'
  port: 5432,              // default: 5432
  user: 'admin',           // default: 'admin'
  password: 'admin123',    // default: 'admin123'
  database: 'myapp',       // optional, auto-runs USE <database>
  connectTimeout: 10000,   // ms, default: 10000
  queryTimeout: 30000      // ms, default: 30000
});

connection.query(sql) → Promise<string|object[]>

Execute a SQL statement.

await db.query('CREATE DATABASE shop');
await db.query('USE shop');
await db.query('CREATE TABLE products (id INT AUTO_INCREMENT, name STRING REQUIRED, price INT)');
await db.query('INSERT INTO products (name, price) VALUES ("Widget", 999)');

const rows = await db.query('SELECT * FROM products');
console.log(rows);

connection.ping() → Promise<void>

Check if the server is reachable.

await db.ping(); // throws on failure

connection.end()

Gracefully close the connection.

connection.destroy()

Forcefully close the connection.

tomsdb.createPool(options) → Pool

Create a connection pool for concurrent usage.

const pool = tomsdb.createPool({
  host: 'localhost',
  port: 5432,
  user: 'admin',
  password: 'admin123',
  database: 'myapp',
  connectionLimit: 10,  // default: 10
  queueLimit: 0         // 0 = unlimited, default: 0
});

pool.query(sql) → Promise<string|object[]>

Auto-acquires a connection, runs the query, and releases it back.

const result = await pool.query('SELECT * FROM users');

pool.getConnection() → Promise<PoolConnection>

Manually acquire a connection (useful for transactions).

const conn = await pool.getConnection();

await conn.query('BEGIN TRANSACTION');
await conn.query('INSERT INTO orders (product, qty) VALUES ("Widget", 2)');
await conn.query('UPDATE inventory SET stock = stock - 2 WHERE product = "Widget"');
await conn.query('COMMIT');

conn.release(); // return to pool

pool.end() → Promise<void>

Close all connections in the pool.

Response Formatting

The SDK automatically formats human-readable string responses from the server into structured JavaScript objects.

| Command | Formatted Output | |---------|------------------| | SELECT * ... | [{ id: '1', name: 'Alice' }, ...] | | SHOW DATABASES | [{ name: 'watchup', current: true }, ...] | | SHOW TABLES | ['users', 'posts'] | | DESCRIBE table | { table: 'users', schema: [...] } |

To disable formatting and get raw strings, set raw: true in your options:

const db = await tomsdb.createConnection({ ..., raw: true });

Express Example

const express = require('express');
const tomsdb = require('tomsdb');

const app = express();
const pool = tomsdb.createPool({
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT) || 5432,
  user: process.env.DB_USER || 'admin',
  password: process.env.DB_PASS || 'admin123',
  database: 'myapp',
  connectionLimit: 20
});

app.get('/users', async (req, res) => {
  try {
    const result = await pool.query('SELECT * FROM users');
    res.json({ data: result });
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

app.listen(3000, () => console.log('Server running on :3000'));

License

MIT