diff --git a/CHANGES.rst b/CHANGES.rst index a101686..f180d46 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -9,4 +9,6 @@ Unreleased - Consolidate ``cloud-reference``, ``cloud-howtos``, and ``cloud-tutorials`` - Adjust links to accompany renaming to ``cloud-docs`` - Adjust intersphinx references to accompany consolidation into single repository -- Rename top-level directories to `howtos`, `reference`, and `tutorials` \ No newline at end of file +- Rename top-level directories to `howtos`, `reference`, and `tutorials` +- Refactored content about connectivity concerns to dedicated section at + ``crate-client-tools`` diff --git a/docs/howtos/connect-to-cluster/cli.rst b/docs/howtos/connect-to-cluster/cli.rst deleted file mode 100644 index 8dc21fd..0000000 --- a/docs/howtos/connect-to-cluster/cli.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. _connect-cli: - -=== -CLI -=== - -This section provides a quick overview of CLI clients available for CrateDB -Cloud clusters. - -.. _crash: - -Crash ------ - -The CrateDB Shell (aka Crash) is an interactive command-line interface (CLI) -tool for working with CrateDB. - -Example command to connect to your cluster will look like this: - -.. code-block:: console - - crash --hosts 'https://.cratedb.net:4200' -U 'admin' -W - -See full documentation :ref:`here `. - -.. _psql: - -psql ----- - -psql is a terminal-based front-end to PostgreSQL. It enables you to type in -queries interactively, issue them to PostgreSQL, and see the query results. - -Example command to connect to your cluster will look like this: - -.. code-block:: console - - psql -h '.cratedb.net' -U 'admin' -W - -For more information see `Full psql documentation`_. - -.. _Full psql documentation: https://www.postgresql.org/docs/current/app-psql.html diff --git a/docs/howtos/connect-to-cluster/index.md b/docs/howtos/connect-to-cluster/index.md new file mode 100644 index 0000000..df69446 --- /dev/null +++ b/docs/howtos/connect-to-cluster/index.md @@ -0,0 +1,23 @@ +(connect-to-cluster-howto-index)= +# Connect to your cluster + +We are maintaining a collection of how-to guides and tutorials about how to +integrate with different applications, tools, libraries, extensions, and clients, +that can be used to connect to your CrateDB Cloud cluster. + + +::::{grid} 1 2 2 2 +:margin: 4 4 0 0 +:gutter: 1 + + +:::{grid-item-card} {material-outlined}`link;2em` Clients, Tools, and Integrations +:link: crate-clients-tools:index +:link-type: ref + +Learn about compatible client applications and tools, and how to configure +your favorite client library to connect to a CrateDB cluster. +::: + + +:::: diff --git a/docs/howtos/connect-to-cluster/index.rst b/docs/howtos/connect-to-cluster/index.rst deleted file mode 100644 index 317ae61..0000000 --- a/docs/howtos/connect-to-cluster/index.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _connect-to-cluster-howto-index: - -======================= -Connect to your cluster -======================= - -This collection of how-tos introduces multiple libraries, extensions, and -clients by which you can connect to your CrateDB Cloud cluster. The features -and capabilities of these tools vary greatly and are discussed in the -individual how-tos. - -.. rubric:: Table of contents - -.. toctree:: - :maxdepth: 1 - - cli - java - javascript - php - python - ruby diff --git a/docs/howtos/connect-to-cluster/java.rst b/docs/howtos/connect-to-cluster/java.rst deleted file mode 100644 index 1d237d2..0000000 --- a/docs/howtos/connect-to-cluster/java.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. _connect-java: - -==== -Java -==== - -JDBC is a standard Java API that provides a common interfaces for accessing -databases in Java. - -Example method used in implementation: - -.. code-block:: java - - import java.sql.*; - import java.util.Properties; - - public class Main { - public static void main(String[] args) { - try { - Properties properties = new Properties(); - properties.put("user", "admin"); - properties.put("password", ""); - properties.put("ssl", true); - Connection conn = DriverManager.getConnection( - "crate://.cratedb.net:5432/", - properties - ); - - Statement statement = conn.createStatement(); - ResultSet resultSet = statement.executeQuery("SELECT name FROM sys.cluster"); - resultSet.next(); - String name = resultSet.getString("name"); - - System.out.println(name); - } catch (SQLException e) { - e.printStackTrace(); - } - } - } - -See full documentation :ref:`here `. \ No newline at end of file diff --git a/docs/howtos/connect-to-cluster/javascript.rst b/docs/howtos/connect-to-cluster/javascript.rst deleted file mode 100644 index b42cff4..0000000 --- a/docs/howtos/connect-to-cluster/javascript.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. _connect-javascript: - -========== -Javascript -========== - -This section provides a quick overview of available node.js modules and -drivers for CrateDB Cloud. - -node-postgres -------------- - -node-postgres is a collection of node.js modules for interfacing with a CrateDB -Cloud database. - -Example implementation will look like this: - -.. code-block:: javascript - - const { Client } = require("pg"); - - const crateClient = new Client({ - host: ".cratedb.net", - port: 5432, - user: "admin", - password: "", - ssl: true, - }); - - (async () => { - await crateClient.connect(); - const result = await crateClient.query("SELECT name FROM sys.cluster"); - console.log(result.rows[0]); - })(); - -For more information see `node-postgres documentation`_. - -node-crate ----------- - -node-crate is an independent node.js driver implementation for CRATE using the _sql endpoint REST API. - -Example implementation will look like this: - -.. code-block:: javascript - - const crate = require("node-crate"); - - crate.connect(`https://admin:${encodeURIComponent("")}@.cratedb.net:4200`); - - (async () => { - const result = await crate.execute("SELECT name FROM sys.cluster"); - console.log(result.rows[0]); - })(); - - -For more information see `node-crate documentation`_. - -.. _node-postgres documentation: https://www.npmjs.com/package/pg -.. _node-crate documentation: https://www.npmjs.com/package/node-crate diff --git a/docs/howtos/connect-to-cluster/php.rst b/docs/howtos/connect-to-cluster/php.rst deleted file mode 100644 index 2ebae4d..0000000 --- a/docs/howtos/connect-to-cluster/php.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. _connect-php: - -=== -PHP -=== - -This section provides a quick overview of available PHP extensions for CrateDB -Cloud. - -PDO ---- - -The PHP Data Objects (PDO) is a standard PHP extension that defines a common -interface for accessing databases in PHP. - -Example implementation will look like this: - -.. code-block:: php - - .cratedb.net:4200', - 'admin', - '' - ); - - $stm = $pdo->query('SELECT name FROM sys.cluster'); - $name = $stm->fetch(); - print $name[0]; - - ?> - -See full documentation :ref:`here `. - -DBAL ----- - -DBAL is a PHP database abstraction layer that comes with database schema -introspection, schema management, and PDO support. - -Example implementation will look like this: - -.. code-block:: console - - 'Crate\DBAL\Driver\PDOCrate\Driver', - 'user' => 'admin', - 'password' = '', - 'host' => '.cratedb.net', - 'port' => 4200 - ); - - $connection = \Doctrine\DBAL\DriverManager::getConnection($params); - $sql = 'SELECT name FROM sys.cluster'; - $name = $connection->query($sql)->fetch(); - - print $name['name']; - - ?> - -See full documentation :ref:`here `. diff --git a/docs/howtos/connect-to-cluster/python.rst b/docs/howtos/connect-to-cluster/python.rst deleted file mode 100644 index bde9745..0000000 --- a/docs/howtos/connect-to-cluster/python.rst +++ /dev/null @@ -1,110 +0,0 @@ -.. _connect-python: - -====== -Python -====== - -This guideasdasd - -crate-python ------------- - -crate-python library implements the Python Database API 2.0 specification, -which defines a common interface for accessing databases in Python - -Example implementation will look like this: - -.. code-block:: python - - from crate import client - - conn = client.connect("https://.cratedb.net:4200", username="admin", password="", verify_ssl_cert=True) - - with conn: - cursor = conn.cursor() - cursor.execute("SELECT name FROM sys.cluster") - result = cursor.fetchone() - print(result) - -See full documentation :ref:`here `. - -psycopg2 --------- - -Psycopg is a popular PostgreSQL database adapter for Python. Its main features -are the complete implementation of the Python DB API 2.0 specification and the -thread safety (several threads can share the same connection). - -Example implementation will look like this: - -.. code-block:: python - - import psycopg2 - - conn = psycopg2.connect(host=".cratedb.net", port=5432, user="admin", password="", sslmode="require") - - with conn: - with conn.cursor() as cursor: - cursor.execute("SELECT name FROM sys.cluster") - result = cursor.fetchone() - print(result) - -For more information see `psycopg documentation`_. - -aiopg ------ - -aiopg is a python library for accessing a PostgreSQL database from the asyncio -PEP-3156/tulip) framework. It wraps asynchronous features of the Psycopg -database driver. - -Example implementation will look like this: - -.. code-block:: python - - import asyncio - import aiopg - - async def run(): - async with aiopg.create_pool(host=".cratedb.net", port=5432, user="admin", password="", sslmode="require") as pool: - async with pool.acquire() as conn: - async with conn.cursor() as cursor: - await cursor.execute("SELECT name FROM sys.cluster") - result = await cursor.fetchone() - print(result) - - loop = asyncio.get_event_loop() - loop.run_until_complete(run()) - -For more information see `aiopg documentation`_. - -asyncpg -------- - -asyncpg is a database interface library designed specifically for PostgreSQL -and Python/asyncio. asyncpg is an efficient, clean implementation of PostgreSQL -server binary protocol for use with Python’s asyncio framework. - -Example implementation will look like this: - -.. code-block:: python - - import asyncio - import asyncpg - - async def run(): - conn = await asyncpg.connect(host=".cratedb.net", port=5432, user="admin", password="", ssl=True) - try: - result = await conn.fetch("SELECT name FROM sys.cluster") - finally: - await conn.close() - print(result) - - loop = asyncio.get_event_loop() - loop.run_until_complete(run()) - -For more information see `asyncpg documentation`_. - -.. _psycopg documentation: https://www.psycopg.org/docs/ -.. _aiopg documentation: https://aiopg.readthedocs.io/ -.. _asyncpg documentation: https://magicstack.github.io/asyncpg/current/ diff --git a/docs/howtos/connect-to-cluster/ruby.rst b/docs/howtos/connect-to-cluster/ruby.rst deleted file mode 100644 index 29458ec..0000000 --- a/docs/howtos/connect-to-cluster/ruby.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _connect-ruby: - -==== -Ruby -==== - -This section shows an example implementation of Ruby client library for CrateDB -Cloud: - -.. code-block:: ruby - - require 'crate_ruby' - - client = CrateRuby::Client.new(servers=[".cratedb.net:4200"], username: "admin", password: "", ssl: true) - result = client.execute("SELECT name FROM sys.cluster") - p result.to_a - -For additional information see `our GitHub documentation`_. - -.. _our GitHub documentation: https://github.com/crate/crate_ruby/blob/main/README.rst \ No newline at end of file