docs: documentation for parameters in Repository, DataSource, EntityManager query methods

docs/data-source-api.md

@@ -141,6 +141,41 @@ await dataSource.transaction(async (manager) => {
 
 ```typescript
 const rawData = await dataSource.query(`SELECT * FROM USERS`)
+
+// You can also use parameters to avoid SQL injection
+// The syntax differs between the drivers
+
+// aurora-mysql, better-sqlite3, capacitor, cordova, 
+// expo, mariadb, mysql, nativescript, react-native, 
+// sap, sqlite, sqljs
+const rawData = await dataSource.query(
+    'SELECT * FROM USERS WHERE name = ? and age = ?',
+    [ 'John', 24 ]
+)
+
+// aurora-postgres, cockroachdb, postgres
+const rawData = await dataSource.query(
+    'SELECT * FROM USERS WHERE name = $1 and age = $2',
+    ['John', 24]
+)
+
+// oracle
+const rawData = await dataSource.query(
+    'SELECT * FROM USERS WHERE name = :1 and age = :2',
+    ['John', 24]
+)
+
+// spanner
+const rawData = await dataSource.query(
+    'SELECT * FROM USERS WHERE name = @param0 and age = @param1',
+    [ 'John', 24 ]
+)
+
+// mssql
+const rawData = await dataSource.query(
+    'SELECT * FROM USERS WHERE name = @0 and age = @1',
+    [ 'John', 24 ]
+)
 ```
 
 -   `createQueryBuilder` - Creates a query builder, which can be used to build queries.

docs/entity-manager-api.md

@@ -28,6 +28,41 @@ await manager.transaction(async (manager) => {
 
 ```typescript
 const rawData = await manager.query(`SELECT * FROM USERS`)
+
+// You can also use parameters to avoid SQL injection
+// The syntax differs between the drivers
+
+// aurora-mysql, better-sqlite3, capacitor, cordova, 
+// expo, mariadb, mysql, nativescript, react-native, 
+// sap, sqlite, sqljs
+const rawData = await manager.query(
+    'SELECT * FROM USERS WHERE name = ? and age = ?',
+    [ 'John', 24 ]
+)
+
+// aurora-postgres, cockroachdb, postgres
+const rawData = await manager.query(
+    'SELECT * FROM USERS WHERE name = $1 and age = $2',
+    ['John', 24]
+)
+
+// oracle
+const rawData = await manager.query(
+    'SELECT * FROM USERS WHERE name = :1 and age = :2',
+    ['John', 24]
+)
+
+// spanner
+const rawData = await manager.query(
+    'SELECT * FROM USERS WHERE name = @param0 and age = @param1',
+    [ 'John', 24 ]
+)
+
+// mssql
+const rawData = await manager.query(
+    'SELECT * FROM USERS WHERE name = @0 and age = @1',
+    [ 'John', 24 ]
+)
 ```
 
 -   `createQueryBuilder` - Creates a query builder use to build SQL queries.

docs/repository-api.md

@@ -391,6 +391,41 @@ const timber = await repository.findOneByOrFail({ firstName: "Timber" })
 
 ```typescript
 const rawData = await repository.query(`SELECT * FROM USERS`)
+
+// You can also use parameters to avoid SQL injection
+// The syntax differs between the drivers
+
+// aurora-mysql, better-sqlite3, capacitor, cordova, 
+// expo, mariadb, mysql, nativescript, react-native, 
+// sap, sqlite, sqljs
+const rawData = await repository.query(
+    'SELECT * FROM USERS WHERE name = ? and age = ?',
+    [ 'John', 24 ]
+)
+
+// aurora-postgres, cockroachdb, postgres
+const rawData = await repository.query(
+    'SELECT * FROM USERS WHERE name = $1 and age = $2',
+    ['John', 24]
+)
+
+// oracle
+const rawData = await repository.query(
+    'SELECT * FROM USERS WHERE name = :1 and age = :2',
+    ['John', 24]
+)
+
+// spanner
+const rawData = await repository.query(
+    'SELECT * FROM USERS WHERE name = @param0 and age = @param1',
+    [ 'John', 24 ]
+)
+
+// mssql
+const rawData = await repository.query(
+    'SELECT * FROM USERS WHERE name = @0 and age = @1',
+    [ 'John', 24 ]
+)
 ```
 
 -   `clear` - Clears all the data from the given table (truncates/drops it).

src/data-source/DataSource.ts

@@ -520,6 +520,8 @@ export class DataSource {
 
     /**
      * Executes raw SQL query and returns raw database results.
+     * 
+     * @see [Official docs](https://typeorm.io/data-source-api) for examples.
      */
     async query<T = any>(
         query: string,

src/entity-manager/EntityManager.ts

@@ -169,6 +169,8 @@ export class EntityManager {
 
     /**
      * Executes raw SQL query and returns raw database results.
+     * 
+     * @see [Official docs](https://typeorm.io/entity-manager-api) for examples.
      */
     async query<T = any>(query: string, parameters?: any[]): Promise<T> {
         return this.connection.query(query, parameters, this.queryRunner)

src/repository/Repository.ts

@@ -644,6 +644,8 @@ export class Repository<Entity extends ObjectLiteral> {
     /**
      * Executes a raw SQL query and returns a raw database results.
      * Raw query execution is supported only by relational databases (MongoDB is not supported).
+     * 
+     * @see [Official docs](https://typeorm.io/repository-api) for examples.
      */
     query(query: string, parameters?: any[]): Promise<any> {
         return this.manager.query(query, parameters)