docs/ts/runtime/storage-sqldb.mdx
Represents a dedicated connection to a database.
BaseQueryExecutornew Connection(impl): Connection
SQLConn
BaseQueryExecutor.constructor
protected readonly impl: SQLConn
BaseQueryExecutor.impl
close(): Promise<void>
Returns the connection to the database pool.
Promise<void>
exec(strings, ...params): Promise<void>
exec executes a query without returning any rows.
TemplateStringsArray
...Primitive[]
Promise<void>
const email = "[email protected]";
const result = database.exec`DELETE FROM users WHERE email=${email}`
BaseQueryExecutor.exec
query<T>(strings, ...params): AsyncGenerator<T>
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.
T extends ResultRow = Record<string, any>
TemplateStringsArray
...Primitive[]
AsyncGenerator<T>
const email = "[email protected]";
const result = database.query`SELECT id FROM users WHERE email=${email}`
This produces the query: "SELECT id FROM users WHERE email=$1".
BaseQueryExecutor.query
queryAll<T>(strings, ...params): Promise<T[]>
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.
T extends ResultRow = Record<string, any>
TemplateStringsArray
...Primitive[]
Promise<T[]>
const email = "[email protected]";
const result = database.queryAll`SELECT id FROM users WHERE email=${email}`
This produces the query: "SELECT id FROM users WHERE email=$1".
BaseQueryExecutor.queryAll
queryRow<T>(strings, ...params): Promise<T | null>
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.
T extends ResultRow = Record<string, any>
TemplateStringsArray
...Primitive[]
Promise<T | null>
const email = "[email protected]";
const result = database.queryRow`SELECT id FROM users WHERE email=${email}`
BaseQueryExecutor.queryRow
rawExec(query, ...params): Promise<void>
rawExec executes a query without returning any rows.
string
The raw SQL query string.
...Primitive[]
The parameters to be used in the query.
Promise<void>
A promise that resolves when the query has been executed.
const query = "DELETE FROM users WHERE email=$1";
const email = "[email protected]";
await database.rawExec(query, email);
BaseQueryExecutor.rawExec
rawQuery<T>(query, ...params): AsyncGenerator<T>
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.
T extends ResultRow = Record<string, any>
string
The raw SQL query string.
...Primitive[]
The parameters to be used in the query.
AsyncGenerator<T>
An async generator that yields rows from the query result.
const query = "SELECT id FROM users WHERE email=$1";
const email = "[email protected]";
for await (const row of database.rawQuery(query, email)) {
console.log(row);
}
BaseQueryExecutor.rawQuery
rawQueryAll<T>(query, ...params): Promise<T[]>
rawQueryAll queries the database using a raw parametrised SQL query and parameters.
It returns an array of all results.
T extends ResultRow = Record<string, any>
string
...Primitive[]
Promise<T[]>
const query = "SELECT id FROM users WHERE email=$1";
const email = "[email protected]";
const rows = await database.rawQueryAll(query, email);
BaseQueryExecutor.rawQueryAll
rawQueryRow<T>(query, ...params): Promise<T | null>
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.
T extends ResultRow = Record<string, any>
string
The raw SQL query string.
...Primitive[]
The parameters to be used in the query.
Promise<T | null>
A promise that resolves to a single row or null.
const query = "SELECT id FROM users WHERE email=$1";
const email = "[email protected]";
const result = await database.rawQueryRow(query, email);
console.log(result);
BaseQueryExecutor.rawQueryRow
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.
BaseQueryExecutornew SQLDatabase(name, cfg?): SQLDatabase
string
BaseQueryExecutor.constructor
protected readonly impl: SQLDatabase
BaseQueryExecutor.impl
get connectionString(): string
Returns the connection string for the database
string
acquire(): Promise<Connection>
Acquires a database connection from the database pool.
When the connection is closed or is garbage-collected, it is returned to the pool.
Promise<Connection>
a new connection to the database
begin(): Promise<Transaction>
Begins a database transaction.
Prefer the await using pattern, which automatically rolls back
the transaction if neither commit nor rollback is called before
the variable goes out of scope:
await using tx = await db.begin();
await tx.exec`INSERT INTO ...`;
await tx.commit();
If you can't use await using, make sure to always call commit
or rollback yourself to prevent hanging transactions.
Promise<Transaction>
a transaction object that implements AsyncDisposable
exec(strings, ...params): Promise<void>
exec executes a query without returning any rows.
TemplateStringsArray
...Primitive[]
Promise<void>
const email = "[email protected]";
const result = database.exec`DELETE FROM users WHERE email=${email}`
BaseQueryExecutor.exec
query<T>(strings, ...params): AsyncGenerator<T>
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.
T extends ResultRow = Record<string, any>
TemplateStringsArray
...Primitive[]
AsyncGenerator<T>
const email = "[email protected]";
const result = database.query`SELECT id FROM users WHERE email=${email}`
This produces the query: "SELECT id FROM users WHERE email=$1".
BaseQueryExecutor.query
queryAll<T>(strings, ...params): Promise<T[]>
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.
T extends ResultRow = Record<string, any>
TemplateStringsArray
...Primitive[]
Promise<T[]>
const email = "[email protected]";
const result = database.queryAll`SELECT id FROM users WHERE email=${email}`
This produces the query: "SELECT id FROM users WHERE email=$1".
BaseQueryExecutor.queryAll
queryRow<T>(strings, ...params): Promise<T | null>
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.
T extends ResultRow = Record<string, any>
TemplateStringsArray
...Primitive[]
Promise<T | null>
const email = "[email protected]";
const result = database.queryRow`SELECT id FROM users WHERE email=${email}`
BaseQueryExecutor.queryRow
rawExec(query, ...params): Promise<void>
rawExec executes a query without returning any rows.
string
The raw SQL query string.
...Primitive[]
The parameters to be used in the query.
Promise<void>
A promise that resolves when the query has been executed.
const query = "DELETE FROM users WHERE email=$1";
const email = "[email protected]";
await database.rawExec(query, email);
BaseQueryExecutor.rawExec
rawQuery<T>(query, ...params): AsyncGenerator<T>
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.
T extends ResultRow = Record<string, any>
string
The raw SQL query string.
...Primitive[]
The parameters to be used in the query.
AsyncGenerator<T>
An async generator that yields rows from the query result.
const query = "SELECT id FROM users WHERE email=$1";
const email = "[email protected]";
for await (const row of database.rawQuery(query, email)) {
console.log(row);
}
BaseQueryExecutor.rawQuery
rawQueryAll<T>(query, ...params): Promise<T[]>
rawQueryAll queries the database using a raw parametrised SQL query and parameters.
It returns an array of all results.
T extends ResultRow = Record<string, any>
string
...Primitive[]
Promise<T[]>
const query = "SELECT id FROM users WHERE email=$1";
const email = "[email protected]";
const rows = await database.rawQueryAll(query, email);
BaseQueryExecutor.rawQueryAll
rawQueryRow<T>(query, ...params): Promise<T | null>
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.
T extends ResultRow = Record<string, any>
string
The raw SQL query string.
...Primitive[]
The parameters to be used in the query.
Promise<T | null>
A promise that resolves to a single row or null.
const query = "SELECT id FROM users WHERE email=$1";
const email = "[email protected]";
const result = await database.rawQueryRow(query, email);
console.log(result);
BaseQueryExecutor.rawQueryRow
static named<name>(name): SQLDatabase
Reference an existing database by name, if the database doesn't
exist yet, use new Database(name) instead.
name extends string
StringLiteral<name>
Represents a database transaction.
Transaction implements AsyncDisposable, so the recommended usage is
the await using pattern — it automatically rolls back the transaction
if neither commit nor rollback is called before the variable goes
out of scope:
await using tx = await db.begin();
await tx.exec`INSERT INTO ...`;
await tx.commit();
If you can't use await using, make sure to always call commit or
rollback yourself to prevent hanging transactions.
BaseQueryExecutorAsyncDisposablenew Transaction(impl): Transaction
Transaction
BaseQueryExecutor.constructor
protected readonly impl: Transaction
BaseQueryExecutor.impl
asyncDispose: Promise<void>
Promise<void>
AsyncDisposable.[asyncDispose]
commit(): Promise<void>
Commit the transaction.
Promise<void>
exec(strings, ...params): Promise<void>
exec executes a query without returning any rows.
TemplateStringsArray
...Primitive[]
Promise<void>
const email = "[email protected]";
const result = database.exec`DELETE FROM users WHERE email=${email}`
BaseQueryExecutor.exec
query<T>(strings, ...params): AsyncGenerator<T>
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.
T extends ResultRow = Record<string, any>
TemplateStringsArray
...Primitive[]
AsyncGenerator<T>
const email = "[email protected]";
const result = database.query`SELECT id FROM users WHERE email=${email}`
This produces the query: "SELECT id FROM users WHERE email=$1".
BaseQueryExecutor.query
queryAll<T>(strings, ...params): Promise<T[]>
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.
T extends ResultRow = Record<string, any>
TemplateStringsArray
...Primitive[]
Promise<T[]>
const email = "[email protected]";
const result = database.queryAll`SELECT id FROM users WHERE email=${email}`
This produces the query: "SELECT id FROM users WHERE email=$1".
BaseQueryExecutor.queryAll
queryRow<T>(strings, ...params): Promise<T | null>
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.
T extends ResultRow = Record<string, any>
TemplateStringsArray
...Primitive[]
Promise<T | null>
const email = "[email protected]";
const result = database.queryRow`SELECT id FROM users WHERE email=${email}`
BaseQueryExecutor.queryRow
rawExec(query, ...params): Promise<void>
rawExec executes a query without returning any rows.
string
The raw SQL query string.
...Primitive[]
The parameters to be used in the query.
Promise<void>
A promise that resolves when the query has been executed.
const query = "DELETE FROM users WHERE email=$1";
const email = "[email protected]";
await database.rawExec(query, email);
BaseQueryExecutor.rawExec
rawQuery<T>(query, ...params): AsyncGenerator<T>
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.
T extends ResultRow = Record<string, any>
string
The raw SQL query string.
...Primitive[]
The parameters to be used in the query.
AsyncGenerator<T>
An async generator that yields rows from the query result.
const query = "SELECT id FROM users WHERE email=$1";
const email = "[email protected]";
for await (const row of database.rawQuery(query, email)) {
console.log(row);
}
BaseQueryExecutor.rawQuery
rawQueryAll<T>(query, ...params): Promise<T[]>
rawQueryAll queries the database using a raw parametrised SQL query and parameters.
It returns an array of all results.
T extends ResultRow = Record<string, any>
string
...Primitive[]
Promise<T[]>
const query = "SELECT id FROM users WHERE email=$1";
const email = "[email protected]";
const rows = await database.rawQueryAll(query, email);
BaseQueryExecutor.rawQueryAll
rawQueryRow<T>(query, ...params): Promise<T | null>
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.
T extends ResultRow = Record<string, any>
string
The raw SQL query string.
...Primitive[]
The parameters to be used in the query.
Promise<T | null>
A promise that resolves to a single row or null.
const query = "SELECT id FROM users WHERE email=$1";
const email = "[email protected]";
const result = await database.rawQueryRow(query, email);
console.log(result);
BaseQueryExecutor.rawQueryRow
rollback(): Promise<void>
Rollback the transaction.
Promise<void>
Configuration for a SQLDatabase.
optional migrations?: string | SQLMigrationsConfig
Configures how database migrations are managed for a SQLDatabase.
path: string
optional source?: "prisma" | "drizzle" | "drizzle/v1"
type Primitive =
| string
| string[]
| number
| number[]
| boolean
| boolean[]
| Buffer
| Date
| Date[]
| Record<string, any>
| Record<string, any>[]
| BigInt
| BigInt[]
| null
| undefined;
Represents a type that can be used in query template literals
type ResultRow = Record<string, any>
Represents a single row from a query result
<!-- symbol-end -->