AppCode 2019.2 Help

Cannot connect to a database

Step 1. Check your network settings

Databases can work locally, on a server, or in the cloud. For server and cloud databases, you need a network connection. To verify that connection is available, use ping and telnet commands.

With the ping command, you can ensure that the destination computer is reachable from the source computer. Open a command line and type the following command: ping -a <host_IP>, where -a is a command option that resolves addresses to hostnames (if it is possible). If you use hostnames with the ping command, a hostname is resolved to the IP address. For example, ping -a example.com resolves to PING example.com (93.184.216.34).

ping -a <host_IP>
Test connection with the ping command

With the telnet command, you can test connectivity to remote computers and issue commands. If you specify a port as a parameter for the telnet command, you can test connectivity to a remote host on the given port. If the connection is successful, you see the message: Connected to <host_IP>.

telnet <host_IP> <port_number>
Test connection with the telnet command

Step 2. Check your connection properties

Each database (MySQL, PostgreSQL, Oracle, or any other vendor) has its own connection settings. Most database include the connection settings:

  • Host: A hostname of a computer or other device that stores a database. It can be an IP address 127.0.0.1 or a domain name localhost.

  • Database: A name of the database to which you want to connect. You can find the database name in the settings of your database server, or you can ask your database administrator. In some cases, it is possible to run a query in a database command line to see names of all available databases. For example, in MySQL you can run SHOW DATABASES;.

    The SHOW DATABASES query

  • User: A name of a user that has sufficient privileges to perform actions with a database. Run a query in a database command line to see names of all available databases. For example, in MySQL you can run SHOW GRANTS;.

    The SHOW GRANTS query

  • Password: A password of the user.

  • Port: An number that identifies a connection point between hosts. Hosts use port numbers to determine to which application, service, or process a connection must be established. Different database vendors use different ports for their databases. The following list is a list of default port numbers.

    Vendor

    Default port

    Amazon Redshift

    5439

    Apache Derby

    1527

    Apache Cassandra

    9042

    Apache Hive

    10000 (Hive Server2) or 9083 (Hive Metastore)

    Azure SQL Database

    1433

    ClickHouse

    8123

    Exasol

    8563

    Greenplum

    5432

    H2

    8082

    HSQLDB

    9001

    IBM Db2

    50000

    MariaDB

    3306

    Microsoft SQL Server

    1433 (TCP), 1434 (UDP might be required)

    MySQL

    3306

    Oracle

    1521

    PostgreSQL

    5432

    Snowflake

    443

    SQLite

    None

    Sybase ASE

    5000

    Vertica

    5433

Verify that the connection settings for the selected database connection are correct. For more information about creating or changing a database connection, see Connecting to a database.

Step 3. Check the driver version

With a JDBC driver, you can interact with a database management system (DBMS) from AppCode. Each DBMS requires its own JDBC driver. Ensure that the driver version and the DBMS version are compatible with each other.

From AppCode, you can download drivers for all supported vendors. You can check the full list of supported vendors in the Drivers list ⌘,. Alternatively, you can add your own driver to an existing vendor, or create a new driver entry for the vendor that is not on the Drivers list.

Download a driver and select the driver version

To download drivers from the JetBrains FTP server, select a vendor from the Drivers list, and click the Download ver. <version_number> link in the Driver files pane.

To change the driver version, click the ver. <version_number> link in the Driver files pane and select the driver version that you need.

The Drivers list and driver settings

Create a connection to a database with a JDBC driver

If you cannot find a name of a database vendor in the list of data sources, download a JDBC driver for the database management system (DBMS), and create a connection in AppCode. With the JDBC driver, you can connect to DBMS and start working.

  1. In the Database tool window (View | Tool Windows | Database), click the Data Source Properties icon The Data Source Properties icon.

  2. In the Data Sources and Drivers dialog, click the Add icon (The Add icon) and select Driver and Data Source.

  3. Click the User Driver link.

  4. In the Driver files pane, click the Add icon and select Custom JARs.

  5. Navigate to the JAR file of the JDBC driver, select it, and click OK.

  6. In the Class field, specify the value that you want to use for the driver.

  7. Click Apply.

  8. Return to the created data source connection.

  9. Specify database connection details. Alternatively, paste the JDBC URL in the URL field.

    To set an empty password, right-click the Password field and select Set empty.

  10. To ensure that the connection to the data source is successful, click Test Connection.

Add a JDBC driver to an existing connection

  1. In the Database tool window (View | Tool Windows | Database), click the Data Source Properties icon The Data Source Properties icon.

  2. In the Data Sources and Drivers dialog, select a data source where you want to change a driver, and click the Driver link in data source settings.

  3. In the Driver files pane, click the Add icon (The Add icon) and select Custom JARs.

  4. Navigate to the JAR file of the JDBC driver, select it, and click OK.

  5. In the Class field, specify the value that you want to use for the driver.

  6. Click Apply.

Step 4. Check if the connection with SSH or SSL is required

To make a connection to a database more secure, some services require SSH or SSL usage. For some services, you need to apply certain JDBC options to use SSL or the SSH tunnel (for example, when you try to connect to Heroku Postgres).

Connect to a database with SSL

  1. In the Database tool window (View | Tool Windows | Database), click the Data Source Properties icon The Data Source Properties icon.

  2. Select a data source profile where you want to change connection settings.

  3. Click the SSH/SSL tab and select the Use SSL checkbox.

  4. In the CA file field, navigate to the CA certificate file (for example, ca.pem).

  5. In the Client certificate file field, navigate to the client certificate file (for example, client-cert.pem).

  6. In the Client key file field, navigate to the client key file (for example, client-key.pem).

  7. To ensure that the connection to the data source is successful, click Test Connection.

Connect to a database with SSL

Connect to a database with SSH

  1. In the Database tool window (View | Tool Windows | Database), click the Data Source Properties icon The Data Source Properties icon.

  2. Select a data source profile where you want to change connection settings.

  3. Click the SSH/SSL tab and select the Use SSH tunnel checkbox.

  4. In Proxy host, Proxy user, Proxy password, and Port fields, specify connection details.

  5. From the Auth type list, select an authentication method:

    • Password: to access the host with a password. Specify the password, and select the Save password checkbox to save the password in AppCode.

    • Key pair (OpenSSH or PuTTY): to use SSH authentication with a key pair. To apply this authentication method, you must have a private key on the client machine and a public key on the remote server. AppCode supports private keys that are generated with the OpenSSH utility.

      Specify the path to the file where your private key is stored and type the passphrase (if any) in the corresponding fields. To have AppCode remember the passphrase, select the Save passphrase checkbox.

    • If your SSH keys are managed by a credentials helper application (for example, ssh-agent ), choose OpenSSH config and authentication agent.

  6. To ensure that the connection to the data source is successful, click Test Connection.

SSH and SSL settings of a data source

Create the SSH tunnel with PuTTY (Windows)

  1. Download and run the latest version of the PuTTY SSH and Telnet client (download the client from https://www.putty.org/).

  2. In the PuTTY Configuration dialog, navigate to Connection | SSH | Auth.

  3. In the Private key file for authentication field, specify the path to your private key file and click Open.

  4. In the command line window, specify the username that you use for the SSH tunnel and press . Do not close the command line window.

  5. In the Database window (View | Tool Windows | Database), click the Data Source Properties icon the Data Source Properties icon on the toolbar.

  6. Select a data source profile where you want to change connection settings.

  7. Click the SSH/SSL tab and select the Use SSH tunnel checkbox.

  8. From the Auth type list, select OpenSSH config and authentication agent.

  9. In Proxy host, Proxy user, and Port fields, specify connection details.

  10. To ensure that the connection to the data source is successful, click Test Connection.

Create the SSH tunnel with PuTTY (Windows)

Create the SSH tunnel with Pageant (Windows)

Pageant is an SSH authentication agent for PuTTY, PSCP, PSFTP, and Plink. Pageant stores your private key, and as long as it is running, it provides the unlocked private key to PuTTY or other tools like AppCode. You can find the Pageant icon in the Windows taskbar.

  1. Download the latest version of Pageant (download the client from https://www.putty.org/).

  2. In the Windows taskbar, right-click the Pageant icon and select Add Key.

  3. In the Select Private Key File dialog, navigate to the private key file (the PPK file) and click Open.

  4. (Optional) Enter the private key passphrase and press .

  5. In the Database window (View | Tool Windows | Database), click the Data Source Properties icon the Data Source Properties icon on the toolbar.

  6. Select a data source profile where you want to change connection settings.

  7. Click the SSH/SSL tab and select the Use SSH tunnel checkbox.

  8. From the Auth type list, select OpenSSH config and authentication agent.

  9. In Proxy host, Proxy user, and Port fields, specify connection details.

  10. To ensure that the connection to the data source is successful, click Test Connection.

Create the SSH tunnel with Pageant (Windows)

Create the SSH tunnel with the ssh-agent (macOS and Linux)

Run all commands for ssh-agent in the command line.

  1. Ensure that ssh-agent is running.

    ssh-agent

  2. Add your key to the agent (in the following example, the key path is ~/.ssh/id_rsa).

    ssh-add ~/.ssh/id_rsa

  3. (Optional) On macOS, you can add -K option to the ssh-add command to store passphrases in your keychain. On macOS Sierra and later, you need to create the config file in ~/.ssh/ with the following text:

    Host * UseKeychain yes AddKeysToAgent yes IdentityFile ~/.ssh/id_rsa

    If you have other private keys in the .ssh directory, add an IdentityFile line for each key. For example, if the second key has the id_ed25519 name, add IdentityFile ~/.ssh/id_ed25519 as an additional line for the second private key.

  4. List all added keys.

    ssh-add -L

  5. In the Database window (View | Tool Windows | Database), click the Data Source Properties icon the Data Source Properties icon on the toolbar.

  6. Select a data source profile where you want to change connection settings.

  7. Click the SSH/SSL tab and select the Use SSH tunnel checkbox.

  8. From the Auth type list, select OpenSSH config and authentication agent.

  9. In Proxy host, Proxy user, and Port fields, specify connection details.

  10. To ensure that the connection to the data source is successful, click Test Connection.

Create the SSH tunnel with the ssh-agent (macOS and Linux)

Step 5. Write to us if you still need help

Write to the AppCode team

Write to our team at appcode-support@jetbrains.com. Describe your problem, and attach all available materials that can speed up troubleshooting (code samples, screenshots, logs, animations, videos, and other materials).

Last modified: 10 October 2019