{"id":27979234,"url":"https://github.com/infinitaslearning/systemic-mssql","last_synced_at":"2025-05-08T02:32:29.568Z","repository":{"id":40700161,"uuid":"436579755","full_name":"infinitaslearning/systemic-mssql","owner":"infinitaslearning","description":"Systemic component for connecting to a MSSQL database","archived":false,"fork":false,"pushed_at":"2023-07-19T06:28:04.000Z","size":2031,"stargazers_count":0,"open_issues_count":17,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-14T03:07:16.312Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/infinitaslearning.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-12-09T10:47:11.000Z","updated_at":"2021-12-21T16:45:46.000Z","dependencies_parsed_at":"2023-02-08T18:00:31.987Z","dependency_job_id":null,"html_url":"https://github.com/infinitaslearning/systemic-mssql","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinitaslearning%2Fsystemic-mssql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinitaslearning%2Fsystemic-mssql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinitaslearning%2Fsystemic-mssql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infinitaslearning%2Fsystemic-mssql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/infinitaslearning","download_url":"https://codeload.github.com/infinitaslearning/systemic-mssql/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252986852,"owners_count":21836242,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-08T02:31:47.744Z","updated_at":"2025-05-08T02:32:29.554Z","avatar_url":"https://github.com/infinitaslearning.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @infinitaslearning/systemic-mssql\n\nSystemic mssql is a [systemic component](https://github.com/guidesmiths/systemic) for the [MS SQL](https://github.com/tediousjs/node-mssql). Its goal is to help you connect to a MS SQL database.\n\nThis library:\n\n- includes straightforward configuration to connect to the database\n- exposes query interface that prefers prepared statements for automatic sanitation to prevent sql injection\n- includes easy to use sql-tag helper\n- includes async iterable streaming query function to query large data sets without memory exhaustion issues\n- includes transaction helpers\n- exposed full connectionPool Request object for advanced scenarios\n- allows setting up error handler to listen to internal connection pool errors\n\nWe've created this library as an alternative to the existing [systemic-mssql](https://github.com/guidesmiths/systemic-mssql) library, which is very opiniated, and doesn't meet our needs.\n\n## Add Mssql to Systemic System\n\n```typescript\nimport System from 'systemic'\nimport initDb from '@infinitaslearning/systemic-mssql'\n\nnew System()\n  .configure({\n    mssql: {\n      connection: 'my-connection-string',\n    },\n  })\n  .add('mssql', initDb())\n  .dependsOn('config')\n  .start((err, components) =\u003e {\n    // Do stuff with components.mssql\n  })\n```\n\nConnection in the configuration can either be a mssql connection string or a full mssql ConnectionPool config.\n\n## Usage\n\n### Query\n\n```typescript\nimport { Database } from '@infinitaslearning/systemic-mssql'\n\ninterface Book {\n  id: string\n  title: string\n}\n\nconst initBookStore = (database: Database) =\u003e ({\n  getBook: (id: string) =\u003e database.query\u003cBook\u003e`\n  SELECT *\n  FROM Books\n  WHERE id = ${id}`,\n})\n```\n\nor\n\n```typescript\nimport { Database } from '@infinitaslearning/systemic-mssql'\nimport { bookQuery } from './queries'\n\nconst initBookStore = (database: Database) =\u003e ({\n  getBook: (id: string) =\u003e database.query(bookQuery(id)),\n})\n```\n\nAll query functions use mssql [tagged template literals](https://github.com/tediousjs/node-mssql#es6-tagged-template-literals) to prevent sql injection\n\n### Re-usable queries\n\n```typescript\nimport { sql } from '@infinitaslearning/systemic-mssql'\n\ninterface Book {\n  id: string\n  title: string\n}\n\nexport bookQuery = (id: string) =\u003e sql`\n  SELECT *\n  FROM Books\n  WHERE id = ${id}`\n```\n\n### Query big datasets\n\nIf you plan to work with large amount of rows, you should always use streaming to prevent memory exhaustion issues.\nThe streamingQuery function wraps the [mssql streaming capability](https://github.com/tediousjs/node-mssql#streaming) and exposes it as an easy to use async iterable.\n\n```typescript\nimport { Database, sql } from '@infinitaslearning/systemic-mssql'\n\nconst initBookStore = (database: Database) =\u003e ({\n  getBooks: () =\u003e database.streamingQuery(sql`SELECT * FROM Books`, { size: 500 }),\n})\n```\n\nThe second argument to the streamingQuery function is optional can be used to set the maximum size of the buffer (in number of records). When the buffer is full the request is automatically paused until all retreived records have been read.\n\nHere's an example of using the result of a streamingQuery:\n\n```typescript\nimport { BookStore } from './stores'\n\nconst initBooksDomain = (store: BookStore) =\u003e ({\n  doSomething: async () =\u003e {\n    for await (const book of store.getBooks()) {\n      // do something with the book\n    }\n  },\n})\n```\n\n### Transactions\n\nThe withTransaction function allows you to write clean code that's bundled in a single transaction that's automatically commited on success. By default the entire transaction is rolled back on error, but that behaviour can be overriden by providing and onTransactionError callback.\n\n```typescript\nimport { Database } from '@infinitaslearning/systemic-mssql'\n\nconst initStore = (database: Database) =\u003e ({\n  doSomething: () =\u003e {\n    database.withTransaction((transaction) =\u003e {\n      const request = transaction.request()\n      // ... execute mulitple request within same transaction and/or include other related logic\n    })\n  },\n})\n```\n\nWithTransaction throws if an error occures while connecting to the database or starting the transaction, therefore in the error callback it's safe to assume that there's an active database connection.\n\n```typescript\nimport { Database } from '@infinitaslearning/systemic-mssql'\nimport { ISOLATION_LEVEL } from 'mssql'\n\nconst initStore = (database: Database) =\u003e ({\n  doSomething: () =\u003e {\n    database.withTransaction(\n      (transaction) =\u003e {\n        // normal transaction flow\n      },\n      {\n        isolationLevel: ISOLATION_LEVEL.READ_UNCOMMITTED,\n        onTransactionError: (error, transaction) =\u003e {\n          // mitigating actions\n        },\n      },\n    )\n  },\n})\n```\n\n### Error handling\n\nThe onError function can be used to attach an error callback to the connection pool.\n\n```typescript\nimport { system } from './system'\n\nsystem.start((err, components) =\u003e {\n  const { mssql } = components\n  mssql.onError((error) =\u003e {\n    // ... error handler\n  })\n})\n```\n\n### Advanced scenarios\n\nFor advanced scenarios that are not supported by any of the functions, the raw mssql Request is also available from this component:\n\n```typescript\nimport { Database } from '@infinitaslearning/systemic-mssql'\n\nconst initBookStore = (database: Database) =\u003e ({\n  doAdvancedStuff: () =\u003e {\n    const request = database.request()\n    // do whatever you want with this request\n  },\n})\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfinitaslearning%2Fsystemic-mssql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfinitaslearning%2Fsystemic-mssql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfinitaslearning%2Fsystemic-mssql/lists"}