{"id":17584,"library":"easy-database-connector","title":"Easy Database Connector","description":"easy-database-connector, currently at version 1.4.1, is a TypeScript-first database connector library primarily designed for MSSQL (SQL Server) environments. It offers a comprehensive suite of features aimed at enhancing performance, security, and developer productivity. Key functionalities include connection pooling for optimal performance, built-in encryption for sensitive data, and integrated Redis caching for pagination and general query results. The library provides robust transaction management, supports bulk operations, and offers type-safe querying with full TypeScript backing. While specific release cadence is not explicitly stated, its current version suggests active development. Its differentiators lie in its all-in-one approach to common database concerns for MSSQL, providing encryption, caching, and robust operations within a single, coherent API, unlike more minimalist ORMs or query builders.","status":"active","version":"1.4.1","language":"javascript","source_language":"en","source_url":"https://github.com/ahmetdlbs/easy-database-connector","tags":["javascript","database","mssql","sql-server","pagination","caching","encryption","typescript","redis"],"install":[{"cmd":"npm install easy-database-connector","lang":"bash","label":"npm"},{"cmd":"yarn add easy-database-connector","lang":"bash","label":"yarn"},{"cmd":"pnpm add easy-database-connector","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for type checking and development.","package":"typescript","optional":false},{"reason":"Runtime dependency if Redis caching is enabled and utilized.","package":"redis","optional":true}],"imports":[{"note":"Primarily used for SELECT operations with optional caching.","wrong":"const query = require('easy-database-connector').query;","symbol":"query","correct":"import { query } from 'easy-database-connector';"},{"note":"Used for INSERT, UPDATE, DELETE, and bulk operations.","wrong":"const execute = require('easy-database-connector').execute;","symbol":"execute","correct":"import { execute } from 'easy-database-connector';"},{"note":"Provides a robust mechanism for running multiple queries within a single database transaction.","wrong":"const transaction = require('easy-database-connector').transaction;","symbol":"transaction","correct":"import { transaction } from 'easy-database-connector';"}],"quickstart":{"code":"import { query, execute, queryWithPagination, transaction } from 'easy-database-connector';\nimport 'dotenv/config'; // Ensure environment variables are loaded\n\ninterface User {\n    id: number;\n    name: string;\n    email: string;\n    active: boolean;\n}\n\nasync function runExample() {\n    // Basic query\n    const users = await query<User>({\n        sql: 'SELECT * FROM users WHERE active = @p0',\n        parameters: [true]\n    });\n    console.log('Active users:', users);\n\n    // Paged query with caching\n    const pagedUsers = await queryWithPagination<User>({\n        sql: 'SELECT * FROM users',\n        parameters: [],\n        page: 1,\n        pageSize: 10,\n        orderBy: 'name ASC',\n        cache: {\n            key: 'users:page1',\n            ttl: 300 // 5 minutes\n        }\n    });\n    console.log('Paged users:', pagedUsers.rows);\n\n    // Encrypted data insertion (requires MSSQL encryption setup)\n    // Ensure environment variables for encryption are set: MSSQL_SYNNETRIC_KEY_NAME, MSSQL_CERTIFICATE_NAME, MASTER_KEY_PASSWORD\n    try {\n        await execute({\n            sql: 'INSERT INTO secure_data (data) VALUES (@p0)',\n            parameters: ['sensitive information'],\n            encryption: {\n                open: { aes: true, masterkey: true },\n                data: ['0']\n            }\n        });\n        console.log('Sensitive data inserted (encrypted).');\n    } catch (e) {\n        console.error('Failed to insert encrypted data. Check MSSQL encryption setup and .env config.', e);\n    }\n\n    // Transaction example\n    await transaction(async (trx) => {\n        await execute({\n            sql: 'INSERT INTO users (name) VALUES (@p0)',\n            parameters: ['John Doe'],\n            transaction: trx\n        });\n\n        await execute({\n            sql: 'INSERT INTO logs (action) VALUES (@p0)',\n            parameters: ['user_john_created'],\n            transaction: trx\n        });\n    });\n    console.log('Transaction completed: User and log created.');\n}\n\nrunExample().catch(console.error);\n","lang":"typescript","description":"This quickstart demonstrates basic querying, cached pagination, encrypted data insertion, and transaction management using the library's core functions."},"warnings":[{"fix":"Ensure all required environment variables (e.g., DB_HOST, DB_USER, REDIS_HOST) are correctly defined and loaded before application startup (e.g., using `dotenv/config`).","message":"The library relies heavily on environment variables for database, Redis, and encryption configuration. Missing or incorrectly named variables in the .env file can lead to connection failures or unexpected behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult MSSQL documentation for setting up database encryption. Verify that `MSSQL_SYNNETRIC_KEY_NAME`, `MSSQL_CERTIFICATE_NAME`, and `MASTER_KEY_PASSWORD` in your .env correctly reference existing and accessible SQL Server encryption objects.","message":"Utilizing the built-in encryption features requires specific setup in your MSSQL database, including creating master keys, symmetric keys, and certificates. Misconfiguration or missing database objects will cause encryption-related operations to fail.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure a Redis server is accessible from your application and `REDIS_ENABLED=true`, `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD` (if applicable) are correctly set in your .env file.","message":"While optional, enabling and configuring Redis caching requires a running Redis server and correct `REDIS_` environment variables. Incorrect Redis configuration can lead to caching failures, fallback to direct database queries, or application errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Carefully match the `ColumnType` definitions in `bulk.columns` to the exact data types and lengths of your target SQL Server table columns. Import `mssql` types if needed for type definitions.","message":"When performing bulk operations with the `execute` function, the `bulk.columns` array requires precise MSSQL data type definitions (e.g., `mssql.NVarChar(100)`). Mismatches between these types, the database schema, or the data being inserted will result in insertion errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Verify that `DB_USER`, `DB_PASSWORD`, `DB_HOST`, `DB_PORT`, and `DB_DATABASE` are correctly configured in your `.env` file and that the user has appropriate database permissions.","cause":"Incorrect database connection credentials (username, password, host, or port) are provided in the environment variables.","error":"Login failed for user 'your_user'."},{"fix":"Ensure all mandatory database configuration variables (e.g., `DB_TYPE`, `DB_HOST`, `DB_USER`, `DB_PASSWORD`, `DB_DATABASE`, `DB_PORT`, `DB_ENCRYPT`) are present and correctly named in your `.env` file.","cause":"A critical database configuration environment variable is missing or misspelled, preventing the connector from initializing.","error":"Error: Environment variable DB_HOST is not set."},{"fix":"Confirm that your SQL Server database has the necessary master key and symmetric key/certificate created and that the `MASTER_KEY_PASSWORD`, `MSSQL_SYNNETRIC_KEY_NAME`, and `MSSQL_CERTIFICATE_NAME` in your `.env` file match the database configuration.","cause":"The MSSQL encryption setup for `easy-database-connector` is incomplete or improperly configured, specifically related to the master key or symmetric key initialization in SQL Server.","error":"A Master Key must be open before a Symmetric Key can be opened. Open the Master Key in the database."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}