Skip to content

Commit fe9388b

Browse files
garyericsongaryericson
committed
SQLML: Review of language extensions
1 parent 2848bcb commit fe9388b

2 files changed

Lines changed: 115 additions & 107 deletions

File tree

‎docs/machine-learning/install/custom-runtime-python.md‎

Lines changed: 66 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -17,37 +17,38 @@ This article describes how to install a custom runtime for running Python script
1717

1818
+ An installation of SQL Server with extensibility framework.
1919

20-
+ An installation of SQL Machine Learning Services for SQL Server 2019. The language extension can be used with [SQL Server Machine Learning Services](../sql-server-machine-learning-services.md) after completing some additional configuration steps.
20+
+ An installation of Machine Learning Services with SQL Server 2019. The language extension can be used with [SQL Server Machine Learning Services](../sql-server-machine-learning-services.md) after completing some additional configuration steps.
2121

2222
::: moniker range=">=sql-server-ver15||=sqlallproducts-allversions"
23+
2324
> [!NOTE]
24-
> This article describes how to install a custom runtime for Python on Windows. To install on Linux, see the [Install a Python custom runtime for SQL Server on Linux](custom-runtime-python.md?view=sql-server-linux-ver15&preserve-view=true)
25+
> This article describes how to install a custom runtime for Python on Windows. To install on Linux, see [Install a Python custom runtime for SQL Server on Linux](custom-runtime-python.md?view=sql-server-linux-ver15&preserve-view=true).
2526
2627
## Pre-install checklist
2728

28-
+ [SQL Server 2019 for Windows CU3 or later.](../../database-engine/install-windows/install-sql-server.md)
29+
Before installing a Python custom runtime, install the following:
30+
31+
+ [SQL Server 2019 for Windows CU3 or later](../../database-engine/install-windows/install-sql-server.md).
2932

3033
> [!NOTE]
3134
> Python custom runtime requires Cumulative Update (CU) 3 or later for SQL Server 2019.
3235
33-
+ [SQL Server Language Extensions on Windows with the extensibility framework.](../../language-extensions/install/install-sql-server-language-extensions-on-windows.md)
36+
+ [SQL Server Language Extensions on Windows with the extensibility framework](../../language-extensions/install/install-sql-server-language-extensions-on-windows.md).
3437

35-
+ [Python 3.7]( https://www.python.org/downloads/release/python-379/)
38+
+ [Python 3.7]( https://www.python.org/downloads/release/python-379/).
3639

3740
## Add SQL Server Language Extensions for Windows
3841

3942
> [!NOTE]
40-
> For Machine Learning Services using SQL Server 2019, the extensibility framework for language extensions is already installed and you can skip this step.
43+
> If you have Machine Learning Services installed on SQL Server 2019, the extensibility framework is already installed and you can skip this step.
4144
4245
Language Extensions use the extensibility framework for executing external code. Code execution is isolated from the core engine processes, but fully integrated with SQL Server query execution.
4346

44-
Complete the setup for SQL Server 2019.
45-
46-
1. Start the setup wizard for SQL Server 2019.
47+
1. Start the setup wizard for SQL Server 2019.
4748

4849
1. On the **Installation** tab, select **New SQL Server stand-alone installation or add features to an existing installation**.
4950

50-
![SQL Server 2019 CU3 or later installation](../install/media/2019setup-installation-page-mlsvcs.png)
51+
![SQL Server 2019 installation CU3 or later](../install/media/2019setup-installation-page-mlsvcs.png)
5152

5253
1. On the **Feature Selection** page, select these options:
5354

@@ -57,7 +58,7 @@ Complete the setup for SQL Server 2019.
5758

5859
- **Machine Learning Services and Language Extensions**
5960

60-
Select **Machine Learning Services and Language Extensions** There's no need to select Python.
61+
Select **Machine Learning Services and Language Extensions**. There's no need to select Python.
6162

6263
![SQL Server 2019 CU3 or later installation features](../install/media/sql-feature-selection.png)
6364

@@ -71,7 +72,7 @@ Complete the setup for SQL Server 2019.
7172

7273
## Install Python 3.7
7374

74-
[Install Python 3.7 and add it to the PATH.]( https://www.python.org/downloads/release/python-379/)
75+
Install [Python 3.7]( https://www.python.org/downloads/release/python-379/) and add it to the PATH.
7576

7677
![Add Python 3.7 to path.](../install/media/python-379.png) **update image - note**
7778

@@ -89,13 +90,10 @@ python.exe -m pip install pandas
8990

9091
Add or modify PYTHONHOME as a system environment variable.
9192

92-
+ In **Search** type **environment.** Select **Edit system environment variables.**
93-
+ In the section System Variables.
94-
Select **Advanced** tab.
95-
Select **Environment Variables.**
96-
97-
+ Select **New** to create PYTHONHOME.
98-
To modify select **Edit** to change PYTHONHOME. Modify PYTHONHOME to point to the Python 3.7 installation location.
93+
+ In the Windows search box, type "environment" and select **Edit the system environment variables**.
94+
+ In the **Advanced** tab, select **Environment Variables**.
95+
+ Under **System variables**, select **New** to create PYTHONHOME to point to the Python 3.7 installation location.
96+
If PYTHONHOME already exists, select **Edit** to point it to the Python 3.7 installation location.
9997
+ Select **OK** to close remaining windows.
10098

10199
![Create PYTHONHOME system variable.](../install/media/sys-pythonhome.png)
@@ -107,21 +105,21 @@ Run the following **icacls** commands from a new *elevated* command prompt to gr
107105

108106
Append the instance name to MSSQLLAUNCHPAD (`MSSQLLAUNCHPAD$INSTANCENAME`). In this example, INSTANCENAME is the default instance `MSSQLSERVER`.
109107

110-
1. Give permissions to **SQL Server Launchpad Service user name**
108+
1. Give permissions to **SQL Server Launchpad Service user name**.
111109

112110
```cmd
113111
icacls "%PYTHONHOME%" /grant "NT Service\MSSQLLAUNCHPAD$MSSQLSERVER":(OI)(CI)RX /T
114112
115-
2. Give permissions to **SID S-1-15-2-1**
113+
2. Give permissions to **SID S-1-15-2-1**.
116114
```cmd
117115
icacls "%PYTHONHOME%" /grant *S-1-15-2-1:(OI)(CI)RX /T
118116
119117
>[!NOTE]
120-
>The above command grants permissions to the computer **SID S-1-15-2-1**, which is equivalent to ALL APPLICATION PACKAGES on an English version of Windows. Alternatively, you can use `icacls "%R_HOME%" /grant "ALL APPLICATION PACKAGES":(OI)(CI)RX /T` on an English version of Windows.
118+
>The preceding command grants permissions to the computer **SID S-1-15-2-1**, which is equivalent to ALL APPLICATION PACKAGES on an English version of Windows. Alternatively, you can use `icacls "%R_HOME%" /grant "ALL APPLICATION PACKAGES":(OI)(CI)RX /T` on an English version of Windows.
121119
122120
## Restart SQL Server Launchpad service
123121
124-
Find the name of the SQL Server Launchpad Service. It is of the form MSSQLLAUNCHPAD$INSTANCENAME where INSTANCENAME is the instance name of your SQL Server. From an *elevated* command prompt, run the following commands (in this example, INSTANCENAME is the default instance `MSSQLSERVER`).
122+
From an *elevated* command prompt, run the following commands. Replace "MSSQLSERVER" with the name of your SQL Server instance.
125123
126124
```CMD
127125
net stop MSSQLLAUNCHPAD$MSSQLSERVER
@@ -132,15 +130,15 @@ Alternatively, right-click the SQL Server Launchpad service in the **Services**
132130

133131
## Download Python language extension
134132

135-
Download the zip file containing the Python language extension (python-lang-extension.zip) from [here.](**GitHub link goes here**)
133+
Download the zip file containing the Python language extension (python-lang-extension.zip) from [here](**GitHub link goes here**).
136134

137135
## Register external language
138136

139-
For each database you want to use this Python language extension, you need to register it with [CREATE EXTERNAL LANGUAGE](../../t-sql/statements/create-external-language-transact-sql.md).
140-
Use [Azure Data Studio](https://docs.microsoft.com/sql/azure-data-studio/download-azure-data-studio) to connect to SQL Server and run the following T-SQL. Modify the path in this statement to reflect the location of the downloaded language extension zip file (python-lang-extension.zip) from above.
137+
Register this Python language extension with [CREATE EXTERNAL LANGUAGE](../../t-sql/statements/create-external-language-transact-sql.md) for each database you want to use it in.
138+
Use [Azure Data Studio](https://docs.microsoft.com/sql/azure-data-studio/download-azure-data-studio) to connect to SQL Server and run the following T-SQL command. Modify the path in this statement to reflect the location of the downloaded language extension zip file (python-lang-extension.zip).
141139

142140
> [!NOTE]
143-
>Python is a reserved word. Use a different name for the external language, e.g. myPython.
141+
> Python is a reserved word. Use a different name for the external language, for example, "myPython".
144142
145143
```sql
146144
CREATE EXTERNAL LANGUAGE [myPython]
@@ -151,30 +149,35 @@ GO
151149
::: moniker-end
152150

153151
::: moniker range=">=sql-server-linux-ver15||=sqlallproducts-allversions"
152+
154153
You can install SQL Server on Red Hat Enterprise Linux (RHEL), SUSE Linux Enterprise Server (SLES), and Ubuntu. For more information, see [the Supported platforms section in the Installation guidance for SQL Server on Linux](../../linux/sql-server-linux-setup.md).
155154

156155
> [!NOTE]
157156
> This article describes how to install a custom runtime for Python on Linux. To install on Windows, see the [Install a Python custom runtime for SQL Server on Windows](custom-runtime-python.md?view=sql-server-ver15&preserve-view=true)
158157
159158
## Pre-install checklist
160159

161-
+ [SQL Server 2019 for Linux (Cumulative Update 3 onwards).](../../linux/sql-server-linux-setup.md)
160+
Before installing a Python custom runtime, install the following:
161+
162+
+ [SQL Server 2019 for Linux (Cumulative Update 3 or later)](../../linux/sql-server-linux-setup.md).
162163
When you install SQL Server on Linux, you must configure a Microsoft repository. For more information, see [configuring repositories](../../linux/sql-server-linux-change-repo.md)
163164

164165
> [!NOTE]
165166
> Python custom runtime requires Cumulative Update (CU) 3 or later for SQL Server 2019.
166167
167-
+ [SQL Server Language Extensions on Linux with the extensibility framework.](../../linux/sql-server-linux-setup-language-extensions.md)
168+
+ [SQL Server Language Extensions on Linux with the extensibility framework](../../linux/sql-server-linux-setup-language-extensions.md).
168169

169-
+ [Python 3.7](https://www.python.org/downloads/release/python-379/)
170+
+ [Python 3.7](https://www.python.org/downloads/release/python-379/).
170171

171172
## Add SQL Server Language Extensions for Linux
172173

173174
> [!NOTE]
174-
> For Machine Learning Services using SQL Server 2019, the **mssql-server-extensibility** package for language extensions is already installed and you can skip this step.
175+
> If you have Machine Learning Services installed on SQL Server 2019, the **mssql-server-extensibility** package for language extensions is already installed and you can skip this step.
175176
176177
Language Extensions use the extensibility framework for executing external code. Code execution is isolated from the core engine processes, but fully integrated with SQL Server query execution.
177178

179+
Use the following commands to install Language Extensions, depending on your version of Linux.
180+
178181
### Ubuntu
179182
> [!Tip]
180183
> If possible, `update` to refresh packages on the system prior to installation. Ubuntu might not have the https apt transport option. To install it, use `apt-get install apt-transport-https`.
@@ -200,7 +203,7 @@ sudo zypper install mssql-server-extensibility
200203

201204
Install Python 3.7, the libpython3.7 library, and the pandas package.
202205

203-
Example instructions for Ubuntu:
206+
The following are example commands for Ubuntu:
204207

205208
```bash
206209
# Install python3.7 and the corresponding library:
@@ -217,59 +220,59 @@ sudo python3.7 -m pip install pandas -t /usr/lib/python3.7/dist-packages
217220
> [!NOTE]
218221
> If you have installed Python in the default location of **/usr/lib/python3.7**, you can skip to [the next section](#download-python-linux).
219222
220-
If you built your own version of Python 3.7, follow the following steps so that SQL Server can find and load your custom installation.
223+
If you built your own version of Python 3.7, use the following commands so that SQL Server can find and load your custom installation.
221224

222-
#### Update the environment variables
225+
### Update the environment variables
223226

224227
1. Add the PYTHONHOME environment variable to the mssql-launchpadd service config.
225228

226229
+ Edit **mssql-launchpadd** service.
227230

228-
```bash
229-
sudo systemctl edit mssql-launchpadd
230-
```
231+
```bash
232+
sudo systemctl edit mssql-launchpadd
233+
```
231234

232235
+ Insert the following text in the **/etc/systemd/system/mssql-launchpadd.service.d/override.conf** file that opens. Set value of PYTHONHOME to the custom Python installation path.
233236

234-
```vi
235-
[Service]
236-
Environment="PYTHONHOME=/path/to/installation/of/python3.7"
237-
```
237+
```vi
238+
[Service]
239+
Environment="PYTHONHOME=/path/to/installation/of/python3.7"
240+
```
238241

239242
+ Save and close.
240243

241244
2. Make sure **libpython3.7m.so.1.0** can be loaded.
242245

243246
+ Create a custom-python.conf file in **/etc/ld.so.conf.d**.
244247

245-
```bash
246-
sudo vi /etc/ld.so.conf.d/custom-python.conf
247-
```
248+
```bash
249+
sudo vi /etc/ld.so.conf.d/custom-python.conf
250+
```
248251

249-
+ In the file that opens, add path to **libpython3.7m.so.1.0** from the custom Python installation.
252+
+ In the file that opens, add the path to **libpython3.7m.so.1.0** from the custom Python installation.
250253

251-
```vi
252-
/path/to/installation/of/python3.7/lib
253-
```
254+
```vi
255+
/path/to/installation/of/python3.7/lib
256+
```
254257

255258
+ Save and close the new file.
256259

257260
+ Run `ldconfig` and verify **libpython3.7m.so.1.0** can be loaded by running the following commands and checking that all the dependent libraries can be found.
258261

259-
```bash
260-
sudo ldconfig
261-
ldd /path/to/installation/of/python3.7/lib/libpython3.7m.so.1.0
262-
```
262+
```bash
263+
sudo ldconfig
264+
ldd /path/to/installation/of/python3.7/lib/libpython3.7m.so.1.0
265+
```
263266

264-
#### Grant access to the custom Python folder
267+
### Grant access to the custom Python folder
265268

266269
Set the `datadirectories` option in the extensibility section of /var/opt/mssql/mssql.conf file to the custom python installation.
267270

268271
```bash
269272
sudo /opt/mssql/bin/mssql-conf set extensibility.datadirectories /path/to/installation/of/python3.7
270273
```
271274

272-
#### Restart the mssql-launchpadd service
275+
### Restart the mssql-launchpadd service
273276

274277
```bash
275278
sudo systemctl restart mssql-launchpadd
@@ -279,17 +282,16 @@ sudo systemctl restart mssql-launchpadd
279282

280283
## <a name="download-python-linux"></a> Download Python language extension
281284

282-
Download the zip file containing the Python language extension (**python-lang-extension.zip**) from [here.](**GitHub link goes here**)
285+
Download the zip file containing the Python language extension (**python-lang-extension.zip**) from [here](**GitHub link goes here**).
283286

284287
## Register external language
285288

286-
For each database you want to use this python language extension, you need to register it with [CREATE EXTERNAL LANGUAGE](../../t-sql/statements/create-external-language-transact-sql.md).
287-
Use [Azure Data Studio](https://docs.microsoft.com/sql/azure-data-studio/download-azure-data-studio) to connect to SQL Server and run the following T-SQL.
288-
289-
Modify the path in this statement to reflect the location of the downloaded language extension zip file (python-lang-extension.zip) from above.
289+
Register this Python language extension with [CREATE EXTERNAL LANGUAGE](../../t-sql/statements/create-external-language-transact-sql.md) for each database you want to use it in.
290+
Use [Azure Data Studio](https://docs.microsoft.com/sql/azure-data-studio/download-azure-data-studio) to connect to SQL Server and run the following T-SQL command.
291+
Modify the path in this statement to reflect the location of the downloaded language extension zip file (python-lang-extension.zip).
290292

291293
> [!NOTE]
292-
>Python is a reserved word. Use a different name for the external language e.g. myPython.
294+
>Python is a reserved word. Use a different name for the external language, for example, "myPython".
293295

294296
```sql
295297
CREATE EXTERNAL LANGUAGE myPython
@@ -302,17 +304,18 @@ GO
302304

303305
## Enable external script execution in SQL Server
304306

305-
An external script in Python can be executed via the stored procedure [sp_execute_external script](../../relational-databases/system-stored-procedures/sp-execute-external-script-transact-sql.md) run against SQL Server. Execute the following script using [Azure Data Studio.](https://docs.microsoft.com/sql/azure-data-studio/download-azure-data-studio)
307+
An external script in Python can be executed via the stored procedure [sp_execute_external script](../../relational-databases/system-stored-procedures/sp-execute-external-script-transact-sql.md) run against SQL Server. 
308+
309+
To enable external scripts, execute the following SQL commands using [Azure Data Studio](https://docs.microsoft.com/sql/azure-data-studio/download-azure-data-studio), connected to SQL Server.
306310

307311
```sql
308312
sp_configure 'external scripts enabled', 1;
309313
RECONFIGURE WITH OVERRIDE;
310314
```
311315

312316
## Verify language extension installation
313-
Use SQL Azure Data Studio to connect to SQL Server.
314317

315-
This script tests the functionality of the installed language extension.
318+
This SQL script tests the functionality of the installed language extension.
316319

317320
```sql
318321
EXEC sp_execute_external_script

0 commit comments

Comments
 (0)