Install SQL for ArcGIS Pro

SQL for ArcGIS® Pro is an add-in for Esri's ArcGIS® Pro, often called SQL or sql4arc for short in this documentation. 

 

SQL requires the latest version of ArcGIS® Pro.  Installation packages are automatically updated to track Esri releases of ArcGIS Pro.  The computer running SQL must have Internet connectivity from time to time, at least during initial activation and then every week or so.   

 

You must have an SQL for ArcGIS Pro serial number to activate an SQL for ArcGIS Pro license.  

Installation Overview

 

 

 

 

SQL for ArcGIS Pro builds are cumulative, including all new features and fixes issued in previous builds. You do not need to install any previous builds to get everything in the latest build.

 

SQL for ArcGIS Pro licenses are activated using a serial number that allows each license to run on a single computer system.  Subject to reasonable limitations, a license can be moved from one computer system to another, or re-installed on the same system if hardware or Windows upgrades require a re-installation.  See the SQL Activation web page to learn how activations automatically grow back after use, providing a never-ending crop of activations.  

Windows Installer

A Windows Installer package is an .msi or .exe file that uses Microsoft's Windows Installer facility to install, modify, and to uninstall programs.   SQL uses .exe files to enable easier installation of any prerequisite Microsoft facilities.  The SQL Windows Installer package will automatically install any required Microsoft prerequisites if those are not already installed on your system, and it will automatically register the add-in with your ArcGIS Pro installation.

 

Windows Installer packages include two versions of the add-in: a version for ArcGIS Pro 2.x and a version for ArcGIS Pro 3.x.  The Windows Installer  package will detect the installed version of ArcGIS Pro and will use the corresponding version of the SQL for ArcGIS Pro add-in.

 

See the SQL for ArcGIS Pro - Install and Activate video for installation using Windows Installer.  The first three minutes show the easy installation and activation process with the rest of the video showing a quick start to writing and executing SQL queries, including use of the query builder.

 

To install SQL (Windows Installer package):

 

  1. Visit the SQL for ArcGIS Pro Downloads page.
  2. Download the Sql4Arc Installer package.
  3. A Windows Installer package is an .exe file.  Double-click the downloaded .exe file to launch the installation.
  4. Click through any warnings from Microsoft.
  5. Installation dialogs are the usual, obvious dialogs. Press the Install button and otherwise click through the dialogs.
  6. When the installation finishes, press Close.
  7. SQL is now installed. When you launch ArcGIS Pro, an Add-In tab will appear in the ribbon.

 

After installation, save the installation .exe file. You may need it to later uninstall or to repair an installation.

 

Installing SQL usually does not require a system reboot.  However, if the installation dialog says a system reboot is required, let it reboot the system.   That can happen when the installation must update Microsoft's Visual C++ Runtime libraries, but the old versions are in use by system components.  A reboot allows those libraries to be updated.

 

To use SQL, launch ArcGIS Pro, open a project, then click the Add-In tab and press the Open SQL button in the sql4arc group.   To close the add-in, press the X  symbol in the upper right corner of the window, or choose File - Exit in the add-in's menu.

 

To uninstall SQL (Windows Installer package):

 

  1. Launch the Windows Programs and Features applet
  2. Click the entry for SQL for ArcGIS Pro (it will be identified by the build number that was installed) and press Uninstall in the applet's menu
  3. A Modify Setup dialog pops open, with choices to repair or to uninstall. Press the Uninstall button.
  4. When finished, the dialog will announce the uninstall is successfully completed. Press the Close button to close the dialog. SQL is now uninstalled.

 

Windows Installer Example:

 

In the SQL for ArcGIS Pro Downloads page, click the Sql4Arc Installer button to download the installation package.  The installation package is a Windows Installer .exe file.  The SHA256 code provided by the downloads page is a cryptographic code that you can use to confirm the downloaded package is indeed the package published by Manifold.

 

 

Move the downloaded .exe file to a convenient folder in your Windows system, where it will be safe for use should you need it again. The name of the installation package includes the build number.

 

Double-click the downloaded .exe file to begin installation.    Windows 10 may complain:

 

 

 

 

The app and publisher are unrecognized because Manifold respectfully declines the terms and conditions of Microsoft programs that may result in harvesting of user identities or which may compromise user privacy.  Manifold will cut no corners on user privacy, not even with a respected partner like Microsoft.  

 

Press the More info link.

 

 

 

 

Press the Run anyway button.

 

On other systems Windows may complain in a different way:

 

 

 

 

Ignore the warning and press Run.   If there is any doubt about the download, you can always check the SHA code published on the download page to make sure the installation file has not been altered since publication by Manifold.

 

That launches the SQL installation dialogs, a standard set of dialogs for .exe file installations similar to those used by Microsoft.  SQL uses .exe style installation dialogs to enable installation of Microsoft Visual C++ Redistributable files automatically if they have not yet been installed on the Windows machine in use.

 

Installation dialogs are obvious.   A typical installation will be similar to the following:

 

 

Click the Install button, and then click through subsequent dialogs in the usual way.

 

In addition to installing SQL, if necessary the package will install or update any Microsoft prerequisites, such as the C++ Redistributable package.   When finished, the dialog will announce the installation is successfully completed. Press the Close button to close the dialog.

 

SQL is now installed.  The ArcGIS Pro installation on the computer also has been updated with the SQL add-in.

Portable Installations

A portable installation is a .zip file that unzips into a fully-functional package that requires no installation. Many users prefer portable installations to using Windows Installer.  When using a portable installation, the ArcGIS Pro Add-In Manager dialog must be used to register the add-in with ArcGIS Pro.  Portable installations also require manual installation of Microsoft prerequisites if those have not already been installed.

 

To install Microsoft Prerequisites:

 

  1. Visit the Microsoft .NET Framework 4.0+ page, or download Microsoft's .NET 4.8 installer.
  2. Visit the Microsoft Visual C++ Redistributable page. Install both vc_redist.x64.exe (64-bit) and vc_redist.x86.exe (32-bit).

 

 

To install SQL (Portable installation):

 

  1. Visit the SQL for ArcGIS Pro Downloads page.
  2. Download the Sql4Arc Edge package.  A portable installation is a .zip file.
  3. Move the .zip file into a convenient location where you will unzip it, usually on an SSD for fast launches.
  4. Unzip the file to create a hierarchy of files and folders, including an addin folder that contains an Esri AddInX file called sql4arc.esriaddinx.

 

 

To register the add-in with ArcGIS Pro (Portable installation):

 

  1. Launch ArcGIS Pro with a project. In the Project tab, choose Add-In Manager.
  2. In the Add-In Manager, choose Options, and choose Load all Add-Ins without restrictions.
  3. Press the Add Folder button.
  4. In the Select Folder dialog, navigate to the location of the addin folder and click it, so it appears in the Name box.
  5. Exit, and then restart ArcGIS Pro. An Add-In tab will appear in the ribbon.

 

To use SQL, launch ArcGIS Pro, open a project, then click the Add-In tab and press the Open SQL button in the sql4arc group.   To close the add-in, press the X  symbol in the upper right corner of the window, or choose File - Exit in the add-in's menu.

Uninstalling a Portable Installation

Portable installations require no special uninstallation. If you no longer want the program on the system, simply delete the .zip file and any unzipped folders and files that are no longer desired.   That also will remove the add-in from ArcGIS Pro, because when Pro launches it will look for the add-in and not find it, and then simply move on without the add-in.

 

Another option to uninstall a portable installation is to leave the files for the installation in place, but to remove the reference to the addin folder using Add-In Manager in ArcGIS Pro.  That is a convenient option if you want to try out a new build of SQL while having the option of going back to a prior build.   You can have the files for both builds on your system and simply choose which one will be used by specifying the path to the desired addin folder using Add-In Manager.

 

Remove the add-in from ArcGIS Pro by deleting files and folders:

 

  1. Close any open sessions of the add-in and ArcGIS Pro.
  2. In Windows Explorer, delete the hierarchy of files and folders that were unzipped from the portable installation's .zip file.

 

When ArcGIS Pro is launched again, it will not be able to find the add-in and will not register it.  The path to the addin folder that was used will still be in the Options for ArcGIS Pro's Add-In Manager, but there will be no Esri AddInX file at that location.

 

Remove the add-in from ArcGIS Pro by using Add-In Manager:

 

  1. Close any open sessions of the add-in.
  2. In ArcGIS Pro, launch the Add-In Manager.
  3. In the Options tab, click on the addin folder in the options list to choose it.
  4. Press the Remove Folder button. That will remove any reference to the addin folder.
  5. Close and reopen ArcGIS Pro.

 

Removing the add-in using the above procedure will not delete any of the add-in's files and folders.  It will simply delete the reference to them in Add-In Manager.  That makes it possible to register the add-in with ArcGIS Pro again using the same files if you change your mind.  If desired, you can have multiple versions of the add-in, such as a newly-published build as well as an older build, and choose which will be used by simply specifying the desired addin folder in Add-In Manager.   

 

There is a third option that is mentioned in Esri documentation:  Launch ArcGIS Pro and then launch the Add-In Manager. In the Add-Ins tab, click the sql4arc add-in to choose it. In the lower right corner of the information screen that pops open, click Delete this Add-in.  That deletes the Esri AddInX file called sql4arc.esriaddinx in the add-in's addin folder.  When ArcGIS Pro is restarted it will be unable to find the Esri AddInX file and will not register the add-in.  

 

That works OK for very simple add-ins that consist of only a single AddinX file, but for add-ins consisting of multiple files and folders it is a messy hybrid of the two methods Manifold recommends.   Although it deletes the Esri AddInX file from the addin folder, it leaves in place the addin folder and all other files and folders that were used for the add-in.  Those should be deleted manually in Windows Explorer, to avoid leaving a collection of files and folders that later on might be misunderstood to be a functional add-in installation.

Portable Installation Example:

 

In the SQL for ArcGIS Pro Downloads page, click the Sql4Arc Edge button to download the Cutting Edge portable installation package.  The portable installation package is a .zip file.  The SHA256 code provided by the downloads page is a cryptographic code that you can use to confirm the downloaded package is indeed the package published by Manifold.

 

 

Move the downloaded .zip file to a convenient folder in your Windows system where it will be unzipped.  For faster launches, choose a folder located on a fast storage device, such as an SSD. In the illustration above we have moved the .zip file into a folder on our C: drive that is called add-ins. The name of the installation package includes the build number.

 

Unzip the downloaded .zip file.

 

 

The result is a new folder that contains the add-ins files and folders, named using the same build number as the downloaded .zip file.

 

 

If we navigate into the unzipped folder hierarchy we can see the main sub folders: addin (where the Esri AddInX file is located), bin and bin64 folders (containing 32-bit and 64-bit versions of the add-in respectively), and a extras folder (where custom configuration files can be placed).   The addin folder will be used when registering the add-in with ArcGIS Pro.

 

The default.ui.txt file is a canonical localization file for English language that can be used to localize SQL to other languages.  The installation.txt file gives installation instructions and the license.txt file is the End User License Agreement in text form.

Registering a Portable Installation with ArcGIS Pro

Windows Installer packages automatically register the add-in with ArcGIS Pro, but portable installations do not, so we must manually register the add-in using the ArGIS Pro Add-In Manager.   

 

Registering an add-in with ArcGIS Pro is just a simple matter of telling Pro where to look for the add-in when it starts up.   That is easy to do using Add-In Manager.

 

 

Launch ArcGIS Pro and open a project.   Note that there is no Add-In tab in the ribbon to the right of the Share tab, since we have yet to register any add-ins.  

 

Click the Project tab in the ribbon.

 

 

Choose Add-In Manager.

 

 

In the Add-In Manager, click Options and make sure the Load all Add-Ins without restrictions option is selected.  

 

Press the Add Folder button.  

 

 

In the Select Folder dialog, navigate to the location of the addin folder and choose the folder, arcgis2 or arcgis3, for the version of ArcGIS Pro you are using, so it appears in the Name box.

 

SQL for ArcGIS Pro portable installation packages include two versions of the add-in: a version for ArcGIS Pro 2.x in the arcgis2 folder and a version for ArcGIS Pro 3.x in the arcgis3 folder.  Choose the folder for the version of ArcGIS Pro being used.

 

Press OK.

 

 

The Add-In Manager is now loaded with the path to the addin folder where the Esri AddInX file for the add-in is located.  

 

Exit ArcGIS Pro, and then restart ArcGIS Pro.    From now on, when ArcGIS Pro launches it will check in the folder we have added, it will find the SQL for ArcGIS Pro add-in file there and will incorporate the add-in.

 

Activation

 To launch SQL for ArcGIS Pro we must have a project open in ArcGIS Pro that has a geodatabase layer in it.  Before launching SQL for ArcGIS Pro, add any geodatabase layer to your ArcGIS Pro project if there is not already a geodatabase layer in the project.  

 

The first time the SQL for ArcGIS Pro add-in is launched it will raise an activation dialog.  Enter your serial number and press the Accept button to activate the license.  Your computer must be connected to Internet to activate.   For details, see the Activation Guide page and the SQL Activation Reference topic in this manual.  Information on managing activations is in the SQL Activation topic.

 

Using the Add-In

Launch ArcGIS Pro and open a project.   

 

 To launch SQL for ArcGIS Pro we must have a project open in ArcGIS Pro that has a geodatabase layer in it.  Before launching SQL for ArcGIS Pro, add any geodatabase layer to your ArcGIS Pro project if there is not already a geodatabase layer in the project.  

 

In the illustrations below we open the ubiquitous Venice Acqua Alta project used in many ArcGIS Pro tutorials.

 

 

Note that there is now an Add-In tab in the ribbon to the right of the Share tab, since we have registered the SQL for ArcGIS Pro add-in.

 

Click the Add-In tab.

 

 

There is only one group in the Add-In tab, the sql4arc group.   Click  Open SQL 64-bit to launch the add-in.

 

 

The SQL for ArcGIS Pro add-in desktop pops open, ready for action with an opened Command window.    A starter query using one of the geodatabase layers in the ArcGIS Pro project populates the query text pane, to show how to write queries that refer to tables within file geodatabase data sources.

 

See the Getting Started with SQL  topic to continue learning about using SQL.

Installing Support for Mobile Geodatabases

Esri mobile geodatabases were introduced in ArcGIS Pro 2.7, with desktop GIS support only in ArcGIS Pro 2.7, 2.8 and subsequent.  This documentation refers to mobile geodatabases as mobile GDB for short.   Mobile geodatabases are basically SQLite files with a .geodatabase extension.   They require installation of an Esri-supplied .dll file called stgeometry_sqlite.dll. as well as an optional SQLITE3.DLL file. 

 

To use mobile geodatabases, we must install the optional stgeometry_sqlite.dll file.  This file is an Esri-provided DLL that extends SQLite with Esri's ST_GEOMETRY type.   We must also install and use an external SQLITE3.DLL file.

 

The stgeometry_sqlite.dll file comes in two versions, a 64-bit version and a 32-bit version.  The easiest way to install this file is to visit the Product Downloads page for SQL for ArcGIS Pro, and to download and install the optional package with DLLs for Postgres, MySQL, and Esri Mobile Geodatabases.  Get the open_source_db_64.zip download for 64-bit launches or the open_source_db_32.zip download for 32-bit launches.  Unzip the zip file that is downloaded, and place the resulting opt folder in the extras folder for SQL for ArcGIS Pro.

 

We must also install an optional, external SQLITE3.DLL file that may be obtained from the official sources for SQLite and SpatialLite:

 

 

Place the SQLITE3.DLL file in the extras folder for SQL for ArcGIS Pro.

 

SQL for ArcGIS Pro includes built-in support for SQLite, to connect to GPKG and to SQLite databases, but that uses different .dlls than Esri's mobile geodatabase technology.  When Esri's stgeometry_sqlite.dll extension and the optional SQLITE3.DLL files are copied into the extras folder,  SQL for ArcGIS Pro will automatically load Esri's stgeometry_sqlite.dll file to connect to mobile geodatabases.

Installing Support for PostgreSQL and MySQL Databases

Connecting to PostgreSQL and MySQL databases requires installation of optional DLL files.  The easiest way to do that is to visit the Product Downloads page for SQL for ArcGIS Pro, and to download and install the optional package with DLLs for Postgres, MySQL, and Esri Mobile Geodatabases.  Get the open_source_db_64.zip download.  Unzip the zip file that is downloaded, and place the resulting opt folder in the extras folder for SQL for ArcGIS Pro.

 

Notes

Serial Numbers - The email sent to you by the Manifold Online Store provides your SQL for ArcGIS Pro serial number.   If you have placed an order and have not received the serial number email, please check the spam folder in your email system in case it was set aside.

 

Error message when launching SQL?  - That usually means your Windows system is missing a Microsoft prerequisite mentioned above, either the C++ Redistributable package or the Microsoft .NET Framework or both. Exit ArcGIS Pro, and then take a moment to install those.

 

Frequent Updates: - Portable installations for SQL are updated frequently with new builds every two weeks or so. After downloading the latest build, if we always delete the old build and then move the new hierarchy of unzipped folders into the same location, with the same path to the addin folder, we will not have to use the ArcGIS Pro Add-In Manager to remove the old add-in and add the new add-in.

 

For example, in this topic we copied the unzipped folder sql4arc-9.0.177.2 and all the files and folders it contained into a C:\add-ins folder so that the path to the addin subfolder was C:\add-ins\sql4arc-9.0.177.2\addin when we registered the add-in in Add-In Manager.   We could have just copied all of the files and subfolders from within the unzipped  sql4arc-9.0.177.2 folder into our C:\add-ins folder, so that the path to the addin subfolder would have been C:\add-ins\addin.    That would avoid having the path include a name, sql4arc-9.0.177.2, that will change with each build.

 

If we do that, then with each new build we simply copy the files and subfolders from within the main unzipped folder into our working destination, and the path to the addin folder is always the same: C:\add-ins\addin.  Every time Pro launches it will find the addin folder and will use the AddInX file it finds there.     Make sure to copy all of the files and folders from each new build when using portable installations.  Do not just copy the AddInX file into the working destination.   The AddInX file just gets the ball rolling with an add-in.  Based on the location of the AddInX file, ArcGIS Pro knows what relative paths to use to find all the other various parts of the add-in, like the various .exe and .dll files that are used, so make sure to copy the entire hierarchy into the working destination.

 

Lost and Found - The SQL for ArcGIS Pro installation uses a variety of .exe and .dll files.   If the key manifold.exe file is moved after the add-in is installed, the add-in might not be able to find it.  If the manifold.exe file cannot be found automatically, SQL for ArcGIS Pro will launch a dialog to try to locate it.  Once found, the location of manifold.exe will then be saved in an environment variable for future reference.

 

Legacy Builds - SQL for ArcGIS Pro download pages provide current builds.  Newer builds fix bugs so it is important to work with the latest build.  If for some wild and crazy reason you think that in the future you will not want to upgrade to the latest build, make sure to save the installation file for whatever build has been installed, so that if a re-install is necessary you can work with an old and obsolete build instead of whatever wonderful new build is the current release.  Note that  tech support is available only for current builds, and not for obsolete legacy builds.

 

Three Letter Extensions - Most file names in Windows end in what usually is called a three letter extension, which is usually three or four letters at the end of the file name following a dot . character.    The three letter extension is one way Windows keeps track of what a file is supposed to be.    Unfortunately, by default Windows hides the three letter extensions of files and instead tries to associate files with whatever program it thinks should be used to open that file.   That may be helpful for inexpert consumers, but for skilled users it is inconvenient and can be misleading when working with the many file formats that ArcGIS Pro, SQL, and other geospatial products utilize.  

 

Tech tip:  Please turn off the hiding of extensions by Windows.  A typical way to do so in most versions of Windows would be from Windows Explorer, choose Tools - Folder options, press the View tab and then in the Advanced Settings pane ensure that the Hide extensions for known file types is unchecked.  Press Apply to Folders and then press OK.  You will then be able to see extensions such as .map and others.  See also the Essay on three letter extensions and why the default hiding of them by Windows is such a bad thing.

 

ODBC Driver - For any users interested in a really deep dive into Advanced mode capabilities, when an SQL for ArcGIS Pro project is saved into a .map file, there is an ODBC driver that allows third party applications to reach into that .map file.   The ODBC driver is installed automatically with Windows Installer installations.  When using a portable installation, the ODBC driver must be installed manually.  To do that, launch the Help - About dialog, and press the Update button on the ODBC line.    For routine work with ArcGIS Pro there is no need to install the ODBC driver.

 

See Also

SQL Activation

 

SQL for ArcGIS Pro

 

Getting Started with SQL

 

Localization