{"id":43563,"library":"pg-lightquery","title":"pg-lightquery","description":"pg-lightquery is a modern, type-safe PostgreSQL query builder for Node.js with TypeScript support (v0.4.5). It offers deferred execution, fluent CTE-based multi-table operations, smart operators (LIKE, IN, date ranges, JSON queries), complex joins, transaction builder, optional audit fields with lastChangedBy tracking, and minimal dependencies (only 4 core packages). Unlike heavier ORMs like Sequelize, it focuses on composable, security-first design with separate column validation and data projection. Suitable for Node.js applications requiring type-safe SQL generation with full control.","status":"active","version":"0.4.5","language":"javascript","source_language":"en","source_url":"https://github.com/dr-aiuta/pgquery","tags":["javascript","postgresql","sql","typescript"],"install":[{"cmd":"npm install pg-lightquery","lang":"bash","label":"npm"},{"cmd":"yarn add pg-lightquery","lang":"bash","label":"yarn"},{"cmd":"pnpm add pg-lightquery","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Underlying PostgreSQL driver for Node.js, required for connection and query execution.","package":"pg","optional":false},{"reason":"Used for reflection support in TypeScript decorators (if used).","package":"reflect-metadata","optional":true}],"imports":[{"note":"Default export. Must be imported with default import in ESM. CJS require() will fail as package is ESM-only.","wrong":"const PostgresConnection = require('pg-lightquery'); // CJS not supported","symbol":"PostgresConnection","correct":"import PostgresConnection from 'pg-lightquery';"},{"note":"Named export. TypeScript definitions included.","wrong":"import TableBase from 'pg-lightquery'; // TableBase is not a default export","symbol":"TableBase","correct":"import { TableBase } from 'pg-lightquery';"},{"note":"Named export for advanced table relationships. TypeScript types included.","wrong":"import EnhancedTableBase from 'pg-lightquery'; // Must use named import","symbol":"EnhancedTableBase","correct":"import { EnhancedTableBase } from 'pg-lightquery';"},{"note":"TypeScript type export. Use 'import type' to avoid runtime inclusion.","wrong":"import { ColumnDefinition } from 'pg-lightquery'; // Type-only import preferred for runtime efficiency","symbol":"ColumnDefinition","correct":"import type { ColumnDefinition } from 'pg-lightquery';"}],"quickstart":{"code":"import PostgresConnection, { TableBase, ColumnDefinition, TableDefinition } from 'pg-lightquery';\n\n// Initialize connection\nPostgresConnection.initialize({\n  host: 'localhost',\n  port: 5432,\n  user: 'your_user',\n  password: 'your_password',\n  database: 'your_database',\n});\n\n// Define schema\nconst usersColumns = {\n  id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },\n  name: { type: 'TEXT', notNull: true },\n  email: { type: 'TEXT', unique: true },\n} as const;\n\ntype UsersSchema = { [K in keyof typeof usersColumns]: ColumnDefinition };\n\nconst usersTable: TableDefinition<UsersSchema> = {\n  tableName: 'users',\n  schema: { columns: usersColumns },\n};\n\n// Create table class\nclass UsersTable extends TableBase<UsersSchema> {\n  constructor() {\n    super(usersTable);\n  }\n\n  insertUser(userData: { name: string; email: string }) {\n    return this.insert({\n      allowedColumns: ['name', 'email'],\n      options: { data: userData, returnField: 'id' },\n    });\n  }\n}\n\n// Use\nconst users = new UsersTable();\nconst result = await users.insertUser({ name: 'Alice', email: 'alice@example.com' });\nconsole.log('Inserted user id:', result.id);","lang":"typescript","description":"Shows how to initialize a connection, define a schema with TypeScript types, create a table class using TableBase, and execute a type-safe insert operation."},"warnings":[{"fix":"Use import syntax in an ESM context (set \"type\": \"module\" in package.json or use .mjs extension).","message":"ESM-only: This package is ESM-only. Using require() will throw a runtime error.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Consider using TableBase with manual relation handling for simpler use cases.","message":"The 'EnhancedTableBase' may be deprecated in future versions in favor of composition patterns.","severity":"deprecated","affected_versions":"0.4.x"},{"fix":"Always provide a 'where' object with at least one condition when calling update().","message":"The 'update' method requires a 'where' clause; omitting it will throw an error to prevent accidental updates.","severity":"gotcha","affected_versions":">=0.4.0"},{"fix":"Explicitly list all columns that can be inserted via allowedColumns in the insert options.","message":"The 'insert' method's 'allowedColumns' is mandatory; passing columns not in the list will be silently ignored or throw, depending on configuration.","severity":"gotcha","affected_versions":">=0.4.0"}],"env_vars":null,"search_vec":"'4':56 'applic':82 'audit':47 'base':29 'builder':15,45 'column':74 'complex':42 'compos':67 'control':91 'core':57 'cte':28 'cte-bas':27 'data':77 'date':38 'defer':24 'depend':54 'design':71 'execut':25 'field':48 'first':70 'fluent':26 'focus':65 'full':90 'generat':88 'heavier':60 'javascript':92 'join':43 'json':40 'lastchangedbi':50 'lightqueri':3,6 'like':36,62 'minim':53 'modern':9 'multi':31 'multi-t':30 'node.js':17,81 'offer':23 'oper':33,35 'option':46 'orm':61 'packag':58 'pg':2,5 'pg-lightqueri':1,4 'postgresql':13,93 'project':78 'queri':14,41 'rang':39 'requir':83 'safe':12,86 'secur':69 'security-first':68 'separ':73 'sequel':63 'smart':34 'sql':87,94 'suitabl':79 'support':20 'tabl':32 'track':51 'transact':44 'type':11,85 'type-saf':10,84 'typescript':19,95 'unlik':59 'v0.4.5':21 'valid':75","created_at":"2026-06-05T17:00:24.499780+00:00","updated_at":"2026-06-05T17:00:24.499780+00:00","problems":[{"fix":"Use import PostgresConnection from 'pg-lightquery'; and ensure your project is configured for ESM.","cause":"Using CommonJS require() instead of ESM import.","error":"TypeError: PostgresConnection.initialize is not a function"},{"fix":"Run 'npm install pg-lightquery' in your project root.","cause":"Package not installed or npm install failed.","error":"ERR_MODULE_NOT_FOUND: Cannot find package 'pg-lightquery'"},{"fix":"Ensure column types match the supported PostgreSQL types exactly (e.g., 'INTEGER', 'TEXT', 'TIMESTAMP WITHOUT TIME ZONE').","cause":"Using incorrect types for column definitions (e.g., wrong type strings).","error":"TypeScript error: Type 'X' is not assignable to type 'ColumnDefinition'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/dr-aiuta/pgquery#readme","github":"https://github.com/dr-aiuta/pgquery","docs":null,"changelog":null,"pypi":null,"npm":"pg-lightquery","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}