Skip to content

Commit d340a1e

Browse files
amotlamotl
committed
Connect: Migrate pages from crate-clients-tools, to be phased out soon
1 parent fead459 commit d340a1e

File tree

18 files changed

+1458
-173
lines changed

18 files changed

+1458
-173
lines changed

‎docs/connect/cli.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
(cli)=
2+
(connect-cli)=
3+
# Using command-line programs with CrateDB
4+
5+
This section provides a quick overview about a few CLI programs, and how to
6+
use them for connecting to CrateDB clusters. We recommend to use crash,
7+
psql, http ([HTTPie]), or curl.
8+
9+
You can use them to quickly validate HTTP and PostgreSQL connectivity to your
10+
database cluster, or to conduct basic scripting.
11+
12+
Before running the command-line snippets outlined below, please use the correct
13+
settings instead of the placeholder tokens `<hostname>`, `<username>` and
14+
`<password>`.
15+
16+
When using CrateDB Cloud, `<hostname>` will be something like
17+
`<clustername>.{aks1,eks1}.region.{azure,aws}.cratedb.net`.
18+
19+
20+
(crash)=
21+
## crash
22+
23+
```{div}
24+
:style: "float: right"
25+
![image](https://cratedb.com/docs/crate/crash/en/latest/_images/query.png){w=240px}
26+
```
27+
28+
The **CrateDB Shell** is an interactive command-line interface (CLI) tool for
29+
working with CrateDB. For more information, see the documentation about [crash].
30+
31+
```{div}
32+
:style: "clear: both"
33+
```
34+
35+
::::{tab-set}
36+
37+
:::{tab-item} CrateDB and CrateDB Cloud
38+
:sync: server
39+
40+
```{code-block} shell
41+
CRATEPW=<password> \
42+
crash --hosts 'https://<hostname>:4200' --username '<username>' \
43+
--command "SELECT 42.42;"
44+
```
45+
:::
46+
47+
:::{tab-item} CrateDB on localhost
48+
:sync: localhost
49+
50+
```{code-block} shell
51+
# No authentication.
52+
crash --command "SELECT 42.42;"
53+
54+
```
55+
:::
56+
57+
::::
58+
59+
60+
(psql)=
61+
## psql
62+
63+
```{div}
64+
:style: "float: right"
65+
![image](https://github.com/crate/crate-clients-tools/assets/453543/8f0a0e06-87f6-467f-be2d-b38121afbafa){w=240px}
66+
```
67+
68+
**psql** is a terminal-based front-end to PostgreSQL. It enables you to type in
69+
queries interactively, issue them to PostgreSQL, and see the query results.
70+
For more information, see the documentation about [psql].
71+
72+
```{div}
73+
:style: "clear: both"
74+
```
75+
76+
::::{tab-set}
77+
78+
:::{tab-item} CrateDB and CrateDB Cloud
79+
:sync: server
80+
81+
```{code-block} shell
82+
PGUSER=<username> PGPASSWORD=<password> \
83+
psql postgresql://<hostname>/crate --command "SELECT 42.42;"
84+
```
85+
:::
86+
87+
:::{tab-item} CrateDB on localhost
88+
:sync: localhost
89+
90+
```{code-block} shell
91+
# No authentication.
92+
psql postgresql://crate@localhost:5432/crate --command "SELECT 42.42;"
93+
```
94+
:::
95+
96+
::::
97+
98+
99+
(httpie)=
100+
## HTTPie
101+
102+
```{div}
103+
:style: "float: right"
104+
![image](https://github.com/crate/crate-clients-tools/assets/453543/f5a2916d-3730-4901-99cf-b88b9af03329){w=240px}
105+
```
106+
107+
The **HTTPie CLI** is a modern, user-friendly command-line HTTP client with
108+
JSON support, colors, sessions, downloads, plugins & more.
109+
For more information, see the documentation about [HTTPie].
110+
111+
```{div}
112+
:style: "clear: both"
113+
```
114+
115+
::::{tab-set}
116+
117+
:::{tab-item} CrateDB and CrateDB Cloud
118+
:sync: server
119+
120+
```{code-block} shell
121+
http "https://<username>:<password>@<hostname>:4200/_sql?pretty" \
122+
stmt="SELECT 42.42;"
123+
```
124+
:::
125+
126+
:::{tab-item} CrateDB on localhost
127+
:sync: localhost
128+
129+
```{code-block} shell
130+
http "localhost:4200/_sql?pretty" \
131+
stmt="SELECT 42.42;"
132+
```
133+
:::
134+
135+
::::
136+
137+
138+
(curl)=
139+
## curl
140+
141+
```{div}
142+
:style: "float: right"
143+
![image](https://github.com/crate/crate-clients-tools/assets/453543/318b0819-a0d4-4112-a320-23852263362c){w=240px}
144+
```
145+
146+
The venerable **curl** is the ubiquitous command line tool and library for transferring
147+
data with URLs. For more information, see the documentation about [curl].
148+
149+
This example combines it with [jq], a lightweight and flexible command-line JSON processor.
150+
151+
```{div}
152+
:style: "clear: both"
153+
```
154+
155+
::::{tab-set}
156+
157+
:::{tab-item} CrateDB and CrateDB Cloud
158+
:sync: server
159+
160+
```{code-block} shell
161+
echo '{"stmt": "SELECT 42.42;"}' \
162+
| curl "https://<username>:<password>@<hostname>:4200/_sql?pretty" --silent --data @- | jq
163+
```
164+
:::
165+
166+
:::{tab-item} CrateDB on localhost
167+
:sync: localhost
168+
169+
```{code-block} shell
170+
echo '{"stmt": "SELECT 42.42;"}' \
171+
| curl "localhost:4200/_sql?pretty" --silent --data @- | jq
172+
```
173+
:::
174+
175+
::::
176+
177+
178+
179+
[curl]: https://curl.se/
180+
[crash]: inv:crate-crash:*:label#index
181+
[HTTPie]: https://httpie.io/
182+
[jq]: https://jqlang.github.io/jq/
183+
[psql]: https://www.postgresql.org/docs/current/app-psql.html

‎docs/connect/configure.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
(connect-configure)=
2+
3+
# Configure
4+
5+
In order to connect to CrateDB, your application or driver needs to be
6+
configured with corresponding connection properties. Please note that different
7+
applications and drivers may obtain connection properties in different formats.
8+
9+
<style>
10+
/* Code blocks need to be slimmer */
11+
.driver-slim div.highlight-default {
12+
margin-top: 0.2em;
13+
}
14+
.driver-slim pre {
15+
padding: 0.4em;
16+
}
17+
.driver-slim p {
18+
margin-bottom: 0;
19+
}
20+
</style>
21+
22+
::::::{tab-set}
23+
24+
:::::{tab-item} CrateDB and CrateDB Cloud
25+
26+
::::{grid}
27+
:margin: 0
28+
:padding: 0
29+
30+
:::{grid-item}
31+
:columns: 4
32+
:margin: 0
33+
:padding: 0
34+
35+
**Connection properties**
36+
37+
:Host: `<cluster>`.cratedb.net
38+
:Port: 5432 (PostgreSQL) or<br>4200 (HTTP)
39+
:User: `<user>`
40+
:Pass: `<password>`
41+
42+
:::
43+
44+
:::{grid-item}
45+
:columns: 8
46+
:margin: 0
47+
:padding: 0
48+
:class: driver-slim
49+
50+
**Connection-string examples**
51+
<br><br>
52+
53+
**Native PostgreSQL, psql**
54+
```
55+
postgresql://<user>:<password>@<cluster>.cratedb.net:5432/doc
56+
```
57+
58+
**JDBC: PostgreSQL pgJDBC**
59+
```
60+
jdbc:postgresql://<user>:<password>@<cluster>.cratedb.net:5432/doc
61+
```
62+
63+
**JDBC: CrateDB JDBC, e.g. Apache Flink**
64+
```
65+
jdbc:crate://<user>:<password>@<cluster>.cratedb.net:5432/doc
66+
```
67+
68+
**HTTP: Admin UI, CLI, CrateDB drivers**
69+
```
70+
https://<user>:<password>@<cluster>.cratedb.net:4200/
71+
```
72+
73+
**SQLAlchemy**
74+
```
75+
crate://<user>:<password>@<cluster>.cratedb.net:4200/?schema=doc&ssl=true
76+
```
77+
78+
:::
79+
80+
::::
81+
82+
:::::
83+
84+
:::::{tab-item} CrateDB on localhost
85+
86+
::::{grid}
87+
:margin: 0
88+
:padding: 0
89+
90+
:::{grid-item}
91+
:columns: 4
92+
:margin: 0
93+
:padding: 0
94+
95+
**Connection properties**
96+
97+
:Host: localhost
98+
:Port: 5432 (PostgreSQL) or<br>4200 (HTTP)
99+
:User: `crate`
100+
:Pass: (empty)
101+
102+
:::
103+
104+
:::{grid-item}
105+
:columns: 8
106+
:margin: 0
107+
:padding: 0
108+
:class: driver-slim
109+
110+
**Connection-string examples**
111+
<br><br>
112+
113+
**Native PostgreSQL, psql**
114+
```
115+
postgresql://crate@localhost:5432/doc
116+
```
117+
118+
**JDBC: PostgreSQL pgJDBC**
119+
```
120+
jdbc:postgresql://crate@localhost:5432/doc
121+
```
122+
123+
**JDBC: CrateDB JDBC, e.g. Apache Flink**
124+
```
125+
jdbc:crate://<user>:<password>@localhost:5432/doc
126+
```
127+
128+
**HTTP: Admin UI, CLI, CrateDB drivers**
129+
```
130+
http://crate@localhost:4200/
131+
```
132+
133+
**SQLAlchemy**
134+
```
135+
crate://crate@localhost:4200/?schema=doc
136+
```
137+
138+
:::
139+
140+
::::
141+
:::::
142+
143+
::::::
144+
145+
146+
```{tip}
147+
- CrateDB's fixed catalog name is `crate`, the default schema name is `doc`.
148+
- CrateDB does not implement the notion of a database,
149+
however tables can be created in different [schemas].
150+
- When asked for a *database name*, specifying a schema name (any),
151+
or the fixed catalog name `crate` may be applicable.
152+
- If a database-/schema-name is omitted while connecting,
153+
the PostgreSQL drivers may default to the "username".
154+
- The predefined [superuser] on an unconfigured CrateDB cluster is
155+
called `crate`, defined without a password.
156+
- For authenticating properly, please learn about the available
157+
[authentication] options.
158+
```

0 commit comments

Comments
 (0)