#ctx.sql

ctx.sql bietet Funktionen zur Ausführung und Verwaltung von SQL, die häufig in RunJS (wie JSBlock, Ereignis-Workflows) verwendet werden, um direkt auf die Datenbank zuzugreifen. Es unterstützt die temporäre SQL-Ausführung, die Ausführung gespeicherter SQL-Vorlagen nach ID, Parameterbindung, Vorlagenvariablen ({{ctx.xxx}}) sowie die Steuerung des Ergebnistyps.

#Anwendungsfälle

Hinweis: ctx.sql greift über die flowSql-API auf die Datenbank zu. Stellen Sie sicher, dass der aktuelle Benutzer über die entsprechenden Ausführungsberechtigungen für die Datenquelle verfügt.

#Berechtigungen

Die Frontend-Logik für reguläre Benutzer sollte ctx.sql.runById(uid, options) verwenden. Wenn dynamisches SQL oder die Verwaltung von Vorlagen erforderlich ist, stellen Sie sicher, dass die aktuelle Rolle über SQL-Konfigurationsberechtigungen verfügt.

#Typdefinition

sql: FlowSQLRepository;

interface FlowSQLRepository {
  run<T = any>(
    sql: string,
    options?: {
      bind?: Record<string, any> | any[];
      type?: 'selectRows' | 'selectRow' | 'selectVar';
      dataSourceKey?: string;
      filter?: Record<string, any>;
    },
  ): Promise<T>;

  save(options: { uid: string; sql: string; dataSourceKey?: string }): Promise<void>;

  runById<T = any>(
    uid: string,
    options?: {
      bind?: Record<string, any> | any[];
      type?: 'selectRows' | 'selectRow' | 'selectVar';
      dataSourceKey?: string;
      filter?: Record<string, any>;
    },
  ): Promise<T>;

  destroy(uid: string): Promise<void>;
}

#Gängige Methoden

Hinweis:

• run wird zum Debuggen von SQL verwendet und erfordert Konfigurationsberechtigungen.
• save und destroy werden zur Verwaltung von SQL-Vorlagen verwendet und erfordern Konfigurationsberechtigungen.
• runById ist für reguläre Benutzer offen; es kann nur gespeicherte Vorlagen ausführen und das SQL weder debuggen noch ändern.
• Wenn eine SQL-Vorlage geändert wird, muss save aufgerufen werden, um die Änderungen zu speichern.

#Parameter

#Optionen für run / runById

#Optionen für save

#SQL-Vorlagenvariablen und Parameterbindung

#Vorlagenvariablen {{ctx.xxx}}

Sie können {{ctx.xxx}} in SQL verwenden, um auf Kontextvariablen zu verweisen. Diese werden vor der Ausführung in tatsächliche Werte aufgelöst:

// Verweis auf ctx.user.id
const user = await ctx.sql.run(
  'SELECT * FROM users WHERE id = {{ctx.user.id}}',
  { type: 'selectRow' }
);

Die Quellen für referenzierbare Variablen sind dieselben wie bei ctx.getVar() (z. B. ctx.user.*, ctx.record.*, benutzerdefinierte ctx.defineProperty usw.).

#Parameterbindung

• Benannte Parameter: Verwenden Sie :name im SQL und übergeben Sie ein Objekt { name: value } in bind.
• Positionsparameter: Verwenden Sie ? im SQL und übergeben Sie ein Array [value1, value2] in bind.

// Benannte Parameter
const users = await ctx.sql.run(
  'SELECT * FROM users WHERE status = :status AND age > :minAge',
  { bind: { status: 'active', minAge: 18 }, type: 'selectRows' }
);

// Positionsparameter
const count = await ctx.sql.run(
  'SELECT COUNT(*) AS total FROM users WHERE city = ? AND status = ?',
  { bind: ['Berlin', 'active'], type: 'selectVar' }
);

#Beispiele

#Temporäres SQL ausführen (Erfordert SQL-Konfigurationsberechtigung)

// Mehrere Zeilen (Standard)
const rows = await ctx.sql.run('SELECT * FROM users LIMIT 10');

// Einzelne Zeile
const user = await ctx.sql.run(
  'SELECT * FROM users WHERE id = :id',
  { bind: { id: 1 }, type: 'selectRow' }
);

// Einzelwert (z. B. COUNT, SUM)
const total = await ctx.sql.run(
  'SELECT COUNT(*) AS total FROM users',
  { type: 'selectVar' }
);

#Verwendung von Vorlagenvariablen

ctx.defineProperty('minId', { get: () => 1 });

const rows = await ctx.sql.run(
  'SELECT * FROM users WHERE id > {{ctx.minId}}',
  { type: 'selectRows' }
);

#Vorlagen speichern und wiederverwenden

// Speichern (Erfordert SQL-Konfigurationsberechtigung)
await ctx.sql.save({
  uid: 'active-users-report',
  sql: 'SELECT * FROM users WHERE status = :status ORDER BY created_at DESC',
});

// Jeder angemeldete Benutzer kann dies ausführen
const users = await ctx.sql.runById('active-users-report', {
  bind: { status: 'active' },
  type: 'selectRows',
});

// Vorlage löschen (Erfordert SQL-Konfigurationsberechtigung)
await ctx.sql.destroy('active-users-report');

#Paginierte Liste (SQLResource)

// Verwenden Sie SQLResource, wenn Paginierung oder Filterung erforderlich ist
ctx.initResource('SQLResource');
ctx.resource.setFilterByTk('saved-sql-uid');  // ID der gespeicherten SQL-Vorlage
ctx.resource.setBind({ status: 'active' });
await ctx.resource.refresh();
const data = ctx.resource.getData();
const meta = ctx.resource.getMeta();  // Enthält page, pageSize usw.

#Beziehung zu ctx.resource und ctx.request

ctx.sql kapselt die flowSql-API und ist auf SQL-Szenarien spezialisiert; ctx.request kann verwendet werden, um jede beliebige API aufzurufen.

#Wichtige Hinweise

• Verwenden Sie Parameterbindung (:name / ?) anstelle von String-Verkettung, um SQL-Injection zu vermeiden.
• type: 'selectVar' gibt einen skalaren Wert zurück, der normalerweise für COUNT, SUM usw. verwendet wird.
• Vorlagenvariablen {{ctx.xxx}} werden vor der Ausführung aufgelöst; stellen Sie sicher, dass die entsprechenden Variablen im Kontext definiert sind.

#Verwandte Themen

• ctx.resource: Datenressourcen; SQLResource ruft intern die flowSql-API auf.
• ctx.initResource(): Initialisiert SQLResource für paginierte Listen usw.
• ctx.request(): Allgemeine HTTP-Anfragen.