sqlsrv_query — Funktion · PHP-Referenz

Signatur

sqlsrv_query(resource $conn, string $tsql, array $params = [], array $options = []): resource|false

Beschreibung

sqlsrv_query() ist die kompakte Variante, um SQL-Anweisungen über den SQLSRV-Treiber auszuführen. Die Funktion kombiniert intern sqlsrv_prepare() und sqlsrv_execute(), sodass Vorbereitung und Ausführung einer Abfrage in einem einzigen Aufruf erfolgen. Sie eignet sich besonders für Abfragen, die nur einmalig ausgeführt werden.

Über den optionalen Parameter $params lassen sich parametrisierte Abfragen realisieren. Jeder Parameter kann entweder als einfacher Wert oder als Array der Form [$wert, $richtung, $phpTyp, $sqlTyp] übergeben werden. Parametrisierung schützt zuverlässig vor SQL-Injection und sollte immer verwendet werden, wenn Nutzereingaben in die Abfrage einfließen.

Der Rückgabewert ist eine Statement-Ressource, die mit Funktionen wie sqlsrv_fetch_array(), sqlsrv_fetch_object() oder sqlsrv_rows_affected() weiterverarbeitet werden kann. Im Fehlerfall wird false zurückgegeben; Fehlerdetails sind dann über sqlsrv_errors() abrufbar.

Soll dieselbe Abfrage mehrfach mit unterschiedlichen Parametern ausgeführt werden, ist es effizienter, sqlsrv_prepare() separat zu verwenden und anschließend sqlsrv_execute() in einer Schleife aufzurufen, da sqlsrv_query() die Abfrage bei jedem Aufruf neu vorbereitet.

Parameter

Name	Typ	Default	Beschreibung
$conn Pflicht	resource		Eine gültige Verbindungsressource, die von `sqlsrv_connect()` zurückgegeben wurde.
$tsql Pflicht	string		Die auszuführende Transact-SQL-Anweisung. Platzhalter für Parameter werden als `?` angegeben.
$params	array	[]	Optionales Array mit Parameterwerten, die den `?`-Platzhaltern in der Reihenfolge entsprechen. Jeder Eintrag kann ein einfacher Wert oder ein Array `[$wert, $richtung, $phpTyp, $sqlTyp]` sein.
$options	array	[]	Optionales assoziatives Array mit Abfrageoptionen, z. B. `'Scrollable'`, `'SendStreamParamsAtExec'` oder `'QueryTimeout'`.

Rückgabewert

Typ

resource|false

Beschreibung

Bei Erfolg eine Statement-Ressource, die für das Abrufen von Ergebnissen verwendet werden kann. Bei einem Fehler wird false zurückgegeben; Details sind über sqlsrv_errors() abrufbar.

Beispiele

Einfache SELECT-Abfrage mit Parameter

<?php
$serverName = 'localhost';
$connectionInfo = ['Database' => 'AdventureWorks', 'UID' => 'sa', 'PWD' => 'geheim'];
$conn = sqlsrv_connect($serverName, $connectionInfo);

if ($conn === false) {
    die(print_r(sqlsrv_errors(), true));
}

$tsql   = 'SELECT FirstName, LastName FROM Person.Person WHERE BusinessEntityID = ?';
$params = [42];

$stmt = sqlsrv_query($conn, $tsql, $params);

if ($stmt === false) {
    die(print_r(sqlsrv_errors(), true));
}

while ($row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC)) {
    echo $row['FirstName'] . ' ' . $row['LastName'] . PHP_EOL;
}

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);

Ken Sánchez

INSERT mit mehreren Parametern und Fehlerbehandlung

<?php
$serverName = 'localhost';
$connectionInfo = ['Database' => 'MeineDB', 'UID' => 'sa', 'PWD' => 'geheim'];
$conn = sqlsrv_connect($serverName, $connectionInfo);

if ($conn === false) {
    die(print_r(sqlsrv_errors(), true));
}

$tsql = 'INSERT INTO Benutzer (Name, Email, Erstellt) VALUES (?, ?, ?)';
$params = [
    'Max Mustermann',
    'max@example.com',
    ['2024-01-15', SQLSRV_PARAM_IN, null, SQLSRV_SQLTYPE_DATE],
];

$stmt = sqlsrv_query($conn, $tsql, $params);

if ($stmt === false) {
    echo 'Fehler beim Einfügen:' . PHP_EOL;
    print_r(sqlsrv_errors());
} else {
    $betroffeneZeilen = sqlsrv_rows_affected($stmt);
    echo "Erfolgreich eingefügt. Betroffene Zeilen: $betroffeneZeilen" . PHP_EOL;
}

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);

Erfolgreich eingefügt. Betroffene Zeilen: 1

// Wichtig · Fallstricke

SQL-Injection: Verwende grundsätzlich parametrisierte Abfragen (das $params-Array), anstatt Nutzereingaben direkt in den SQL-String zu interpolieren. sqlsrv_query() verarbeitet Parameter serverseitig gebunden und schützt damit vor Injection-Angriffen.

Performance: Wird dieselbe Abfrage in einer Schleife viele Male ausgeführt, sollte stattdessen sqlsrv_prepare() zusammen mit sqlsrv_execute() verwendet werden, da sqlsrv_query() bei jedem Aufruf eine neue Vorbereitung durchführt.

Ressourcen freigeben: Nach der Verwendung sollte die zurückgegebene Statement-Ressource immer mit sqlsrv_free_stmt() freigegeben werden, um Speicher zu sparen.

Voraussetzung: Die Funktion ist nur verfügbar, wenn die SQLSRV-Extension (Microsoft Drivers for PHP for SQL Server) installiert ist. Sie steht nicht im Standard-PHP-Lieferumfang zur Verfügung.

Siehe auch

sqlsrv_connect sqlsrv_prepare sqlsrv_execute sqlsrv_fetch_array sqlsrv_fetch_object sqlsrv_rows_affected sqlsrv_errors sqlsrv_free_stmt