Create Database Connection (Data Management)

Summary

Creates a file that ArcGIS uses to connect to a database or an enterprise geodatabase.

Usage

• After valid connection information is provided on the tool dialog box to establish a connection, the tool will connect to the database to determine if it contains the geodatabase schema.

  • For databases, all the parameters in the Geodatabase Connection Properties parameter category in the Geoprocessing pane will be ignored.
  • For geodatabases, the tool automatically populates the Geodatabase Connection Properties parameter category. The Schema parameter is set with the sde schema (for Oracle user schema geodatabases only), the default Version Type value for the geodatabase, and the Default version.

• If you don't want to save the connection information in the Results window or don't want to store it in the geoprocessing history log files, disable all logging options for geoprocessing history and save the connection file without saving the connection information.

• Connections from ArcGIS to Altibase and Netezza are no longer supported.

Parameters

Dialog

Label	Explanation	Data Type
Connection File Location	The folder path where the database connection file (.sde) will be stored.	Folder
Connection File Name	The name of the database connection file. The output file will have the .sde extension.	String
Database Platform	Specifies the database management system platform to which the connection will be made. The following are valid options: BigQuery—The connection will be made to Google BigQuery. Dameng—The connection will be made to Dameng. Db2—The connection will be made to IBM Db2 for Linux, UNIX, or Windows. Oracle—The connection will be made to Oracle, Amazon Relational Database Service (RDS) for Oracle, or Autonomous Transaction Processing. PostgreSQL—The connection will be made to PostgreSQL, Amazon Aurora (PostgreSQL-compatible edition), Amazon Relational Database Service (RDS) for PostgreSQL, Google Cloud SQL for PostgreSQL, Microsoft Azure Database for PostgreSQL, or Microsoft Azure Cosmos DB for PostgreSQL. Redshift—The connection will be made to Amazon Redshift. Teradata—The connection will be made to Teradata Vantage. SAP HANA—The connection will be made to SAP HANA or SAP HANA Cloud. Snowflake—The connection will be made to Snowflake. SQL Server—The connection will be made to Microsoft SQL Server, Microsoft Azure SQL Database, Microsoft Azure SQL Managed Instance, Amazon Relational Database Service (RDS) for SQL Server, or Google Cloud SQL for SQL Server.	String
Instance/Server (Optional)	The database server or instance to which the connection will be made. The value you choose from the Database Platform drop-down list indicates the type of database or cloud data warehouse to which the connection will be made. The information you provide for the Instance/Server parameter will vary, depending on the connection type you choose. See below for information about what to provide for each platform. Dameng—The name of the server where the Dameng database is installed Db2—The name of the cataloged Db2 database Oracle—Either the TNS name or the Oracle Easy Connection string to connect to the Oracle database or database service PostgreSQL—The name of the server where PostgreSQL is installed or the name of the PostgreSQL database service instance Redshift—The URL for the Redshift server SAP HANA—The Open Database Connectivity (ODBC) data source name for the SAP HANA database or database service Snowflake—The URL of the Snowflake server SQL Server—The name of the SQL Server database instance or the name of the database service instance Teradata—The ODBC data source name for the Teradata database	String
Database Authentication (Optional)	Specifies the type of authentication that will be used. Database authentication—Database authentication will be used. An internal database username and a password will be used to connect to the database. You aren't required to provide your username and password to create a connection; however, if you don't, you will be prompted to enter them when a connection is established. Note: If the connection file you are creating will provide ArcGIS services with access to the database or geodatabase, or if you want to use the Catalog search to locate data accessed through this connection file, you must include a username and password. Operating system authentication—Operating system authentication will be used. You do not need to provide a username and password. The connection will be made with the username and password that were used to log in to the operating system. If the login used for the operating system is not a valid database login, the connection will fail.	Boolean
Username (Optional)	The database username that will be used for database authentication.	String
Password (Optional)	The database user password that will be used for database authentication.	Encrypted String
Save username and password (Optional)	Specifies whether the username and password will be saved. Checked—The username and password will be saved in the connection file. This is the default. If the connection file you are creating will provide ArcGIS services with access to the database, geodatabase, or cloud data warehouse, if you need to use the Catalog search to locate data accessed through this connection file, or if you will use the connection file in a script, you must save the username and password. Unchecked—The username and password will not be saved in the connection file. Every time you attempt to connect using the file, you will be prompted for the username and password. Note: ArcGIS Pro caches credentials for the first successful database connection for which you do not save the username and password. If you create a second connection to the same database, geodatabase, or cloud data warehouse instance in the same ArcGIS Pro session and do not save credentials, the cached credentials from the first connection are used even if you provide different credentials in the second connection file. To connect with different credentials without saving the username and password, start a new ArcGIS Pro session.	Boolean
Database (Optional)	The name of the database to which the connection will be made. This parameter applies to PostgreSQL, Redshift, Snowflake, and SQL Server platforms.	String
Schema (Oracle user schema geodatabases only) (Optional)	The user schema geodatabase to which the connection will be made. The tool will determine if it is connecting to an Oracle database that contains a user–schema geodatabase. If the Oracle database contains a user schema, this option is active; otherwise, it remains inactive. The default option for this parameter is to use the sde schema geodatabase.	String
Version Type (Optional)	Specifies the type of version to which the connection will be made. This parameter only applies when connecting to a geodatabase. Note: If Historical is selected and a name is not provided, the default transactional version will be used. If Point in time is selected and a date is not provided for the Date and Time parameter, the default transactional version will be used. Transactional—The connection will be made to a transactional version. If Transactional is selected, the The following version will be used parameter will be populated with a list of transactional versions, and the Date and Time parameter will be inactive. This is the default. Historical—The connection will be made to an historical marker. If Historical is selected, the The following version will be used parameter will be populated with a list of historical markers, and the Date and Time parameter will be inactive. Point in time—The connection will be made to a specific point in time. If Point in time is selected, the The following version will be used parameter will be inactive, and the Date and Time parameter will become active. Branch—The connection will be made to the default branch version.	String
The following version will be used (Optional)	The geodatabase transactional version or historical marker to which the connection will be made. The default option uses the default transactional version. If you choose a branch version type, the connection is always to the default branch version.	String
Date and Time (Optional)	The value representing the date and time that will be used to connect to the database. This option is used with archive-enabled data. Use the time picker to choose the appropriate date. If manually entering a date, the following formats can be used: 6/9/2011 4:20:15 PM 6/9/2011 16:20:15 6/9/2011 4:20:15 PM 16:20:15 Note: If a time is entered without a date, the default date of December 30, 1899, will be used. If a date is entered without a time, the default time of 12:00:00 AM will be used.	Date
Advanced Authentication Type (Optional)	Specifies the advanced authentication type that will be used when connecting to a cloud data warehouse, Microsoft Azure SQL Database, or Azure SQL Managed Instance. Microsoft Entra MFA—The Microsoft Entra multifactor authentication (MFA) username authentication type will be used, but not the password. When you connect, a code is sent to you in a text message, email, or MFA device, or it can use a fingerprint scan for authentication. This second part of the authentication process varies depending on how your network and authentication protocols are configured. This option is supported for Azure SQL Database and Azure SQL Managed Instance only. Microsoft Entra Password—The Microsoft Entra Password authentication type, which requires username and password parameter values, will be used. Usernames can be a maximum of 30 characters. This option is supported for Azure SQL Database and Azure SQL Managed Instance only. Microsoft Entra Integrated—The Microsoft Entra Integrated authentication type will be used. You do not need to provide a username and password. The connection will be made with the username and password that were used to log in to the operation system. This option is supported for Azure SQL Database and Azure SQL Managed Instance only. Service Authentication—The service authentication type when connecting to Google BigQuery will be used. See Google BigQuery documentation about authentication for information. Standard—The standard authentication type when connecting to Amazon Redshift will be used. See the Amazon Redshift ODBC Data Connector Installation and Configuration Guide for information about standard authentication. User—An authentication method that requires a username and password when connecting to Snowflake will be used. User Authentication—The user authentication type when connecting to Google BigQuery will be used. See Google BigQuery documentation about authentication for information.	String
Project ID (Optional)	The project ID for the Google BigQuery connection.	String
Default Dataset (Optional)	The default dataset for the Google BigQuery connection.	String
Refresh Token (Optional)	The refresh token value. This parameter is only applicable for Google BigQuery connections when the advanced authentication type is user authentication.	Encrypted String
Key File (Optional)	The key file value. This parameter is only applicable for Google BigQuery connections when the advanced authentication type is server authentication.	File
Role (Optional)	The role value for a cloud data warehouse connection. This parameter is only applicable for connections to Snowflake.	String
Warehouse (Optional)	The warehouse value for the connection. This parameter is only applicable for connections to Snowflake.	String
Advanced Options (Optional)	The advanced options for the connection. This is optional connection information that is specific to the cloud data warehouse platform (Google BigQuery, Amazon Redshift, or Snowflake) to which you connect. Provide advanced options using Option=<value> separated by semicolons. For example, option1=value1;option2=value2;. Consult the cloud data warehouse documentation for information about optional connection options.	String

Derived Output

Label	Explanation	Data Type
Output Workspace	The output database connection file (.sde).	workspace

Python

arcpy.management.CreateDatabaseConnection(out_folder_path, out_name, database_platform, {instance}, {account_authentication}, {username}, {password}, {save_user_pass}, {database}, {schema}, {version_type}, {version}, {date}, {auth_type}, {project_id}, {default_dataset}, {refresh_token}, {key_file}, {role}, {warehouse}, {advanced_options})

Name	Explanation	Data Type
out_folder_path	The folder path where the database connection file (.sde) will be stored.	Folder
out_name	The name of the database connection file. The output file will have the .sde extension.	String
database_platform	Specifies the database management system platform to which the connection will be made. The following are valid options: BIGQUERY—The connection will be made to Google BigQuery. DAMENG—The connection will be made to Dameng. DB2—The connection will be made to IBM Db2 for Linux, UNIX, or Windows. ORACLE—The connection will be made to Oracle, Amazon Relational Database Service (RDS) for Oracle, or Autonomous Transaction Processing. POSTGRESQL—The connection will be made to PostgreSQL, Amazon Aurora (PostgreSQL-compatible edition), Amazon Relational Database Service (RDS) for PostgreSQL, Google Cloud SQL for PostgreSQL, Microsoft Azure Database for PostgreSQL, or Microsoft Azure Cosmos DB for PostgreSQL. REDSHIFT—The connection will be made to Amazon Redshift. SAP HANA—The connection will be made to SAP HANA or SAP HANA Cloud. SNOWFLAKE—The connection will be made to Snowflake. SQL_SERVER—The connection will be made to Microsoft SQL Server, Microsoft Azure SQL Database, Microsoft Azure SQL Managed Instance, Amazon Relational Database Service (RDS) for SQL Server, or Google Cloud SQL for SQL Server. TERADATA—The connection will be made to Teradata Vantage.	String
instance (Optional)	The database server or instance to which the connection will be made. The value you specify for the database_platform parameter indicates the type of database or cloud data warehouse to which the connection will be made. The information you provide for the instance parameter will vary, depending on the platform you specified. See below for information about what to provide for each platform. Dameng—The name of the server where the Dameng database is installed Db2—The name of the cataloged Db2 database Oracle—Either the TNS name or the Oracle Easy Connection string to connect to the Oracle database or database service PostgreSQL—The name of the server where PostgreSQL is installed or the name of the PostgreSQL database service instance Redshift—The URL for the Redshift server SAP HANA—The Open Database Connectivity (ODBC) data source name for the SAP HANA database or database service Snowflake—The URL of the Snowflake server SQL Server—The name of the SQL Server database instance or the name of the database service instance Teradata—The ODBC data source name for the Teradata database	String
account_authentication (Optional)	Specifies the type of authentication that will be used. DATABASE_AUTH—Database authentication will be used. An internal database username and a password will be used to connect to the database. You aren't required to provide your username and password to create a connection; however, if you don't, you will be prompted to enter them when a connection is established. Note: If the connection file you are creating will provide ArcGIS services with access to the database or geodatabase, or if you want to use the Catalog search to locate data accessed through this connection file, you must include a username and password. OPERATING_SYSTEM_AUTH—Operating system authentication will be used. You do not need to provide a username and password. The connection will be made with the username and password that were used to log in to the operating system. If the login used for the operating system is not a valid database login, the connection will fail.	Boolean
username (Optional)	The database username that will be used for database authentication.	String
password (Optional)	The database user password that will be used for database authentication.	Encrypted String
save_user_pass (Optional)	Specifies whether the username and password will be saved. SAVE_USERNAME—The username and password will be saved in the connection file. This is the default. If the connection file you are creating will provide ArcGIS services with access to the database, geodatabase, or cloud data warehouse, or if you want to use the Catalog search to locate data accessed through this connection file, you must save the username and password. DO_NOT_SAVE_USERNAME—The username and password will not be saved in the connection file. Every time you attempt to connect using the file, you will be prompted for the username and password. Note: ArcGIS Pro caches credentials for the first successful database connection for which you do not save the username and password. If you create a second connection to the same database, geodatabase, or cloud data warehouse instance in the same ArcGIS Pro session and do not save credentials, the cached credentials from the first connection are used even if you provide different credentials in the second connection file. To connect with different credentials without saving the username and password, start a new ArcGIS Pro session.	Boolean
database (Optional)	The name of the database to which the connection will be made. This parameter applies to PostgreSQL, Redshift, Snowflake, and SQL Server platforms.	String
schema (Optional)	The user schema geodatabase to which the connection will be made. This option only applies to Oracle databases that contain at least one user–schema geodatabase. The default value for this parameter is to use the sde schema geodatabase.	String
version_type (Optional)	Specifies the type of version to which the connection will be made. TRANSACTIONAL—The connection will be made to a traditional transactional version. Note: This option does not apply to geodatabases in SAP HANA. HISTORICAL—The connection will be made to an historical marker. POINT_IN_TIME—The connection will be made to a specific point in time. If POINT_IN_TIME is used, the version parameter will be ignored. BRANCH—The connection will be made to the default branch version. Note: If TRANSACTIONAL or HISTORICAL is used, the date parameter will be ignored. If HISTORICAL is used and a name is not provided for the version parameter, the default transactional version will be used. If POINT_IN_TIME is used and a date is not provided for the date parameter, the default transactional version will be used.	String
version (Optional)	The geodatabase transactional version or historical marker to which the connection will be made. The default option uses the default transactional version. If you choose a branch version type, the connection is always to the default branch version.	String
date (Optional)	The value representing the date and time that will be used to connect to the database when working with archive-enabled data. Dates can be entered in the following formats: 6/9/2011 4:20:15 PM 6/9/2011 16:20:15 6/9/2011 4:20:15 PM 16:20:15 Note: If a time is entered without a date, the default date of December 30, 1899, will be used. If a date is entered without a time, the default time of 12:00:00 AM will be used.	Date
auth_type (Optional)	Specifies the advanced authentication type that will be used when connecting to a cloud data warehouse, Microsoft Azure SQL Database, or Azure SQL Managed Instance. AZURE_ACTIVE_DIRECTORY_UNIVERSAL_WITH_MFA—The Microsoft Entra multifactor authentication (MFA) username authentication type will be used, but not the password. When you connect, a code is sent to you in a text message, email, or MFA device, or it can use a fingerprint scan for authentication. This second part of the authentication process varies depending on how your network and authentication protocols are configured. This option is supported for Azure SQL Database and Azure SQL Managed Instance only. AZURE_ACTIVE_DIRECTORY_PASSWORD—The Microsoft Entra Password authentication type, which requires username and password parameter values, will be used. Usernames can be a maximum of 30 characters. This option is supported for Azure SQL Database and Azure SQL Managed Instance only. AZURE_ACTIVE_DIRECTORY_INTEGRATEDSERVICE_AUTHENTICATION—The Microsoft Entra Integrated authentication type will be used. You do not need to provide a username and password. The connection will be made with the username and password that were used to log in to the operation system. This option is supported for Azure SQL Database and Azure SQL Managed Instance only. SERVICE_AUTHENTICATION—The service authentication type when connecting to Google BigQuery will be used. See Google BigQuery documentation about authentication for information. STANDARD—The standard authentication type when connecting to Amazon Redshift will be used. See the Amazon Redshift ODBC Data Connector Installation and Configuration Guide for information about standard authentication. USER—An authentication method that requires a username and password when connecting to Snowflake will be used. USER_AUTHENTICATION—The user authentication type when connecting to Google BigQuery will be used. See Google BigQuery documentation about authentication for information.	String
project_id (Optional)	The project ID for the Google BigQuery connection.	String
default_dataset (Optional)	The default dataset for the Google BigQuery connection.	String
refresh_token (Optional)	The refresh token value. This parameter is only applicable for Google BigQuery connections when the advanced authentication type is user authentication.	Encrypted String
key_file (Optional)	The key file value. This parameter is only applicable for Google BigQuery connections when the advanced authentication type is server authentication.	File
role (Optional)	The role value for a cloud data warehouse connection. This parameter is only applicable for connections to Snowflake.	String
warehouse (Optional)	The warehouse value for the connection. This parameter is only applicable for connections to Snowflake.	String
advanced_options (Optional)	The advanced options for the connection. This is optional connection information that is specific to the cloud data warehouse platform (Google BigQuery, Amazon Redshift, or Snowflake) to which you connect. Provide advanced options using Option=<value> separated by semicolons. For example, option1=value1;option2=value2;. Consult the cloud data warehouse documentation for information about optional connection options.	String

Derived Output

Name	Explanation	Data Type
out_workspace	The output database connection file (.sde).	workspace

Code sample

CreateDatabaseConnection example 1 (Python window)

The following Python window script demonstrates how to use the CreateDatabaseConnection function in immediate mode.

import arcpy
arcpy.CreateDatabaseConnection_management("C:\\MyProject",
                                          "utah.sde",
                                          "SQL_SERVER",
                                          "utah",
                                          "DATABASE_AUTH",
                                          "gdb",
                                          "gdb",
                                          "SAVE_USERNAME",
                                          "garfield",
                                          "#",
                                          "TRANSACTIONAL",
                                          "sde.DEFAULT")

CreateDatabaseConnection example 2 (stand-alone script)

The following stand-alone script demonstrates how to use the CreateDatabaseConnection function.

# Name: CreateDatabaseConnection2.py
# Description: Connects to a database using Easy Connect string
#              and operating system authentication.

# Import system modules
import arcpy

# Run the tool
arcpy.CreateDatabaseConnection_management("C:\\MyProject",
                                          "zion.sde",
                                          "ORACLE",
                                          "zionserver/ORCL",
                                          "OPERATING_SYSTEM_AUTH")

CreateDatabaseConnection example 3 (Python window)

The following Python window script demonstrates how to use the CreateDatabaseConnection function to connect to an historical marker.

# Name: CreateDatabaseConnection3.py
# Description: Connects to a geodatabase historical marker using a
#              cataloged DB2 database and database authentication.

# Import system modules
import arcpy

# Run the tool
arcpy.CreateDatabaseConnection_management("C:\\MyProject",
                                          "history.sde",
                                          "DB2",
                                          "DB2_DS",
                                          "DATABASE_AUTH",
                                          "butch",
                                          "sundance",
                                          "SAVE_USERNAME",
                                          "#",
                                          "#",
                                          "HISTORICAL",
                                          "June 9, 2010",
                                          "#")

CreateDatabaseConnection example 4 (Python window)

The following Python window script demonstrates how to use the CreateDatabaseConnection function to connect to a point in time.

# Name: CreateDatabaseConnection4.py
# Description: Connects to a point in time in the geodatabase in
#              PostgreSQL using database authentication.

# Import system modules
import arcpy

# Run the tool
arcpy.CreateDatabaseConnection_management("C:\\MyProject",
                                          "history.sde",
                                          "POSTGRESQL",
                                          "dbserver",
                                          "DATABASE_AUTH",
                                          "stevie",
                                          "smith",
                                          "SAVE_USERNAME",
                                          "archivedb",
                                          "#",
                                          "POINT_IN_TIME",
                                          "#",
                                          "5/19/2011 8:43:41 AM")

Environments

Current Workspace