Agrupamento de Conexões (Microsoft Drivers para PHP para SQL Server)

Descarregar o driver PHP

Os seguintes pontos são importantes sobre o agrupamento de ligações nos Microsoft Drivers for PHP for SQL Server:

  • Os Drivers da Microsoft para PHP para SQL Server utilizam agregação de conexões ODBC.

  • Por defeito, o pooling de ligações está ativado no Windows. No Linux e macOS, as ligações são agrupadas apenas se o pool de ligações estiver ativado para ODBC (ver Ativar ou desativar o pool de ligações). Quando o pooling de ligações está ativado e se liga a um servidor, o driver tenta usar uma ligação em pool antes de criar uma nova. Se não for encontrada uma ligação equivalente no pool, uma nova ligação é criada e adicionada ao pool. O driver determina se as ligações são equivalentes com base numa comparação de cadeias de ligação.

  • Quando uma ligação do pool é utilizada, o estado da ligação é reiniciado (apenas no Windows).

  • Fechar a ligação devolve a ligação ao pool.

Para mais informações sobre pool de conexões, consulte Driver Manager Connection Pooling.

Ativar/Desativar o agrupamento de ligações

Windows

Pode forçar o driver a criar uma nova ligação (em vez de procurar uma ligação equivalente no pool de ligações) definindo o valor do atributo ConnectionPooling na string de ligação para false (ou 0).

Se o atributo ConnectionPooling for omitido da cadeia de ligação ou se estiver definido como true (ou 1), o driver só cria uma nova ligação se não existir uma ligação equivalente no pool de ligações.

Observação

O Multiple Active Result Sets (MARS) está ativado por defeito. Quando tanto o MARS como o pooling estão em uso, para que o MARS funcione corretamente, o driver demora mais tempo a reiniciar a ligação na primeira consulta, ignorando assim qualquer tempo de espera especificado. No entanto, a definição de timeout da consulta entra em vigor em consultas subsequentes.

Se necessário, veja como desativar Múltiplos Conjuntos de Resultados Ativos (MARS). Para informações sobre outros atributos de ligação, consulte Opções de Ligação.

Linux e macOS

O atributo ConnectionPooling não pode ser usado para ativar ou desativar o pool de ligações.

O pooling de ligações pode ser ativado ou desativado editando o ficheiro de configuração odbcinst.ini. O controlador deve ser reiniciado para que as alterações entrem em vigor.

Definir Pooling para Yes e um valor positivo CPTimeout no ficheiro odbcinst.ini permite o pooling de ligações.

[ODBC]
Pooling=Yes

[ODBC Driver 17 for SQL Server]
CPTimeout=<int value>

No mínimo, o ficheiro odbcinst.ini deve assemelhar-se ao seguinte exemplo:

[ODBC]
Pooling=Yes

[ODBC Driver 17 for SQL Server]
Description=Microsoft ODBC Driver 17 for SQL Server
Driver=/opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.5.so.2.1
UsageCount=1
CPTimeout=120

Definir Pooling para No no ficheiro odbcinst.ini obriga o driver a criar uma nova ligação.

[ODBC]
Pooling=No

Observações

  • No Linux ou macOS, o agrupamento de ligações não é recomendado com o unixODBC < 2.3.7. Todas as ligações serão agrupadas se o pooling estiver ativado no ficheiro odbcinst.ini, o que significa que a opção de ligação ConnectionPooling não tem efeito. Para desativar o pooling, defina Pooling=No no ficheiro odbcinst.ini e recarregue os drivers.

    • unixODBC <= 2.3.4 (Linux e macOS) pode não devolver informação de diagnóstico adequada, como mensagens de erro, avisos e mensagens informativas.
    • Por esta razão, os drivers SQLSRV e PDO_SQLSRV podem não conseguir obter corretamente dados longos (como xml, binário) como strings. Os dados longos podem ser obtidos em formato de fluxo como uma solução alternativa. Veja o seguinte exemplo para SQLSRV.

  • Ao usar AccessToken com pooling de conexões, o driver adiciona um hash do conteúdo do token à palavra-chave de ligação APP para garantir que conexões com diferentes tokens de acesso não sejam agrupadas. Isto previne contaminação cruzada de identidades, onde uma ligação agrupada autenticada como uma identidade pode ser reutilizada para uma identidade diferente. Os dados dos tokens são armazenados em cache com expiração baseada em TTL para garantir a estabilidade dos ponteiros para o driver ODBC. Este comportamento foi introduzido na versão 5.13.1.

<?php
$connectionInfo = array("Database"=>"test", "UID"=>"username", "PWD"=>"password");

$conn1 = sqlsrv_connect("servername", $connectionInfo);

$longSample = str_repeat("a", 8500);
$xml1 = 
'<ParentXMLTag>
  <ChildTag01>'.$longSample.'</ChildTag01>
</ParentXMLTag>';

// Create table and insert xml string into it
sqlsrv_query($conn1, "CREATE TABLE xml_table (field xml)");
sqlsrv_query($conn1, "INSERT into xml_table values ('$xml1')");

// retrieve the inserted xml
$column1 = getColumn($conn1);

// return the connection to the pool
sqlsrv_close($conn1);

// This connection is from the pool
$conn2 = sqlsrv_connect("servername", $connectionInfo);
$column2 = getColumn($conn2);

sqlsrv_query($conn2, "DROP TABLE xml_table");
sqlsrv_close($conn2);

function getColumn($conn)
{
    $tsql = "SELECT * from xml_table";
    $stmt = sqlsrv_query($conn, $tsql);
    sqlsrv_fetch($stmt);
    // This might fail in Linux and macOS
    // $column = sqlsrv_get_field($stmt, 0, SQLSRV_PHPTYPE_STRING(SQLSRV_ENC_CHAR));
    // The workaround is to fetch it as a stream
    $column = sqlsrv_get_field($stmt, 0, SQLSRV_PHPTYPE_STREAM(SQLSRV_ENC_CHAR));
    sqlsrv_free_stmt($stmt);
    return ($column);
}
?>

Conteúdo relacionado

  • Last updated on