.. _install_overview:

Install |ksqldb| for |cp|
============================

|ksqldb| is available as a component of |cp| and |ccloud|. For |cp| the |ksqldb| binaries are located at
:cp-download:`https://www.confluent.io/download/|` as a part of the |cp| bundle.

|ksqldb| must have access to a running |ak-tm| cluster, which can be in your data center, in a public cloud, |ccloud|, etc.

.. include:: ../.hidden/docs-common/home/includes/cloud-platform-cta.rst

Docker support
    You can deploy |ksqldb| by using :ksqldb-docs:`Docker containers|operate-and-deploy/installation/installing/`. Starting with |cp| 4.1.2,
    Confluent maintains images at `Docker Hub <https://hub.docker.com/r/confluentinc/cp-ksqldb-server/>`__.
    To start |ksqldb| containers in configurations like "|ksqldb| Headless Server" and
    "Interactive Server with Interceptors", see
    :ksqldb-docs:`Docker Configuration Parameters|operate-and-deploy/installation/server-config/config-reference/`.

Watch the `screencast of Installing and Running KSQL <https://www.youtube.com/embed/icwHpPm-TCA>`_ on YouTube.

---------------------------------------
Supported Versions and Interoperability
---------------------------------------

.. include:: includes/ksql-supported-versions.rst


.. _install_ksql-server:

-------------------------
Installation Instructions
-------------------------

Follow the instructions at :ref:`quickstart`.

Also, you can install |ksqldb| individually by using the
:ref:`confluent-ksql package <confluent-ksql-package>`.
For more information, see :ref:`available_packages`.

-------------------------------------
Scale Your |ksqldb| Server Deployment
-------------------------------------

You can scale |ksqldb| by adding more capacity per server (vertically) or by adding
more servers (horizontally). Also, you can scale |ksqldb| clusters during live operations
without loss of data. For more information, see :ksqldb-docs:`Scaling ksqlDB|operate-and-deploy/capacity-planning/#scaling-ksqldb`.

.. _start_ksql-server:

----------------------------
Starting the |ksqldb| Server
----------------------------

The |ksqldb| servers are run separately from the |ksqldb| CLI client and Kafka brokers. You can deploy servers on remote machines,
VMs, or containers and then the CLI connects to these remote servers.

You can add or remove servers from the same resource pool during live operations, to elastically scale query processing. You
can use different resource pools to support workload isolation. For example, you could deploy separate pools for production
and for testing.

You can only connect to one |ksqldb| server at a time. The |ksqldb| CLI does not support automatic failover to another |ksqldb| server.

.. image:: img/client-server.png
    :align: center

Follow these instructions to start |ksqldb| server using the ``ksql-server-start`` script.

.. include:: ../includes/installation-types-zip-tar.rst

#.  Specify your |ksqldb| server configuration parameters. You can also set any property for the Kafka Streams API, the Kafka
    producer, or the Kafka consumer. The required parameters are ``bootstrap.servers`` and ``listeners``. You can specify
    the parameters in the |ksqldb| properties file or the ``KSQL_OPTS`` environment variable. Properties set with ``KSQL_OPTS``
    take precedence over those specified in the properties file.

    A recommended approach is to configure a common set of properties using the |ksqldb| configuration file and override
    specific properties as needed, using the ``KSQL_OPTS`` environment variable.

    Here are the default settings:

    ::

        bootstrap.servers=localhost:9092
        listeners=http://0.0.0.0:8088

    For more information, see :ksqldb-docs:`Configure ksqlDB Server|operate-and-deploy/installation/server-config/`.

#.  Start a server node with this command:

    .. code:: bash

       ksql-server-start ${CONFLUENT_HOME}/etc/ksqldb/ksql-server.properties

    .. tip:: You can view the |ksqldb| server help text by running ``ksql-server-start --help``.

         ::

                NAME
                        server - KSQL Cluster

                SYNOPSIS
                        server [ {-h | --help} ] [ --queries-file <queriesFile> ] [--]
                                <config-file>

                OPTIONS
                        -h, --help
                            Display help information

                        --queries-file <queriesFile>
                            Path to the query file on the local machine.

                        --
                            This option can be used to separate command-line options from the
                            list of arguments (useful when arguments might be mistaken for
                            command-line options)

                        <config-file>
                            A file specifying configs for the KSQL Server, KSQL, and its
                            underlying Kafka Streams instance(s). Refer to KSQL documentation
                            for a list of available configs.

                            This option may occur a maximum of 1 times

#. Have a look at :ksqldb-docs:`this page|operate-and-deploy/installation/server-config/#non-interactive-headless-ksqldb-usage`
   for instructions on running |ksqldb| in non-interactive (aka headless) mode.

.. _install_ksql-cli:

-------------------------
Starting the |ksqldb| CLI
-------------------------

The |ksqldb| CLI is a client that connects to the |ksqldb| servers.

You can start the |ksqldb| CLI by providing the connection information to the |ksqldb| server.

.. code:: bash

    LOG_DIR=./ksql_logs ${CONFLUENT_HOME}/bin/ksql http://localhost:8088

.. include:: includes/ksql-includes.rst
    :start-after: log_limitations_start
    :end-before: log_limitations_qs_end

After |ksqldb| is started, your terminal should resemble this.

.. include:: includes/ksql-includes.rst
    :start-after: CLI_welcome_start
    :end-before: CLI_welcome_end

.. tip:: You can view the |ksqldb| CLI help text by running ``ksql --help``.

    ::

        NAME
                ksql - KSQL CLI

        SYNOPSIS
                ksql [ --config-file <configFile> ]
                        [ --confluent-api-key <ccloudApiKey> ]
                        [ --confluent-api-secret <ccloudApiSecret> ]
                        [ {--define | -d} <definedVars>... ]
                        [ {--execute | -e} <execute> ] [ {--file | -f} <scriptFile> ]
                        [ {-h | --help} ] [ --output <outputFormat> ]
                        [ {--password | -p} <password> ]
                        [ --query-row-limit <streamedQueryRowLimit> ]
                        [ --query-timeout <streamedQueryTimeoutMs> ]
                        [ {--user | -u} <userName> ] [--] [ <server> ]

        OPTIONS
                --config-file <configFile>
                    A file specifying configs for Ksql and its underlying Kafka Streams
                    instance(s). Refer to KSQL documentation for a list of available
                    configs.

                --confluent-api-key <ccloudApiKey>
                    If you're connecting to a Confluent Cloud ksqlDB server and would
                    like to use ksqlDB's connector management capabilities, then
                    provide your Confluent Cloud API key here. The API key secret must
                    be specified separately with the --confluent-api-secret flag

                --confluent-api-secret <ccloudApiSecret>
                    If you're connecting to a Confluent Cloud ksqlDB server and would
                    like to use ksqlDB's connector management capabilities, then
                    provide your Confluent Cloud API key secret here. The API key
                    itself must be specified separately with the --confluent-api-key
                    flag

                --define <definedVars>, -d <definedVars>
                    Define variables for the CLI session (equivalent to the DEFINE
                    statement).

                --execute <execute>, -e <execute>
                    Execute one or more SQL statements and quit.

                --file <scriptFile>, -f <scriptFile>
                    Execute commands from a file and exit.

                -h, --help
                    Display help information

                --output <outputFormat>
                    The output format to use (either 'JSON' or 'TABULAR'; can be
                    changed during REPL as well; defaults to TABULAR)

                --password <password>, -p <password>
                    If your KSQL server is configured for authentication, then provide
                    your password here. The username must be specified separately with
                    the -u/--user flag

                --query-row-limit <streamedQueryRowLimit>
                    An optional maximum number of rows to read from streamed queries

                    This options value must fall in the following range: value >= 1


                --query-timeout <streamedQueryTimeoutMs>
                    An optional time limit (in milliseconds) for streamed queries

                    This options value must fall in the following range: value >= 1


                --user <userName>, -u <userName>
                    If your KSQL server is configured for authentication, then provide
                    your user name here. The password must be specified separately with
                    the -p/--password flag

                --
                    This option can be used to separate command-line options from the
                    list of arguments (useful when arguments might be mistaken for
                    command-line options)

                <server>
                    The address of the Ksql server to connect to (ex:
                    http://confluent.io:9098)

                    This option may occur a maximum of 1 times

---------------------------------
Configuring |ksqldb| for |ccloud|
---------------------------------

You can use |ksqldb| with a Kafka cluster in |ccloud|. For more information, see :cloud:`Connecting ksqlDB to Confluent Cloud|cp-component/ksql-cloud-config.html`.