encore.dev 1.46.17 → 1.46.18

package/storage/sqldb/database.ts

@@ -34,38 +34,14 @@ export type Primitive =
   | null
   | undefined;
 
-/**
- * Constructing a new database object will result in Encore provisioning a database with
- * that name and returning this object to represent it.
- *
- * If you want to reference an existing database, use `Database.Named(name)` as it is a
- * compile error to create duplicate databases.
- */
-export class SQLDatabase {
-  private readonly impl: runtime.SQLDatabase;
-
-  /**
-   * Creates a new database with the given name and configuration
-   */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  constructor(name: string, cfg?: SQLDatabaseConfig) {
-    this.impl = runtime.RT.sqlDatabase(name);
-  }
-
-  /**
-   * Reference an existing database by name, if the database doesn't
-   * exist yet, use `new Database(name)` instead.
-   */
-  static named<name extends string>(name: StringLiteral<name>): SQLDatabase {
-    return new SQLDatabase(name);
-  }
+type SQLQueryExecutor =
+  | runtime.SQLConn
+  | runtime.SQLDatabase
+  | runtime.Transaction;
 
-  /**
-   * Returns the connection string for the database
-   */
-  get connectionString(): string {
-    return this.impl.connString();
-  }
+/** Base class containing shared query functionality */
+class BaseQueryExecutor {
+  constructor(protected readonly impl: SQLQueryExecutor) {}
 
   /**
    * query queries the database using a template string, replacing your placeholders in the template
@@ -92,9 +68,7 @@ export class SQLDatabase {
     const cursor = await this.impl.query(query, args, source);
     while (true) {
       const row = await cursor.next();
-      if (row === null) {
-        break;
-      }
+      if (row === null) break;
       yield row.values() as T;
     }
   }
@@ -125,10 +99,7 @@ export class SQLDatabase {
     const result = await this.impl.query(query, args, source);
     while (true) {
       const row = await result.next();
-      if (row === null) {
-        break;
-      }
-
+      if (row === null) break;
       yield row.values() as T;
     }
   }
@@ -158,12 +129,9 @@ export class SQLDatabase {
     const result: T[] = [];
     while (true) {
       const row = await cursor.next();
-      if (row === null) {
-        break;
-      }
+      if (row === null) break;
       result.push(row.values() as T);
     }
-
     return result;
   }
 
@@ -189,12 +157,9 @@ export class SQLDatabase {
     const result: T[] = [];
     while (true) {
       const row = await cursor.next();
-      if (row === null) {
-        break;
-      }
+      if (row === null) break;
       result.push(row.values() as T);
     }
-
     return result;
   }
 
@@ -216,10 +181,8 @@ export class SQLDatabase {
     const args = buildQueryArgs(params);
     const source = getCurrentRequest();
     const result = await this.impl.query(query, args, source);
-    while (true) {
-      const row = await result.next();
-      return row ? (row.values() as T) : null;
-    }
+    const row = await result.next();
+    return row ? (row.values() as T) : null;
   }
 
   /**
@@ -244,10 +207,8 @@ export class SQLDatabase {
     const args = buildQueryArgs(params);
     const source = getCurrentRequest();
     const result = await this.impl.query(query, args, source);
-    while (true) {
-      const row = await result.next();
-      return row ? (row.values() as T) : null;
-    }
+    const row = await result.next();
+    return row ? (row.values() as T) : null;
   }
 
   /**
@@ -267,7 +228,7 @@ export class SQLDatabase {
 
     // Need to await the cursor to process any errors from things like
     // unique constraint violations.
-    let cur = await this.impl.query(query, args, source);
+    const cur = await this.impl.query(query, args, source);
     await cur.next();
   }
 
@@ -289,263 +250,112 @@ export class SQLDatabase {
 
     // Need to await the cursor to process any errors from things like
     // unique constraint violations.
-    let cur = await this.impl.query(query, args, source);
+    const cur = await this.impl.query(query, args, source);
     await cur.next();
   }
-
-  /**
-   * Acquires a database connection from the database pool.
-   *
-   * When the connection is closed or is garbage-collected, it is returned to the pool.
-   * @returns a new connection to the database
-   */
-  async acquire(): Promise<Connection> {
-    const impl = await this.impl.acquire();
-    return new Connection(impl);
-  }
 }
 
 /**
- * Represents a dedicated connection to a database.
+ * Constructing a new database object will result in Encore provisioning a database with
+ * that name and returning this object to represent it.
+ *
+ * If you want to reference an existing database, use `Database.Named(name)` as it is a
+ * compile error to create duplicate databases.
  */
-export class Connection {
-  private readonly impl: runtime.SQLConn;
+export class SQLDatabase extends BaseQueryExecutor {
+  protected declare readonly impl: runtime.SQLDatabase;
 
-  constructor(impl: runtime.SQLConn) {
-    this.impl = impl;
+  constructor(name: string, cfg?: SQLDatabaseConfig) {
+    super(runtime.RT.sqlDatabase(name));
   }
 
   /**
-   * Returns the connection to the database pool.
+   * Reference an existing database by name, if the database doesn't
+   * exist yet, use `new Database(name)` instead.
    */
-  async close() {
-    await this.impl.close();
+  static named<name extends string>(name: StringLiteral<name>): SQLDatabase {
+    return new SQLDatabase(name);
   }
 
   /**
-   * query queries the database using a template string, replacing your placeholders in the template
-   * with parametrised values without risking SQL injections.
-   *
-   * It returns an async generator, that allows iterating over the results
-   * in a streaming fashion using `for await`.
-   *
-   * @example
-   *
-   * const email = "foo@example.com";
-   * const result = database.query`SELECT id FROM users WHERE email=${email}`
-   *
-   * This produces the query: "SELECT id FROM users WHERE email=$1".
+   * Returns the connection string for the database
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  async *query<T extends Row = Record<string, any>>(
-    strings: TemplateStringsArray,
-    ...params: Primitive[]
-  ): AsyncGenerator<T> {
-    const query = buildQuery(strings, params);
-    const args = buildQueryArgs(params);
-    const source = getCurrentRequest();
-    const cursor = await this.impl.query(query, args, source);
-    while (true) {
-      const row = await cursor.next();
-      if (row === null) {
-        break;
-      }
-      yield row.values() as T;
-    }
+  get connectionString(): string {
+    return this.impl.connString();
   }
 
   /**
-   * rawQuery queries the database using a raw parametrised SQL query and parameters.
-   *
-   * It returns an async generator, that allows iterating over the results
-   * in a streaming fashion using `for await`.
-   *
-   * @example
-   * const query = "SELECT id FROM users WHERE email=$1";
-   * const email = "foo@example.com";
-   * for await (const row of database.rawQuery(query, email)) {
-   *   console.log(row);
-   * }
+   * Acquires a database connection from the database pool.
    *
-   * @param query - The raw SQL query string.
-   * @param params - The parameters to be used in the query.
-   * @returns An async generator that yields rows from the query result.
+   * When the connection is closed or is garbage-collected, it is returned to the pool.
+   * @returns a new connection to the database
    */
-  async *rawQuery<T extends Row = Record<string, any>>(
-    query: string,
-    ...params: Primitive[]
-  ): AsyncGenerator<T> {
-    const args = buildQueryArgs(params);
-    const source = getCurrentRequest();
-    const result = await this.impl.query(query, args, source);
-    while (true) {
-      const row = await result.next();
-      if (row === null) {
-        break;
-      }
-
-      yield row.values() as T;
-    }
+  async acquire(): Promise<Connection> {
+    const impl = await this.impl.acquire();
+    return new Connection(impl);
   }
 
   /**
-   * queryAll queries the database using a template string, replacing your placeholders in the template
-   * with parametrised values without risking SQL injections.
-   *
-   * It returns an array of all results.
-   *
-   * @example
+   * Begins a database transaction.
    *
-   * const email = "foo@example.com";
-   * const result = database.queryAll`SELECT id FROM users WHERE email=${email}`
-   *
-   * This produces the query: "SELECT id FROM users WHERE email=$1".
+   * Make sure to always call `rollback` or `commit` to prevent hanging transactions.
+   * @returns a transaction object that implements AsycDisposable
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  async queryAll<T extends Row = Record<string, any>>(
-    strings: TemplateStringsArray,
-    ...params: Primitive[]
-  ): Promise<T[]> {
-    const query = buildQuery(strings, params);
-    const args = buildQueryArgs(params);
+  async begin(): Promise<Transaction> {
     const source = getCurrentRequest();
-    const cursor = await this.impl.query(query, args, source);
-    const result: T[] = [];
-    while (true) {
-      const row = await cursor.next();
-      if (row === null) {
-        break;
-      }
-      result.push(row.values() as T);
-    }
-
-    return result;
+    const impl = await this.impl.begin(source);
+    return new Transaction(impl);
   }
+}
 
-  /**
-   * rawQueryAll queries the database using a raw parametrised SQL query and parameters.
-   *
-   * It returns an array of all results.
-   *
-   * @example
-   *
-   * const query = "SELECT id FROM users WHERE email=$1";
-   * const email = "foo@example.com";
-   * const rows = await database.rawQueryAll(query, email);
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  async rawQueryAll<T extends Row = Record<string, any>>(
-    query: string,
-    ...params: Primitive[]
-  ): Promise<T[]> {
-    const args = buildQueryArgs(params);
-    const source = getCurrentRequest();
-    const cursor = await this.impl.query(query, args, source);
-    const result: T[] = [];
-    while (true) {
-      const row = await cursor.next();
-      if (row === null) {
-        break;
-      }
-      result.push(row.values() as T);
-    }
+export class Transaction extends BaseQueryExecutor implements AsyncDisposable {
+  protected declare readonly impl: runtime.Transaction;
+  private done: boolean = false;
 
-    return result;
+  constructor(impl: runtime.Transaction) {
+    super(impl);
   }
 
   /**
-   * queryRow is like query but returns only a single row.
-   * If the query selects no rows it returns null.
-   * Otherwise it returns the first row and discards the rest.
-   *
-   * @example
-   * const email = "foo@example.com";
-   * const result = database.queryRow`SELECT id FROM users WHERE email=${email}`
+   * Commit the transaction.
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  async queryRow<T extends Row = Record<string, any>>(
-    strings: TemplateStringsArray,
-    ...params: Primitive[]
-  ): Promise<T | null> {
-    const query = buildQuery(strings, params);
-    const args = buildQueryArgs(params);
+  async commit() {
+    this.done = true;
     const source = getCurrentRequest();
-    const result = await this.impl.query(query, args, source);
-    while (true) {
-      const row = await result.next();
-      return row ? (row.values() as T) : null;
-    }
+    await this.impl.commit(source);
   }
 
   /**
-   * rawQueryRow is like rawQuery but returns only a single row.
-   * If the query selects no rows, it returns null.
-   * Otherwise, it returns the first row and discards the rest.
-   *
-   * @example
-   * const query = "SELECT id FROM users WHERE email=$1";
-   * const email = "foo@example.com";
-   * const result = await database.rawQueryRow(query, email);
-   * console.log(result);
-   *
-   * @param query - The raw SQL query string.
-   * @param params - The parameters to be used in the query.
-   * @returns A promise that resolves to a single row or null.
+   * Rollback the transaction.
    */
-  async rawQueryRow<T extends Row = Record<string, any>>(
-    query: string,
-    ...params: Primitive[]
-  ): Promise<T | null> {
-    const args = buildQueryArgs(params);
+  async rollback() {
+    this.done = true;
     const source = getCurrentRequest();
-    const result = await this.impl.query(query, args, source);
-    while (true) {
-      const row = await result.next();
-      return row ? (row.values() as T) : null;
+    await this.impl.rollback(source);
+  }
+
+  async [Symbol.asyncDispose]() {
+    if (!this.done) {
+      await this.rollback();
     }
   }
+}
 
-  /**
-   * exec executes a query without returning any rows.
-   *
-   * @example
-   * const email = "foo@example.com";
-   * const result = database.exec`DELETE FROM users WHERE email=${email}`
-   */
-  async exec(
-    strings: TemplateStringsArray,
-    ...params: Primitive[]
-  ): Promise<void> {
-    const query = buildQuery(strings, params);
-    const args = buildQueryArgs(params);
-    const source = getCurrentRequest();
+/**
+ * Represents a dedicated connection to a database.
+ */
+export class Connection extends BaseQueryExecutor {
+  protected declare readonly impl: runtime.SQLConn;
 
-    // Need to await the cursor to process any errors from things like
-    // unique constraint violations.
-    let cur = await this.impl.query(query, args, source);
-    await cur.next();
+  constructor(impl: runtime.SQLConn) {
+    super(impl);
   }
 
   /**
-   * rawExec executes a query without returning any rows.
-   *
-   * @example
-   * const query = "DELETE FROM users WHERE email=$1";
-   * const email = "foo@example.com";
-   * await database.rawExec(query, email);
-   *
-   * @param query - The raw SQL query string.
-   * @param params - The parameters to be used in the query.
-   * @returns A promise that resolves when the query has been executed.
+   * Returns the connection to the database pool.
    */
-  async rawExec(query: string, ...params: Primitive[]): Promise<void> {
-    const args = buildQueryArgs(params);
-    const source = getCurrentRequest();
-
-    // Need to await the cursor to process any errors from things like
-    // unique constraint violations.
-    let cur = await this.impl.query(query, args, source);
-    await cur.next();
+  async close() {
+    await this.impl.close();
   }
 }