From b34793a2f4dcdace5785aa92977b3d407edf9141 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Fri, 17 Oct 2025 23:35:29 +0200 Subject: [PATCH 1/6] Connect/Erlang: Add dedicated page --- docs/connect/erlang/index.md | 134 +++++++++++++++++++++++++++++++++++ docs/connect/index.md | 11 +++ 2 files changed, 145 insertions(+) create mode 100644 docs/connect/erlang/index.md diff --git a/docs/connect/erlang/index.md b/docs/connect/erlang/index.md new file mode 100644 index 00000000..c218f4db --- /dev/null +++ b/docs/connect/erlang/index.md @@ -0,0 +1,134 @@ +(connect-erlang)= + +# Erlang + +:::{div} sd-text-muted +Connect to CrateDB from Erlang applications. +::: + +## ODBC + +:::{rubric} About +::: + +Erlang includes an [ODBC application] out of the box that provides an +interface to communicate with relational SQL-databases, see also +[Erlang ODBC examples]. + +::::{todo} +Enable this include with the [ODBC patch](https://github.com/crate/cratedb-guide/pull/411). +```md +:::{include} _odbc-setup-widget.md +::: +``` +:::: + +:::{rubric} Synopsis +::: + +Before running the example, ensure the PostgreSQL ODBC driver is +installed on your system. + +`odbc_example.erl` +```erlang +-module(odbc_example). + +main(_) -> + odbc:start(), + {ok, Ref} = odbc:connect("Driver={PostgreSQL ODBC};Server=localhost;Port=5432;Uid=crate;Pwd=crate", []), + io:fwrite("~p~n", [odbc:sql_query(Ref, "SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3")]), + init:stop(). +``` + +:::{include} ../_cratedb.md +::: +```shell +escript odbc_example.erl +``` + +:::{rubric} CrateDB Cloud +::: + +For connecting to CrateDB Cloud, start the Erlang [SSL application], +add `sslmode=require`, and replace `Server`, `Uid`, and `Pwd` with +values matching your environment. + +`odbc_example.erl` +```erlang +-module(odbc_example). + +main(_) -> + ssl:start(), + odbc:start(), + {ok, Ref} = odbc:connect("Driver={PostgreSQL};Server=testcluster.cratedb.net;Port=5432;sslmode=require;Uid=admin;Pwd=password", []), + io:fwrite("~p~n", [odbc:sql_query(Ref, "SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3")]), + init:stop(). +``` + + +## epgsql + +[epgsql] is the designated Erlang PostgreSQL client library. + +`rebar.config` +```erlang +{deps, + [ + {epgsql, ".*", {git, "https://github.com/epgsql/epgsql.git", {tag, "4.8.0"}}} + ]}. +``` +`epgsql_example.erl` +```erlang +-module(epgsql_example). +-export([start/0]). + +start() -> + {ok, C} = epgsql:connect(#{ + host => "localhost", + username => "crate", + password => "crate", + database => "doc", + port => 5432, + timeout => 4000 + }), + {ok, _, Result} = epgsql:squery(C, "SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3"), + io:fwrite("~p~n", [Result]), + ok = epgsql:close(C), + init:stop(). +``` + +:::{include} ../_cratedb.md +::: +```shell +rebar3 compile +erlc epgsql_example.erl +rebar3 shell --eval 'epgsql_example:start().' +``` + +:::{rubric} CrateDB Cloud +::: + +For connecting to CrateDB Cloud, start the Erlang [SSL application] first, +use the `ssl` and `ssl_opts` arguments on `epgsql:connect`, and +replace username, password, and hostname with values matching +your environment. +```erlang +start() -> + ssl:start(), + {ok, C} = epgsql:connect(#{ + host => "testcluster.cratedb.net", + username => "admin", + password => "password", + database => "doc", + port => 5432, + ssl => true, + ssl_opts => [{verify, verify_none}], + timeout => 4000 + }), +``` + + +[epgsql]: https://github.com/epgsql/epgsql +[Erlang ODBC examples]: https://www.erlang.org/doc/apps/odbc/getting_started.html +[ODBC application]: https://www.erlang.org/docs/28/apps/odbc/odbc.html +[SSL application]: https://www.erlang.org/docs/28/apps/ssl/ssl_app.html diff --git a/docs/connect/index.md b/docs/connect/index.md index 265c8e26..42353bc6 100644 --- a/docs/connect/index.md +++ b/docs/connect/index.md @@ -64,6 +64,7 @@ Any (ODBC) :::: ::::{grid-item-card} +<<<<<<< HEAD :link: connect-elixir :link-type: ref :class-body: sd-fs-1 sd-text-center @@ -74,6 +75,15 @@ Any (ODBC) ``` +++ Elixir +======= +:link: connect-erlang +:link-type: ref +:class-body: sd-fs-1 sd-text-center +:class-footer: sd-fs-5 sd-font-weight-bold +{fab}`erlang` ++++ +Erlang +>>>>>>> 11da959b (Connect/Erlang: Add dedicated page) :::: ::::{grid-item-card} @@ -229,6 +239,7 @@ application :hidden: elixir/index +erlang/index go/index java/index javascript From 859fa3a5ec48accd7631c5cfbcf8be60c16c748a Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Mon, 27 Oct 2025 21:35:35 +0100 Subject: [PATCH 2/6] Connect/Erlang: Each item on a separate page --- docs/connect/erlang/epgsql.md | 76 ++++++++++++++++++++ docs/connect/erlang/index.md | 128 +--------------------------------- docs/connect/erlang/odbc.md | 68 ++++++++++++++++++ 3 files changed, 147 insertions(+), 125 deletions(-) create mode 100644 docs/connect/erlang/epgsql.md create mode 100644 docs/connect/erlang/odbc.md diff --git a/docs/connect/erlang/epgsql.md b/docs/connect/erlang/epgsql.md new file mode 100644 index 00000000..a0d48a26 --- /dev/null +++ b/docs/connect/erlang/epgsql.md @@ -0,0 +1,76 @@ +(erlang-epgsql)= + +# Erlang epgsql + +:::{div} sd-text-muted +Connect to CrateDB from Erlang using epgsql. +::: + +:::{rubric} About +::: + +[epgsql] is the designated Erlang PostgreSQL client library. + +:::{rubric} Synopsis +::: + +`rebar.config` +```erlang +{deps, + [ + {epgsql, ".*", {git, "https://github.com/epgsql/epgsql.git", {tag, "4.8.0"}}} + ]}. +``` +`epgsql_example.erl` +```erlang +-module(epgsql_example). +-export([start/0]). + +start() -> + {ok, C} = epgsql:connect(#{ + host => "localhost", + username => "crate", + password => "crate", + database => "doc", + port => 5432, + timeout => 4000 + }), + {ok, _, Result} = epgsql:squery(C, "SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3"), + io:fwrite("~p~n", [Result]), + ok = epgsql:close(C), + init:stop(). +``` + +:::{include} ../_cratedb.md +::: +```shell +rebar3 compile +erlc epgsql_example.erl +rebar3 shell --eval 'epgsql_example:start().' +``` + +:::{rubric} CrateDB Cloud +::: + +For connecting to CrateDB Cloud, start the Erlang [SSL application] first, +use the `ssl` and `ssl_opts` arguments on `epgsql:connect`, and +replace username, password, and hostname with values matching +your environment. +```erlang +start() -> + ssl:start(), + {ok, C} = epgsql:connect(#{ + host => "testcluster.cratedb.net", + username => "admin", + password => "password", + database => "doc", + port => 5432, + ssl => true, + ssl_opts => [{verify, verify_none}], + timeout => 4000 + }), +``` + + +[epgsql]: https://github.com/epgsql/epgsql +[SSL application]: https://www.erlang.org/docs/28/apps/ssl/ssl_app.html diff --git a/docs/connect/erlang/index.md b/docs/connect/erlang/index.md index c218f4db..8555dc2e 100644 --- a/docs/connect/erlang/index.md +++ b/docs/connect/erlang/index.md @@ -6,129 +6,7 @@ Connect to CrateDB from Erlang applications. ::: -## ODBC - -:::{rubric} About -::: - -Erlang includes an [ODBC application] out of the box that provides an -interface to communicate with relational SQL-databases, see also -[Erlang ODBC examples]. - -::::{todo} -Enable this include with the [ODBC patch](https://github.com/crate/cratedb-guide/pull/411). -```md -:::{include} _odbc-setup-widget.md -::: -``` -:::: - -:::{rubric} Synopsis -::: - -Before running the example, ensure the PostgreSQL ODBC driver is -installed on your system. - -`odbc_example.erl` -```erlang --module(odbc_example). - -main(_) -> - odbc:start(), - {ok, Ref} = odbc:connect("Driver={PostgreSQL ODBC};Server=localhost;Port=5432;Uid=crate;Pwd=crate", []), - io:fwrite("~p~n", [odbc:sql_query(Ref, "SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3")]), - init:stop(). -``` - -:::{include} ../_cratedb.md -::: -```shell -escript odbc_example.erl -``` - -:::{rubric} CrateDB Cloud -::: - -For connecting to CrateDB Cloud, start the Erlang [SSL application], -add `sslmode=require`, and replace `Server`, `Uid`, and `Pwd` with -values matching your environment. - -`odbc_example.erl` -```erlang --module(odbc_example). - -main(_) -> - ssl:start(), - odbc:start(), - {ok, Ref} = odbc:connect("Driver={PostgreSQL};Server=testcluster.cratedb.net;Port=5432;sslmode=require;Uid=admin;Pwd=password", []), - io:fwrite("~p~n", [odbc:sql_query(Ref, "SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3")]), - init:stop(). -``` - - -## epgsql - -[epgsql] is the designated Erlang PostgreSQL client library. - -`rebar.config` -```erlang -{deps, - [ - {epgsql, ".*", {git, "https://github.com/epgsql/epgsql.git", {tag, "4.8.0"}}} - ]}. -``` -`epgsql_example.erl` -```erlang --module(epgsql_example). --export([start/0]). - -start() -> - {ok, C} = epgsql:connect(#{ - host => "localhost", - username => "crate", - password => "crate", - database => "doc", - port => 5432, - timeout => 4000 - }), - {ok, _, Result} = epgsql:squery(C, "SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3"), - io:fwrite("~p~n", [Result]), - ok = epgsql:close(C), - init:stop(). -``` - -:::{include} ../_cratedb.md -::: -```shell -rebar3 compile -erlc epgsql_example.erl -rebar3 shell --eval 'epgsql_example:start().' -``` - -:::{rubric} CrateDB Cloud +:::{toctree} +odbc +epgsql ::: - -For connecting to CrateDB Cloud, start the Erlang [SSL application] first, -use the `ssl` and `ssl_opts` arguments on `epgsql:connect`, and -replace username, password, and hostname with values matching -your environment. -```erlang -start() -> - ssl:start(), - {ok, C} = epgsql:connect(#{ - host => "testcluster.cratedb.net", - username => "admin", - password => "password", - database => "doc", - port => 5432, - ssl => true, - ssl_opts => [{verify, verify_none}], - timeout => 4000 - }), -``` - - -[epgsql]: https://github.com/epgsql/epgsql -[Erlang ODBC examples]: https://www.erlang.org/doc/apps/odbc/getting_started.html -[ODBC application]: https://www.erlang.org/docs/28/apps/odbc/odbc.html -[SSL application]: https://www.erlang.org/docs/28/apps/ssl/ssl_app.html diff --git a/docs/connect/erlang/odbc.md b/docs/connect/erlang/odbc.md new file mode 100644 index 00000000..83aa51b4 --- /dev/null +++ b/docs/connect/erlang/odbc.md @@ -0,0 +1,68 @@ +(erlang-odbc)= + +# Erlang ODBC + +:::{div} sd-text-muted +Connect to CrateDB from Erlang using ODBC. +::: + +:::{rubric} About +::: + +Erlang includes an [ODBC application] out of the box that provides an +interface to communicate with relational SQL-databases, see also +[Erlang ODBC examples]. + +::::{todo} +Enable this include with the [ODBC patch](https://github.com/crate/cratedb-guide/pull/411). +```md +:::{include} _odbc-setup-widget.md +::: +``` +:::: + +:::{rubric} Synopsis +::: + +Before running the example, ensure the PostgreSQL ODBC driver is +installed on your system. + +`odbc_example.erl` +```erlang +-module(odbc_example). + +main(_) -> + odbc:start(), + {ok, Ref} = odbc:connect("Driver={PostgreSQL ODBC};Server=localhost;Port=5432;Uid=crate;Pwd=crate", []), + io:fwrite("~p~n", [odbc:sql_query(Ref, "SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3")]), + init:stop(). +``` + +:::{include} ../_cratedb.md +::: +```shell +escript odbc_example.erl +``` + +:::{rubric} CrateDB Cloud +::: + +For connecting to CrateDB Cloud, start the Erlang [SSL application], +add `sslmode=require`, and replace `Server`, `Uid`, and `Pwd` with +values matching your environment. + +`odbc_example.erl` +```erlang +-module(odbc_example). + +main(_) -> + ssl:start(), + odbc:start(), + {ok, Ref} = odbc:connect("Driver={PostgreSQL};Server=testcluster.cratedb.net;Port=5432;sslmode=require;Uid=admin;Pwd=password", []), + io:fwrite("~p~n", [odbc:sql_query(Ref, "SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3")]), + init:stop(). +``` + + +[Erlang ODBC examples]: https://www.erlang.org/doc/apps/odbc/getting_started.html +[ODBC application]: https://www.erlang.org/docs/28/apps/odbc/odbc.html From 3e30d05425c09e809dc15ea08a5afbd25256bb65 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Thu, 30 Oct 2025 12:08:55 +0100 Subject: [PATCH 3/6] Connect/Erlang: Copy editing --- docs/connect/erlang/epgsql.md | 21 +++++++++++++-------- docs/connect/erlang/odbc.md | 18 ++++++++++++------ 2 files changed, 25 insertions(+), 14 deletions(-) diff --git a/docs/connect/erlang/epgsql.md b/docs/connect/erlang/epgsql.md index a0d48a26..a5415555 100644 --- a/docs/connect/erlang/epgsql.md +++ b/docs/connect/erlang/epgsql.md @@ -41,14 +41,6 @@ start() -> init:stop(). ``` -:::{include} ../_cratedb.md -::: -```shell -rebar3 compile -erlc epgsql_example.erl -rebar3 shell --eval 'epgsql_example:start().' -``` - :::{rubric} CrateDB Cloud ::: @@ -71,6 +63,19 @@ start() -> }), ``` +:::{rubric} Example +::: + +Create the files `rebar.config` and `epgsql_example.erl` including the synopsis code shared above. + +:::{include} ../_cratedb.md +::: +```shell +rebar3 compile +erlc epgsql_example.erl +rebar3 shell --eval 'epgsql_example:start().' +``` + [epgsql]: https://github.com/epgsql/epgsql [SSL application]: https://www.erlang.org/docs/28/apps/ssl/ssl_app.html diff --git a/docs/connect/erlang/odbc.md b/docs/connect/erlang/odbc.md index 83aa51b4..6a06b21e 100644 --- a/docs/connect/erlang/odbc.md +++ b/docs/connect/erlang/odbc.md @@ -38,12 +38,6 @@ main(_) -> init:stop(). ``` -:::{include} ../_cratedb.md -::: -```shell -escript odbc_example.erl -``` - :::{rubric} CrateDB Cloud ::: @@ -63,6 +57,18 @@ main(_) -> init:stop(). ``` +:::{rubric} Example +::: + +Create the file `odbc_example.erl` including the synopsis code shared above. + +:::{include} ../_cratedb.md +::: +```shell +escript odbc_example.erl +``` + [Erlang ODBC examples]: https://www.erlang.org/doc/apps/odbc/getting_started.html [ODBC application]: https://www.erlang.org/docs/28/apps/odbc/odbc.html +[SSL application]: https://www.erlang.org/docs/28/apps/ssl/ssl_app.html From a49df3df535733f5aa5a49b05404a80709cc91e3 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Fri, 31 Oct 2025 23:51:16 +0100 Subject: [PATCH 4/6] Connect/Erlang: Fix card on index page (merge conflict unresolved) --- docs/connect/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/connect/index.md b/docs/connect/index.md index 42353bc6..094ca1e9 100644 --- a/docs/connect/index.md +++ b/docs/connect/index.md @@ -64,7 +64,6 @@ Any (ODBC) :::: ::::{grid-item-card} -<<<<<<< HEAD :link: connect-elixir :link-type: ref :class-body: sd-fs-1 sd-text-center @@ -75,7 +74,9 @@ Any (ODBC) ``` +++ Elixir -======= +:::: + +::::{grid-item-card} :link: connect-erlang :link-type: ref :class-body: sd-fs-1 sd-text-center @@ -83,7 +84,6 @@ Elixir {fab}`erlang` +++ Erlang ->>>>>>> 11da959b (Connect/Erlang: Add dedicated page) :::: ::::{grid-item-card} From b3a5468f242064f3e8d3f906b394658a21dee3c5 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Fri, 31 Oct 2025 23:55:18 +0100 Subject: [PATCH 5/6] Connect/Erlang/ODBC: Include ODBC installation instructions --- docs/connect/erlang/odbc.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/connect/erlang/odbc.md b/docs/connect/erlang/odbc.md index 6a06b21e..03620396 100644 --- a/docs/connect/erlang/odbc.md +++ b/docs/connect/erlang/odbc.md @@ -13,13 +13,11 @@ Erlang includes an [ODBC application] out of the box that provides an interface to communicate with relational SQL-databases, see also [Erlang ODBC examples]. -::::{todo} -Enable this include with the [ODBC patch](https://github.com/crate/cratedb-guide/pull/411). -```md -:::{include} _odbc-setup-widget.md +:::{rubric} Install +::: + +:::{include} ../odbc/install.md ::: -``` -:::: :::{rubric} Synopsis ::: @@ -33,7 +31,7 @@ installed on your system. main(_) -> odbc:start(), - {ok, Ref} = odbc:connect("Driver={PostgreSQL ODBC};Server=localhost;Port=5432;Uid=crate;Pwd=crate", []), + {ok, Ref} = odbc:connect("Driver={PostgreSQL Unicode};Server=localhost;Port=5432;Uid=crate;Pwd=crate", []), io:fwrite("~p~n", [odbc:sql_query(Ref, "SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3")]), init:stop(). ``` @@ -52,7 +50,7 @@ values matching your environment. main(_) -> ssl:start(), odbc:start(), - {ok, Ref} = odbc:connect("Driver={PostgreSQL};Server=testcluster.cratedb.net;Port=5432;sslmode=require;Uid=admin;Pwd=password", []), + {ok, Ref} = odbc:connect("Driver={PostgreSQL Unicode};Server=testcluster.cratedb.net;Port=5432;sslmode=require;Uid=admin;Pwd=password", []), io:fwrite("~p~n", [odbc:sql_query(Ref, "SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3")]), init:stop(). ``` From 63984499c16fb9bda8d5125cd476036006af59e5 Mon Sep 17 00:00:00 2001 From: Marios Trivyzas <5058131+matriv@users.noreply.github.com> Date: Mon, 3 Nov 2025 12:01:23 +0100 Subject: [PATCH 6/6] Connect/Erlang/epgsql: Wording adjustments for CrateDB Cloud option --- docs/connect/erlang/epgsql.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/connect/erlang/epgsql.md b/docs/connect/erlang/epgsql.md index a5415555..dc6d6f07 100644 --- a/docs/connect/erlang/epgsql.md +++ b/docs/connect/erlang/epgsql.md @@ -41,13 +41,15 @@ start() -> init:stop(). ``` -:::{rubric} CrateDB Cloud +:::{rubric} SSL connection ::: -For connecting to CrateDB Cloud, start the Erlang [SSL application] first, +Start the Erlang [SSL application] first, use the `ssl` and `ssl_opts` arguments on `epgsql:connect`, and replace username, password, and hostname with values matching your environment. + +Also use this variant to connect to CrateDB Cloud. ```erlang start() -> ssl:start(),