From 0d8c6920b798a545c735984c638acafe248e81c3 Mon Sep 17 00:00:00 2001 From: Henk Poley Date: Wed, 6 Mar 2024 14:15:39 +0100 Subject: [PATCH 1/3] Better document SQL Server settings in config/database.php --- database.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/database.md b/database.md index 0a5664abfca..3667f39a8fd 100644 --- a/database.md +++ b/database.md @@ -53,7 +53,58 @@ DB_FOREIGN_KEYS=true #### Microsoft SQL Server Configuration -To use a Microsoft SQL Server database, you should ensure that you have the `sqlsrv` and `pdo_sqlsrv` PHP extensions installed as well as any dependencies they may require such as the Microsoft SQL ODBC driver. +To use a Microsoft SQL Server database, you should ensure that you have the [`sqlsrv` and `pdo_sqlsrv` PHP extensions installed](https://learn.microsoft.com/en-us/sql/connect/php/installation-tutorial-linux-mac) as well as any dependencies they may require such as the Microsoft SQL ODBC driver. + +For further configuration options such as `MultiSubnetFailover` look into `\Illuminate\Database\Connectors\SqlServerConnector->getSqlSrvDsn()`. + +Which can be configured in `config/database.php`: + +```php + 'sqlsrv' => [ + 'driver' => 'sqlsrv', + // .. + + // General connection options documentation: + // https://learn.microsoft.com/en-us/sql/connect/php/connection-options?view=sql-server-ver16#table-of-connection-options + // 'appname' => 'Your application name', // APP + // 'transaction_isolation' => true, // TransactionIsolation + // 'login_timeout' => '', // LoginTimeout + + // https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/odbc-driver-on-linux-support-for-high-availability-disaster-recovery?view=sql-server-ver16#targets-of-readonly + // 'readonly' => true, // ApplicationIntent=ReadOnly + + // https://learn.microsoft.com/en-us/sql/connect/php/connection-pooling-microsoft-drivers-for-php-for-sql-server?view=sql-server-ver16 + // 'pooling' => false, // ConnectionPooling=0 + + // https://learn.microsoft.com/en-us/sql/connect/php/how-to-connect-using-sql-server-authentication?view=sql-server-ver16 + // 'encrypt' => true, // Encrypt + // 'trust_server_certificate' => true, // TrustServerCertificate + + // https://learn.microsoft.com/en-us/sql/connect/php/how-to-disable-multiple-active-resultsets-mars?view=sql-server-ver16 + // 'multiple_active_result_sets' => false, // MultipleActiveResultSets + + // https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/odbc-driver-on-linux-support-for-high-availability-disaster-recovery?view=sql-server-ver16#connect-with-multisubnetfailover + // MultiSubnetFailover + // 'multi_subnet_failover' => true, + + // https://learn.microsoft.com/en-us/sql/connect/php/using-always-encrypted-php-drivers?view=sql-server-ver16#enabling-always-encrypted-in-a-php-application + // 'column_encryption' => true, // ColumnEncryption + + // https://learn.microsoft.com/en-us/sql/connect/odbc/using-always-encrypted-with-the-odbc-driver?view=sql-server-ver16 + // 'key_store_authentication' => '', // KeyStoreAuthentication: 'KeyVaultClientSecret', 'KeyVaultPassword' / 'KeyVaultManagedIdentity' + // 'key_store_principal_id' => '', // KeyStorePrincipalId: / / + // 'key_store_secret' => '', // KeyStoreSecret: / + + // https://learn.microsoft.com/en-us/sql/connect/php/azure-active-directory?view=sql-server-ver16 + // 'authentication' => '', // Authentication: SqlPassword, ActiveDirectoryPassword, ActiveDirectoryMsi, ActiveDirectoryServicePrincipal + ], +``` + +Unsupported configuration options such as `TransparentNetworkIPResolution` can be set using a complete server string with all your options: + +``` +DATABASE_URL=sqlsrv:Server=sqlsrv.example.com;Database=laravel;MultiSubnetFailover=True;TransparentNetworkIPResolution=True +``` #### Configuration Using URLs From 43c4dacfd3462c408bdac9dcdf4c11dc3c2fb2b2 Mon Sep 17 00:00:00 2001 From: Henk Poley Date: Fri, 8 Mar 2024 11:48:00 +0100 Subject: [PATCH 2/3] Update database.md Removed all the (deprecated?) array documentation. Merely reference Microsoft documentation. --- database.md | 53 ++++++----------------------------------------------- 1 file changed, 6 insertions(+), 47 deletions(-) diff --git a/database.md b/database.md index 3667f39a8fd..a269d6f14ef 100644 --- a/database.md +++ b/database.md @@ -53,58 +53,17 @@ DB_FOREIGN_KEYS=true #### Microsoft SQL Server Configuration -To use a Microsoft SQL Server database, you should ensure that you have the [`sqlsrv` and `pdo_sqlsrv` PHP extensions installed](https://learn.microsoft.com/en-us/sql/connect/php/installation-tutorial-linux-mac) as well as any dependencies they may require such as the Microsoft SQL ODBC driver. +Ensure you have the [`sqlsrv` and `pdo_sqlsrv` PHP extensions installed](https://learn.microsoft.com/en-us/sql/connect/php/installation-tutorial-linux-mac), along with the necessary Microsoft SQL ODBC driver. Use the `DATABASE_URL` in the `.env` file for easy configuration of your Microsoft SQL Server database connection in a Laravel environment. -For further configuration options such as `MultiSubnetFailover` look into `\Illuminate\Database\Connectors\SqlServerConnector->getSqlSrvDsn()`. +Example `DATABASE_URL`: -Which can be configured in `config/database.php`: - -```php - 'sqlsrv' => [ - 'driver' => 'sqlsrv', - // .. - - // General connection options documentation: - // https://learn.microsoft.com/en-us/sql/connect/php/connection-options?view=sql-server-ver16#table-of-connection-options - // 'appname' => 'Your application name', // APP - // 'transaction_isolation' => true, // TransactionIsolation - // 'login_timeout' => '', // LoginTimeout - - // https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/odbc-driver-on-linux-support-for-high-availability-disaster-recovery?view=sql-server-ver16#targets-of-readonly - // 'readonly' => true, // ApplicationIntent=ReadOnly - - // https://learn.microsoft.com/en-us/sql/connect/php/connection-pooling-microsoft-drivers-for-php-for-sql-server?view=sql-server-ver16 - // 'pooling' => false, // ConnectionPooling=0 - - // https://learn.microsoft.com/en-us/sql/connect/php/how-to-connect-using-sql-server-authentication?view=sql-server-ver16 - // 'encrypt' => true, // Encrypt - // 'trust_server_certificate' => true, // TrustServerCertificate - - // https://learn.microsoft.com/en-us/sql/connect/php/how-to-disable-multiple-active-resultsets-mars?view=sql-server-ver16 - // 'multiple_active_result_sets' => false, // MultipleActiveResultSets - - // https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/odbc-driver-on-linux-support-for-high-availability-disaster-recovery?view=sql-server-ver16#connect-with-multisubnetfailover - // MultiSubnetFailover - // 'multi_subnet_failover' => true, - - // https://learn.microsoft.com/en-us/sql/connect/php/using-always-encrypted-php-drivers?view=sql-server-ver16#enabling-always-encrypted-in-a-php-application - // 'column_encryption' => true, // ColumnEncryption - - // https://learn.microsoft.com/en-us/sql/connect/odbc/using-always-encrypted-with-the-odbc-driver?view=sql-server-ver16 - // 'key_store_authentication' => '', // KeyStoreAuthentication: 'KeyVaultClientSecret', 'KeyVaultPassword' / 'KeyVaultManagedIdentity' - // 'key_store_principal_id' => '', // KeyStorePrincipalId: / / - // 'key_store_secret' => '', // KeyStoreSecret: / - - // https://learn.microsoft.com/en-us/sql/connect/php/azure-active-directory?view=sql-server-ver16 - // 'authentication' => '', // Authentication: SqlPassword, ActiveDirectoryPassword, ActiveDirectoryMsi, ActiveDirectoryServicePrincipal - ], +``` +DATABASE_URL="sqlsrv:Server=your_server_address;Database=your_database_name;Encrypt=true;TrustServerCertificate=false;LoginTimeout=30;App=your_app_name;MultipleActiveResultSets=false;MultiSubnetFailover=True" ``` -Unsupported configuration options such as `TransparentNetworkIPResolution` can be set using a complete server string with all your options: +This connection string format allows inclusion of various Microsoft SQL Server options such as encryption, trust server certificate, login timeout, application name, Multiple Active Result Sets (MARS), and MultiSubnetFailovere. -``` -DATABASE_URL=sqlsrv:Server=sqlsrv.example.com;Database=laravel;MultiSubnetFailover=True;TransparentNetworkIPResolution=True -``` +For a detailed list of available connection string options, refer to the [Microsoft SQL Server documentation on connection strings](https://learn.microsoft.com/en-us/sql/connect/php/connection-options?view=sql-server-ver16#table-of-connection-options). #### Configuration Using URLs From 9b7f7973833294142287bf2fc64967426d2decdd Mon Sep 17 00:00:00 2001 From: Henk Poley Date: Fri, 8 Mar 2024 19:30:50 +0100 Subject: [PATCH 3/3] Update database.md, hint about not putting Database= first --- database.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/database.md b/database.md index a269d6f14ef..ad775de7a59 100644 --- a/database.md +++ b/database.md @@ -61,6 +61,8 @@ Example `DATABASE_URL`: DATABASE_URL="sqlsrv:Server=your_server_address;Database=your_database_name;Encrypt=true;TrustServerCertificate=false;LoginTimeout=30;App=your_app_name;MultipleActiveResultSets=false;MultiSubnetFailover=True" ``` +(Due to a bug do not put Database= as your first item of the connection string.) + This connection string format allows inclusion of various Microsoft SQL Server options such as encryption, trust server certificate, login timeout, application name, Multiple Active Result Sets (MARS), and MultiSubnetFailovere. For a detailed list of available connection string options, refer to the [Microsoft SQL Server documentation on connection strings](https://learn.microsoft.com/en-us/sql/connect/php/connection-options?view=sql-server-ver16#table-of-connection-options).