The best way to control Claude Code, Codex and more from any computer or phone

main
ts 287 lines 10 KB
Raw
1 import type * as data from "@distilled.cloud/aws/redshift-data";
2 import * as Binding from "alchemy/Binding";
3 import * as Data from "effect/Data";
4 import type * as Effect from "effect/Effect";
5 import type { Workgroup } from "../RedshiftServerless/Workgroup.ts";
6
7 /**
8 * Options that pin every statement run through this binding to a database and,
9 * optionally, an authentication method.
10 */
11 export interface StatementsOptions {
12 /**
13 * Database to run statements against.
14 * @default "dev"
15 */
16 database?: string;
17 /**
18 * ARN of a Secrets Manager secret holding the database credentials. Omit to
19 * authenticate with the Lambda's IAM identity via
20 * `redshift-serverless:GetCredentials`.
21 */
22 secretArn?: string;
23 /**
24 * Database user to connect as. Only used with secret/temporary-credential
25 * auth flows that require an explicit user.
26 */
27 dbUser?: string;
28 }
29
30 /**
31 * Fields the binding injects on every request: the workgroup, the pinned
32 * database, and the auth fields resolved from {@link StatementsOptions}
33 * (cluster-only fields are excluded because this binding targets Serverless).
34 */
35 type InjectedFields = "WorkgroupName" | "Database" | "ClusterIdentifier" | "SecretArn" | "DbUser";
36
37 /**
38 * `executeStatement` input minus the identifiers this binding injects
39 * (workgroup, database, and the cluster-only fields).
40 */
41 export interface ExecuteStatementRequest extends Omit<data.ExecuteStatementInput, InjectedFields> {}
42
43 /**
44 * `batchExecuteStatement` input minus the identifiers this binding injects
45 * (workgroup, database, and the cluster-only fields).
46 */
47 export interface BatchExecuteStatementRequest extends Omit<
48 data.BatchExecuteStatementInput,
49 InjectedFields
50 > {}
51
52 /**
53 * `describeTable` input minus the injected identifiers. Use
54 * `ConnectedDatabase` to introspect a database other than the pinned one.
55 */
56 export interface DescribeTableRequest extends Omit<data.DescribeTableRequest, InjectedFields> {}
57
58 /**
59 * `listDatabases` input minus the injected identifiers.
60 */
61 export interface ListDatabasesRequest extends Omit<data.ListDatabasesRequest, InjectedFields> {}
62
63 /**
64 * `listSchemas` input minus the injected identifiers.
65 */
66 export interface ListSchemasRequest extends Omit<data.ListSchemasRequest, InjectedFields> {}
67
68 /**
69 * `listTables` input minus the injected identifiers.
70 */
71 export interface ListTablesRequest extends Omit<data.ListTablesRequest, InjectedFields> {}
72
73 /**
74 * `listStatements` input minus the workgroup identifier this binding injects.
75 * `Database`, `Status`, and `StatementName` remain available as filters.
76 */
77 export interface ListStatementsRequest extends Omit<
78 data.ListStatementsRequest,
79 "ClusterIdentifier" | "WorkgroupName"
80 > {}
81
82 /**
83 * Raised when a statement reaches a terminal `FAILED` or `ABORTED` status
84 * while a composite `query` waits for it to finish.
85 */
86 export class RedshiftStatementFailed extends Data.TaggedError("RedshiftStatementFailed")<{
87 /**
88 * ID of the failed statement.
89 */
90 readonly statementId: string;
91 /**
92 * Terminal status the statement ended in (`"FAILED"` or `"ABORTED"`).
93 */
94 readonly status: string;
95 /**
96 * Error message reported by Redshift, if any.
97 */
98 readonly error: string | undefined;
99 }> {}
100
101 /**
102 * Runtime client for the Redshift Data API scoped to a single workgroup +
103 * database.
104 */
105 export interface StatementsClient {
106 /**
107 * Submit a SQL statement. Returns immediately with the statement `Id`;
108 * results are fetched asynchronously via {@link describe}/{@link getResult}.
109 */
110 readonly execute: (
111 request: ExecuteStatementRequest,
112 ) => Effect.Effect<data.ExecuteStatementOutput, data.ExecuteStatementError>;
113 /**
114 * Submit a batch of SQL statements that run in order as one transaction.
115 * Returns immediately with the batch statement `Id`; sub-statement ids
116 * (`{Id}:1`, `{Id}:2`, ...) are reported by {@link describe}.
117 */
118 readonly executeBatch: (
119 request: BatchExecuteStatementRequest,
120 ) => Effect.Effect<data.BatchExecuteStatementOutput, data.BatchExecuteStatementError>;
121 /**
122 * Describe a submitted statement (status, timing, row counts).
123 */
124 readonly describe: (
125 id: string,
126 ) => Effect.Effect<data.DescribeStatementResponse, data.DescribeStatementError>;
127 /**
128 * Cancel a running statement. Returns `Status: true` when the cancellation
129 * was accepted.
130 */
131 readonly cancel: (
132 id: string,
133 ) => Effect.Effect<data.CancelStatementResponse, data.CancelStatementError>;
134 /**
135 * Fetch the cached result rows of a finished statement (JSON result
136 * format). Pass `nextToken` to page through large result sets.
137 */
138 readonly getResult: (
139 id: string,
140 nextToken?: string,
141 ) => Effect.Effect<data.GetStatementResultResponse, data.GetStatementResultError>;
142 /**
143 * Fetch the cached result rows of a finished statement that ran with
144 * `ResultFormat: "CSV"`. Pass `nextToken` to page through large result
145 * sets.
146 */
147 readonly getResultV2: (
148 id: string,
149 nextToken?: string,
150 ) => Effect.Effect<data.GetStatementResultV2Response, data.GetStatementResultV2Error>;
151 /**
152 * Describe a table's columns from the database metadata.
153 */
154 readonly describeTable: (
155 request: DescribeTableRequest,
156 ) => Effect.Effect<data.DescribeTableResponse, data.DescribeTableError>;
157 /**
158 * List the databases in the workgroup.
159 */
160 readonly listDatabases: (
161 request?: ListDatabasesRequest,
162 ) => Effect.Effect<data.ListDatabasesResponse, data.ListDatabasesError>;
163 /**
164 * List the schemas in the pinned database.
165 */
166 readonly listSchemas: (
167 request?: ListSchemasRequest,
168 ) => Effect.Effect<data.ListSchemasResponse, data.ListSchemasError>;
169 /**
170 * List the tables in the pinned database, optionally filtered by
171 * `SchemaPattern`/`TablePattern`.
172 */
173 readonly listTables: (
174 request?: ListTablesRequest,
175 ) => Effect.Effect<data.ListTablesResponse, data.ListTablesError>;
176 /**
177 * List statements previously run through the Data API on this workgroup
178 * by the caller's identity.
179 */
180 readonly listStatements: (
181 request?: ListStatementsRequest,
182 ) => Effect.Effect<data.ListStatementsResponse, data.ListStatementsError>;
183 /**
184 * Run a SQL statement and wait (bounded) for it to finish, returning its
185 * result rows. Fails with {@link RedshiftStatementFailed} if the statement
186 * ends in `FAILED`/`ABORTED`.
187 */
188 readonly query: (
189 sql: string,
190 parameters?: data.SqlParameter[],
191 ) => Effect.Effect<
192 data.GetStatementResultResponse,
193 | data.ExecuteStatementError
194 | data.DescribeStatementError
195 | data.GetStatementResultError
196 | RedshiftStatementFailed
197 >;
198 }
199
200 /**
201 * Runtime binding for the Amazon Redshift Data API against a Serverless
202 * {@link Workgroup}. Exposes the full Data API surface —
203 * `execute`/`executeBatch`/`describe`/`cancel`/`getResult`/`getResultV2`,
204 * the metadata reads (`describeTable`, `listDatabases`, `listSchemas`,
205 * `listTables`, `listStatements`) — plus a composite `query` that submits a
206 * statement and polls until it finishes.
207 *
208 * At deploy time it grants the workgroup-scoped Data API actions on the
209 * workgroup (plus `redshift-serverless:GetCredentials` for IAM auth) and the
210 * statement-scoped actions (`DescribeStatement`, `GetStatementResult`,
211 * `GetStatementResultV2`, `CancelStatement`, `ListStatements`) which AWS
212 * authorizes per statement owner rather than by ARN. The Data API is
213 * HTTP-based — no driver, no VPC reach, and no credential plumbing required.
214 * Provide the implementation with
215 * `Effect.provide(AWS.RedshiftData.StatementsHttp)`.
216 *
217 * ### Running SQL
218 * **Example:** Query a Workgroup
219 * ```typescript
220 * const sql = yield* RedshiftData.Statements(workgroup, { database: "dev" });
221 * const result = yield* sql.query("SELECT 1 AS n");
222 * // result.Records -> [[{ longValue: 1 }]]
223 * ```
224 *
225 * **Example:** Run a Batch of Statements in One Transaction
226 * ```typescript
227 * const submitted = yield* sql.executeBatch({
228 * Sqls: ["CREATE TABLE IF NOT EXISTS events(id int)", "INSERT INTO events VALUES (1)"],
229 * });
230 * // sub-statement ids are `${submitted.Id}:1`, `${submitted.Id}:2`
231 * const described = yield* sql.describe(submitted.Id!);
232 * ```
233 *
234 * **Example:** Cancel a Running Statement
235 * ```typescript
236 * const submitted = yield* sql.execute({ Sql: "SELECT count(*) FROM big_table" });
237 * const { Status } = yield* sql.cancel(submitted.Id!);
238 * ```
239 *
240 * ### Browsing Metadata
241 * **Example:** List Databases, Schemas and Tables
242 * ```typescript
243 * const { Databases } = yield* sql.listDatabases();
244 * const { Schemas } = yield* sql.listSchemas({ SchemaPattern: "public" });
245 * const { Tables } = yield* sql.listTables({ SchemaPattern: "public" });
246 * const { ColumnList } = yield* sql.describeTable({ Schema: "public", Table: "events" });
247 * ```
248 *
249 * **Example:** Serve Query Results from a Lambda Function
250 * ```typescript
251 * export default QueryFunction.make(
252 * { main: import.meta.url, functionUrl: true },
253 * Effect.gen(function* () {
254 * const namespace = yield* RedshiftServerless.Namespace("Analytics", {
255 * dbName: "analytics",
256 * adminUsername: "admin",
257 * manageAdminPassword: true,
258 * });
259 * const workgroup = yield* RedshiftServerless.Workgroup("Analytics", {
260 * namespaceName: namespace.namespaceName,
261 * baseCapacity: 8,
262 * });
263 * // init — bind the Data API to the workgroup
264 * const sql = yield* RedshiftData.Statements(workgroup, {
265 * database: "analytics",
266 * });
267 *
268 * return {
269 * fetch: Effect.gen(function* () {
270 * // runtime — submit a statement and wait for its rows
271 * const result = yield* sql.query("SELECT count(*) AS n FROM events");
272 * return yield* HttpServerResponse.json({ records: result.Records });
273 * }).pipe(Effect.orDie),
274 * };
275 * }).pipe(Effect.provide(RedshiftData.StatementsHttp)),
276 * );
277 * ```
278 *
279 * @binding
280 */
281 export interface Statements extends Binding.Service<
282 Statements,
283 "AWS.RedshiftData.Statements",
284 (workgroup: Workgroup, options?: StatementsOptions) => Effect.Effect<StatementsClient>
285 > {}
286
287 export const Statements = Binding.Service<Statements>("AWS.RedshiftData.Statements");