hasura/graphql-engine
1
0
Fork 0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-12-14 08:02:15 +03:00
Code Issues Projects Releases Wiki Activity

NDAT-164 CockroachDB 'Getting Started' Docs

Browse Source 
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/6386
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Rob Dominguez <24390149+robertjdominguez@users.noreply.github.com>
GitOrigin-RevId: 92b7fce2e63c0baab84271d74116a27187dfa270
This commit is contained in:
Abby Sassel 2022-10-20 18:06:23 +01:00 committed by hasura-bot
parent 6289b06453
commit 639ce90c4c
17 changed files with 541 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
docs/docs/databases/index.mdx
View File

@ -27,12 +27,14 @@ Hasura GraphQL engine supports:
- [Postgres & Postgres compatible flavours](/databases/postgres/index.mdx)
- [MS SQL Server](/databases/ms-sql-server/index.mdx)
- [Citus / Hyperscale](/databases/postgres/citus-hyperscale-postgres/index.mdx)
- [CockroachDB](/databases/postgres/cockroachdb/index.mdx)
- [BigQuery](/databases/bigquery/index.mdx)
- **MySQL** (in preview) - See the [preview guide](/guides/mysql-preview.mdx)
:::tip Tip
Although it is safe to use Hasura with a serverless database, caution must be maintained because some functionalities - such as subscriptions or event triggers - will force a serverless database to be always on.
Although it is safe to use Hasura with a serverless database, caution must be maintained because some functionalities -
such as subscriptions or event triggers - will force a serverless database to be always on.
:::
@ -49,60 +51,60 @@ Each ✅ below links **directly** to the feature within a particular type of dat
#### Schema
| | Postgres | Citus | SQL Server | BigQuery |
| -------------------- | ----------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------- |
| Table Relationships | [✅](/schema/postgres/table-relationships/index.mdx) | [✅](/schema/postgres/table-relationships/index.mdx) | [✅](/schema/ms-sql-server/table-relationships/index.mdx) | [✅](/schema/bigquery/table-relationships/index.mdx) |
| Remote Relationships | [✅](/schema/postgres/remote-relationships/index.mdx) | [✅](/schema/postgres/remote-relationships/index.mdx) | [✅](/schema/ms-sql-server/remote-relationships/index.mdx) | [✅](/schema/bigquery/index.mdx) |
| Views | [✅](/schema/postgres/views.mdx) | [✅](/schema/postgres/views.mdx) | [✅](/schema/ms-sql-server/views.mdx) | ❌ |
| Custom Functions | [✅](/schema/postgres/custom-functions.mdx) | [✅](/schema/postgres/custom-functions.mdx) | ❌ | ❌ |
| Enums | [✅](/schema/postgres/enums.mdx) | [✅](/schema/postgres/enums.mdx) | ❌ | ❌ |
| Computed Fields | [✅](/schema/postgres/computed-fields.mdx) | [✅](/schema/postgres/computed-fields.mdx) | ❌ | [✅](/schema/bigquery/computed-fields.mdx) |
| Data Validations | [✅](/schema/postgres/data-validations.mdx) | [✅](/schema/postgres/data-validations.mdx) | ✅ | [✅](/schema/bigquery/data-validations.mdx) |
| Relay Schema | [✅](/schema/postgres/relay-schema.mdx) | [✅](/schema/postgres/relay-schema.mdx) | ❌ | ❌ |
| Naming Conventions | [✅](/schema/postgres/naming-convention.mdx) | ❌ | ❌ | ❌ |
| | Postgres | Citus | SQL Server | BigQuery | CockroachDB |
| -------------------- | ----------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------- |
| Table Relationships | [✅](/schema/postgres/table-relationships/index.mdx) | [✅](/schema/postgres/table-relationships/index.mdx) | [✅](/schema/ms-sql-server/table-relationships/index.mdx) | [✅](/schema/bigquery/table-relationships/index.mdx) | [✅](/schema/postgres/table-relationships/index.mdx) |
| Remote Relationships | [✅](/schema/postgres/remote-relationships/index.mdx) | [✅](/schema/postgres/remote-relationships/index.mdx) | [✅](/schema/ms-sql-server/remote-relationships/index.mdx) | [✅](/schema/bigquery/index.mdx) | ❌ |
| Views | [✅](/schema/postgres/views.mdx) | [✅](/schema/postgres/views.mdx) | [✅](/schema/ms-sql-server/views.mdx) | ❌ | [✅](/schema/postgres/views.mdx) |
| Custom Functions | [✅](/schema/postgres/custom-functions.mdx) | [✅](/schema/postgres/custom-functions.mdx) | ❌ | ❌ | ❌ |
| Enums | [✅](/schema/postgres/enums.mdx) | [✅](/schema/postgres/enums.mdx) | ❌ | ❌ | ❌ |
| Computed Fields | [✅](/schema/postgres/computed-fields.mdx) | [✅](/schema/postgres/computed-fields.mdx) | ❌ | [✅](/schema/bigquery/computed-fields.mdx) | ❌ |
| Data Validations | [✅](/schema/postgres/data-validations.mdx) | [✅](/schema/postgres/data-validations.mdx) | ✅ | [✅](/schema/bigquery/data-validations.mdx) | [✅](/schema/postgres/data-validations.mdx) |
| Relay Schema | [✅](/schema/postgres/relay-schema.mdx) | [✅](/schema/postgres/relay-schema.mdx) | ❌ | ❌ | ❌ |
| Naming Conventions | [✅](/schema/postgres/naming-convention.mdx) | ❌ | ❌ | ❌ | [✅](/schema/postgres/naming-convention.mdx) |
#### Queries
| | Postgres | Citus | SQL Server | BigQuery |
| ------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------- |
| Simple | [✅](/queries/postgres/simple-object-queries.mdx) | [✅](/queries/postgres/simple-object-queries.mdx) | [✅](/queries/ms-sql-server/simple-object-queries.mdx) | [✅](/queries/bigquery/simple-object-queries.mdx) |
| Nested Object | [✅](/queries/postgres/nested-object-queries.mdx) | [✅](/queries/postgres/nested-object-queries.mdx) | [✅](/queries/ms-sql-server/nested-object-queries.mdx) | [✅](/queries/bigquery/nested-object-queries.mdx) |
| Aggregation | [✅](/queries/postgres/aggregation-queries.mdx) | [✅](/queries/postgres/aggregation-queries.mdx) | [✅](/queries/ms-sql-server/aggregation-queries.mdx) | [✅](/queries/bigquery/aggregation-queries.mdx) |
| Filter / Search | [✅](/queries/postgres/query-filters.mdx) | [✅](/queries/postgres/query-filters.mdx) | [✅](/queries/ms-sql-server/query-filters.mdx) | [✅](/queries/bigquery/query-filters.mdx) |
| Sort | [✅](/queries/postgres/sorting.mdx) | [✅](/queries/postgres/sorting.mdx) | [✅](/queries/ms-sql-server/sorting.mdx) | [✅](/queries/bigquery/index.mdx) |
| Distinct | [✅](/queries/postgres/distinct-queries.mdx) | [✅](/queries/postgres/distinct-queries.mdx) | [✅](/queries/ms-sql-server/index.mdx) | [✅](/queries/bigquery/index.mdx) |
| Paginate | [✅](/queries/postgres/pagination.mdx) | [✅](/queries/postgres/pagination.mdx) | [✅](/queries/ms-sql-server/pagination.mdx) | [✅](/queries/bigquery/index.mdx) |
| Multiple Arguments | [✅](/queries/postgres/multiple-arguments.mdx) | [✅](/queries/postgres/multiple-arguments.mdx) | [✅](/queries/ms-sql-server/multiple-arguments.mdx) | [✅](/queries/bigquery/index.mdx) |
| Multiple Queries | [✅](/queries/postgres/multiple-queries.mdx) | [✅](/queries/postgres/multiple-queries.mdx) | [✅](/queries/ms-sql-server/multiple-queries.mdx) | [✅](/queries/bigquery/index.mdx) |
| Variables / Aliases / Fragments | [✅](/queries/postgres/variables-aliases-fragments-directives.mdx) | [✅](/queries/postgres/variables-aliases-fragments-directives.mdx) | [✅](/queries/ms-sql-server/variables-aliases-fragments-directives.mdx) | [✅](/queries/bigquery/index.mdx) |
| | Postgres | Citus | SQL Server | BigQuery | CockroachDB |
| ------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
| Simple | [✅](/queries/postgres/simple-object-queries.mdx) | [✅](/queries/postgres/simple-object-queries.mdx) | [✅](/queries/ms-sql-server/simple-object-queries.mdx) | [✅](/queries/bigquery/simple-object-queries.mdx) | [✅](/queries/postgres/simple-object-queries.mdx) |
| Nested Object | [✅](/queries/postgres/nested-object-queries.mdx) | [✅](/queries/postgres/nested-object-queries.mdx) | [✅](/queries/ms-sql-server/nested-object-queries.mdx) | [✅](/queries/bigquery/nested-object-queries.mdx) | [✅](/queries/postgres/nested-object-queries.mdx) |
| Aggregation | [✅](/queries/postgres/aggregation-queries.mdx) | [✅](/queries/postgres/aggregation-queries.mdx) | [✅](/queries/ms-sql-server/aggregation-queries.mdx) | [✅](/queries/bigquery/aggregation-queries.mdx) | [✅](/queries/postgres/aggregation-queries.mdx) |
| Filter / Search | [✅](/queries/postgres/query-filters.mdx) | [✅](/queries/postgres/query-filters.mdx) | [✅](/queries/ms-sql-server/query-filters.mdx) | [✅](/queries/bigquery/query-filters.mdx) | [✅](/queries/postgres/query-filters.mdx) |
| Sort | [✅](/queries/postgres/sorting.mdx) | [✅](/queries/postgres/sorting.mdx) | [✅](/queries/ms-sql-server/sorting.mdx) | [✅](/queries/bigquery/index.mdx) | [✅](/queries/postgres/sorting.mdx) |
| Distinct | [✅](/queries/postgres/distinct-queries.mdx) | [✅](/queries/postgres/distinct-queries.mdx) | [✅](/queries/ms-sql-server/index.mdx) | [✅](/queries/bigquery/index.mdx) | [✅](/queries/postgres/distinct-queries.mdx) |
| Paginate | [✅](/queries/postgres/pagination.mdx) | [✅](/queries/postgres/pagination.mdx) | [✅](/queries/ms-sql-server/pagination.mdx) | [✅](/queries/bigquery/index.mdx) | [✅](/queries/postgres/pagination.mdx) |
| Multiple Arguments | [✅](/queries/postgres/multiple-arguments.mdx) | [✅](/queries/postgres/multiple-arguments.mdx) | [✅](/queries/ms-sql-server/multiple-arguments.mdx) | [✅](/queries/bigquery/index.mdx) | [✅](/queries/postgres/multiple-arguments.mdx) |
| Multiple Queries | [✅](/queries/postgres/multiple-queries.mdx) | [✅](/queries/postgres/multiple-queries.mdx) | [✅](/queries/ms-sql-server/multiple-queries.mdx) | [✅](/queries/bigquery/index.mdx) | [✅](/queries/postgres/multiple-queries.mdx) |
| Variables / Aliases / Fragments | [✅](/queries/postgres/variables-aliases-fragments-directives.mdx) | [✅](/queries/postgres/variables-aliases-fragments-directives.mdx) | [✅](/queries/ms-sql-server/variables-aliases-fragments-directives.mdx) | [✅](/queries/bigquery/index.mdx) | [✅](/queries/postgres/variables-aliases-fragments-directives.mdx) |
#### Mutations
| | Postgres | Citus | SQL Server | BigQuery |
| -------------------- | ------------------------------------------------ | ------------------------------------------------ | ----------------------------------------- | -------- |
| Insert | [✅](/mutations/postgres/insert.mdx) | [✅](/mutations/postgres/insert.mdx) | [✅](/mutations/ms-sql-server/insert.mdx) | ❌ |
| Upsert | [✅](/mutations/postgres/upsert.mdx) | [✅](/mutations/postgres/upsert.mdx) | [✅](/mutations/ms-sql-server/upsert.mdx) | ❌ |
| Update | [✅](/mutations/postgres/update.mdx) | [✅](/mutations/postgres/update.mdx) | [✅](/mutations/ms-sql-server/update.mdx) | ❌ |
| Delete | [✅](/mutations/postgres/delete.mdx) | [✅](/mutations/postgres/delete.mdx) | [✅](/mutations/ms-sql-server/delete.mdx) | ❌ |
| Multiple per Request | [✅](/mutations/postgres/multiple-mutations.mdx) | [✅](/mutations/postgres/multiple-mutations.mdx) | ❌ | ❌ |
| | Postgres | Citus | SQL Server | BigQuery | CockroachDB |
| -------------------- | ------------------------------------------------ | ------------------------------------------------ | ----------------------------------------- | -------- | ------------------------------------------------ |
| Insert | [✅](/mutations/postgres/insert.mdx) | [✅](/mutations/postgres/insert.mdx) | [✅](/mutations/ms-sql-server/insert.mdx) | ❌ | [✅](/mutations/postgres/insert.mdx) |
| Upsert | [✅](/mutations/postgres/upsert.mdx) | [✅](/mutations/postgres/upsert.mdx) | [✅](/mutations/ms-sql-server/upsert.mdx) | ❌ | [✅](/mutations/postgres/upsert.mdx) |
| Update | [✅](/mutations/postgres/update.mdx) | [✅](/mutations/postgres/update.mdx) | [✅](/mutations/ms-sql-server/update.mdx) | ❌ | [✅](/mutations/postgres/update.mdx) |
| Delete | [✅](/mutations/postgres/delete.mdx) | [✅](/mutations/postgres/delete.mdx) | [✅](/mutations/ms-sql-server/delete.mdx) | ❌ | [✅](/mutations/postgres/delete.mdx) |
| Multiple per Request | [✅](/mutations/postgres/multiple-mutations.mdx) | [✅](/mutations/postgres/multiple-mutations.mdx) | ❌ | ❌ | [✅](/mutations/postgres/multiple-mutations.mdx) |
#### Subscriptions
| | Postgres | Citus | SQL Server | BigQuery |
| ----------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------- |
| Value of Field | [✅](/subscriptions/postgres/livequery/use-cases.mdx#pg-subscribe-field) | [✅](/subscriptions/postgres/livequery/use-cases.mdx#pg-subscribe-field) | [✅](/subscriptions/ms-sql-server/use-cases.mdx#pg-subscribe-field) | ❌ |
| Updates to Rows | [✅](/subscriptions/postgres/livequery/use-cases.mdx#pg-subscribe-table) | [✅](/subscriptions/postgres/livequery/use-cases.mdx#pg-subscribe-table) | ❌ | ❌ |
| Value of Derived Field | [✅](/subscriptions/postgres/livequery/use-cases.mdx#pg-subscribe-derived) | [✅](/subscriptions/postgres/livequery/use-cases.mdx#pg-subscribe-derived) | [✅](/subscriptions/ms-sql-server/use-cases.mdx#pg-subscribe-derived) | ❌ |
| Streaming Subscriptions | [✅](/subscriptions/postgres/streaming/index.mdx) | ❌ | ❌ | ❌ |
| | Postgres | Citus | SQL Server | BigQuery | CockroachDB |
| ----------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------- | ----------- |
| Value of Field | [✅](/subscriptions/postgres/livequery/use-cases.mdx#pg-subscribe-field) | [✅](/subscriptions/postgres/livequery/use-cases.mdx#pg-subscribe-field) | [✅](/subscriptions/ms-sql-server/use-cases.mdx#pg-subscribe-field) | ❌ | ❌ |
| Updates to Rows | [✅](/subscriptions/postgres/livequery/use-cases.mdx#pg-subscribe-table) | [✅](/subscriptions/postgres/livequery/use-cases.mdx#pg-subscribe-table) | ❌ | ❌ | ❌ |
| Value of Derived Field | [✅](/subscriptions/postgres/livequery/use-cases.mdx#pg-subscribe-derived) | [✅](/subscriptions/postgres/livequery/use-cases.mdx#pg-subscribe-derived) | [✅](/subscriptions/ms-sql-server/use-cases.mdx#pg-subscribe-derived) | ❌ | ❌ |
| Streaming Subscriptions | [✅](/subscriptions/postgres/streaming/index.mdx) | ❌ | ❌ | ❌ | ❌ |
#### Event Triggers
| | Postgres | Citus | SQL Server | BigQuery |
| ------ | ------------------------------- | ----- | ------------------------------- | -------- |
| INSERT | [✅](/event-triggers/index.mdx) | ❌ | [✅](/event-triggers/index.mdx) | ❌ |
| UPDATE | [✅](/event-triggers/index.mdx) | ❌ | [✅](/event-triggers/index.mdx) | ❌ |
| DELETE | [✅](/event-triggers/index.mdx) | ❌ | [✅](/event-triggers/index.mdx) | ❌ |
| MANUAL | [✅](/event-triggers/index.mdx) | ❌ | [✅](/event-triggers/index.mdx) | ❌ |
| | Postgres | Citus | SQL Server | BigQuery | CockroachDB |
| ------ | ------------------------------- | ----- | ------------------------------- | -------- | ----------- |
| INSERT | [✅](/event-triggers/index.mdx) | ❌ | [✅](/event-triggers/index.mdx) | ❌ | ❌ |
| UPDATE | [✅](/event-triggers/index.mdx) | ❌ | [✅](/event-triggers/index.mdx) | ❌ | ❌ |
| DELETE | [✅](/event-triggers/index.mdx) | ❌ | [✅](/event-triggers/index.mdx) | ❌ | ❌ |
| MANUAL | [✅](/event-triggers/index.mdx) | ❌ | [✅](/event-triggers/index.mdx) | ❌ | ❌ |
:::info Additional Resources

2
docs/docs/databases/postgres/citus-hyperscale-postgres/index.mdx
View File

@ -13,7 +13,7 @@ slug: index
## Introduction
[Citus](https://www.citusdata.com/) is a is an open source extension that transforms Postgres into a distributed
[Citus](https://www.citusdata.com/) is an open source extension that transforms Postgres into a distributed
database. As it is a Postgres extension, all of Postgres' features, tooling & ecosystem can be leveraged.
<!--

4
docs/docs/databases/postgres/cockroachdb/_category_.json Normal file
View File

@ -0,0 +1,4 @@
{
"label": "CockroachDB",
"position": 5
}

4
docs/docs/databases/postgres/cockroachdb/getting-started/_category_.json Normal file
View File

@ -0,0 +1,4 @@
{
"label": "Getting started",
"position": 1
}

92
docs/docs/databases/postgres/cockroachdb/getting-started/cloud.mdx Normal file
View File

@ -0,0 +1,92 @@
---
sidebar_label: Hasura Cloud
sidebar_position: 1
description: Hasura Cloud for CockroachDB
keywords:
- hasura
- docs
- databases
- cockroachdb
- hasura-cloud
---
import Thumbnail from '@site/src/components/Thumbnail';
# Get Started with Hasura Cloud & CockroachDB
## Try it out
### Step 1: Create an account on Hasura Cloud and create a new Hasura Project
Navigate to
[cloud.hasura.io](https://cloud.hasura.io/signup/?pg=docs&plcmt=body&cta=navigate-to-cloud-hasura-io&tech=default), and
create a new Hasura Cloud account.
Once you create a project on Hasura Cloud, hit the "Launch Console" button to open the Hasura Console for your project.
<Thumbnail src='/img/getting-started/create-project.png' alt='Connect new or existing database' width='600px' />
### Step 2: Add your CockroachDB database as a source to Hasura
In the `Data > Data Manager > Connect Existing Database` section on the Console, select `CockroachDB` from the
`Data Source Driver` dropdown and add the connection string directly or through an environment variable. As CockroachDB
speaks the same protocol as Postgres, the connection string will start with `postgres://`, i.e, there is no difference
between CockroachDB's connection strings and Postgres’s connection strings.
<Thumbnail src='/img/databases/cockroachdb-postgres/1-add-source.png' alt='Add source' width='1100px' />
Once you add the database, you'll see your database pop up on the sidebar.
### Step 3: Track existing tables or create new tables
If you have existing tables, head to the database page by clicking on the database name on the sidebar. You should see a
list of tables.
<!--
.. thumbnail:: /img/databases/ms-sql-server/3-manage-mydb.png
:alt: Manage my-db
:width: 1000px
-->
Track tables selectively or all of them so that Hasura can introspect the tables and create the corresponding GraphQL
schema.
<Thumbnail src='/img/databases/cockroachdb-postgres/4-track-tables.png' alt='Track tables' width='1100px' />
If you have foreign keys, you'll also see suggested relationships. Again, you can choose to track them selectively or
all at once.
<Thumbnail
src='/img/databases/cockroachdb-postgres/5-track-rels.png'
alt='Track foreign-key relationships'
width='1100px'
/>
If you don't have existing tables, go ahead and add new tables and data and try out some queries, just like with a
regular Postgres database.
<Thumbnail src='/img/databases/cockroachdb-postgres/6-add-tables.png' alt='Add a new table' width='1100px' />
### Step 4: Try out a GraphQL query
Head to the `API` tab in the Console and try running a GraphQL query! Use the explorer sidebar on GraphQL to get help in
creating a GraphQL query.
<Thumbnail src='/img/databases/cockroachdb-postgres/7-make-graphql-query.png' alt='Make GraphQL query' width='1100px' />
## Keep up to date
Hasura currently supports [queries](./queries/postgres/index.mdx),
[relationships](./schema/postgres/table-relationships/index.mdx), and [mutations](./mutations/postgres/index.mdx) on
CockroachDB.
Please refer to the [Postgres docs](./queries/postgres/index.mdx) on how you can try these features out via the Console
or by manipulating Metadata in JSON/YAML directly.
If you'd like to stay informed about the status of CockroachDB support, subscribe to our newsletter and join our
discord!
- https://hasura.io/newsletter/
- https://discord.com/invite/hasura

196
docs/docs/databases/postgres/cockroachdb/getting-started/docker.mdx Normal file
View File

@ -0,0 +1,196 @@
---
sidebar_label: Docker
sidebar_position: 2
description: Hasura with Docker for CockroachDB
keywords:
- hasura
- docs
- databases
- cockroachdb
- docker
---
import Thumbnail from '@site/src/components/Thumbnail';
# Get Started with Hasura (Docker) & CockroachDB
## Try it out
### Pre-requisites
- [Docker](https://docs.docker.com/install/)
- [Docker Compose](https://docs.docker.com/compose/install/)
- Optionally, an existing [CockroachDB database](https://www.cockroachlabs.com/get-started-cockroachdb/)
### Step 1: Get the docker-compose file
Get the Hasura docker-compose file:
```bash
# in a new directory run
wget https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/docker-compose-cockroach/docker-compose.yaml
# or run
curl https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/docker-compose-cockroach/docker-compose.yaml -o docker-compose.yaml
```
### Step 2: Run Hasura GraphQL Engine and a CockroachDB instance
The following command will run Hasura along with a Postgres database required for its functioning.
```bash
$ docker compose up -d
```
Check that the containers are running:
```
$ docker ps
CONTAINER ID IMAGE ... CREATED STATUS PORTS ...
a6956d1492fd hasura/graphql-engine ... 1 minute ago Up 10 seconds 8080->8080/tcp ...
f0931e41c608 cockroach ... 1 minute ago Up 10 seconds 26257->26257/tcp ...
42cd380d6ceb postgres ... 1 minute ago Up 10 seconds 5432/tcp ...
Please do note that you will see a Postgres database running, which is used by Hasura to store its configuration (Hasura Metadata).
```
### Step 3: Open the Hasura Console
Head to `http://localhost:8080/console` to open the Hasura Console.
### Step 4: Add your CockroachDB database as a source to Hasura
In the `Data > Data Manager > Connect Existing Database` section on the Console, select `CockroachDB` from the
`Data Source Driver` dropdown and add the connection string directly or through an environment variable. As CockroachDB
speaks the same protocol as Postgres, the connection string will start with `postgres://`, i.e, there is no difference
between CockroachDB's connection strings and Postgres’s connection strings.
<Thumbnail src='/img/databases/cockroachdb-postgres/1-add-source.png' alt='Add source' width='1100px' />
If you're testing Hasura with CockroachDB running locally, [read this guide](/guides/docker-networking.mdx) on Docker
networking if you're not sure how to reach your CockroachDB database from the Hasura docker container on Linux, Mac or
Windows.
<Thumbnail
src='/img/databases/cockroachdb-postgres/2-add-source.png'
alt='Add source added with docker-compose'
width='1100px'
/>
This example uses the DB url `postgresql://root@cockroach:26257/hasura`, with the service name `cockroach`, as both
Hasura and the CockroachDB services are configured in the above-mentioned `docker-compose.yaml` file.
Once you add the database, you'll see your database pop up on the sidebar.
### Optional: Populate the CockroachDB database
The following examples use `author` and `articles` tables, which can be set up as follows.
1. Connect to the CockroachDB container and start the `sql` command line tool:
```bash
docker exec -it docker-compose-cockroach-cockroach-1 ./cockroach sql --insecure
```
2. Once the command line tool has started, execute the following to set up example tables:
```sql
CREATE TABLE author(
id serial PRIMARY KEY,
name text UNIQUE,
"createdAt" timestamp
);
CREATE TABLE article (
id SERIAL PRIMARY KEY,
title TEXT,
content TEXT,
author_id INTEGER REFERENCES author(id),
is_published BOOLEAN
);
-- Inserting sequential ids for demo purposes
-- See https://www.cockroachlabs.com/docs/v22.2/serial.html
INSERT INTO
author (id, name, "createdAt")
VALUES
(1, 'Author 3', '2017-09-21T09:39:44'),
(2, 'Author 4', '2017-09-21T09:50:44');
INSERT INTO
article (title, content, author_id, is_published)
VALUES
(
'Article 1',
'Sample article content 1',
1,
false
),
(
'Article 2',
'Sample article content 2',
1,
TRUE
),
(
'Article 3',
'Sample article content 3',
2,
TRUE
);
```
### Step 5: Track existing tables or create new tables
If you have existing tables, head to the database page by clicking on the database name on the sidebar. You should see a
list of tables.
<!--
.. thumbnail:: /img/databases/ms-sql-server/3-manage-mydb.png
:alt: Manage my-db
:width: 1000px
-->
Track tables selectively or all of them so that Hasura can introspect the tables and create the corresponding GraphQL
schema.
<Thumbnail src='/img/databases/cockroachdb-postgres/4-track-tables.png' alt='Track tables' width='1100px' />
If you have foreign keys, you'll also see suggested relationships. Again, you can choose to track them selectively or
all at once.
<Thumbnail
src='/img/databases/cockroachdb-postgres/5-track-rels.png'
alt='Track foreign-key relationships'
width='1100px'
/>
If you don't have existing tables, go ahead and add new tables and data and try out some queries, just like with a
regular Postgres database.
<Thumbnail src='/img/databases/cockroachdb-postgres/6-add-tables.png' alt='Add a new table' width='1100px' />
### Step 6: Try out a GraphQL query
Head to the `API` tab in the Console and try running a GraphQL query! Use the explorer sidebar on GraphQL to get help in
creating a GraphQL query.
<Thumbnail src='/img/databases/cockroachdb-postgres/7-make-graphql-query.png' alt='Make GraphQL query' width='1100px' />
## Keep up to date
Hasura currently supports [queries](./queries/postgres/index.mdx),
[relationships](./schema/postgres/table-relationships/index.mdx), and [mutations](./mutations/postgres/index.mdx) on
CockroachDB.
Please refer to the [Postgres docs](./queries/postgres/index.mdx) on how you can try these features out via the Console
or by manipulating metadata in JSON/YAML directly.
If you'd like to stay informed about the status of CockroachDB support, subscribe to our newsletter and join our
discord!
- https://hasura.io/newsletter/
- https://discord.com/invite/hasura

32
docs/docs/databases/postgres/cockroachdb/getting-started/index.mdx Normal file
View File

@ -0,0 +1,32 @@
---
description: Getting Started with Hasura &amp; CockroachDB
keywords:
- hasura
- docs
- databases
- cockroachdb
slug: index
---
# Getting Started with CockroachDB
To try Hasura with CockroachDB, you'll need your own new or existing CockroachDB database.
Here are 2 ways you can get started with Hasura:
1. [Hasura Cloud](/databases/postgres/cockroachdb/getting-started/cloud.mdx): You'll need to be able to access your
CockroachDB database from Hasura Cloud.
2. [Docker](/databases/postgres/cockroachdb/getting-started/docker.mdx): Run Hasura with Docker and then connect your
CockroachDB database to Hasura.
:::tip Supported versions:
<!--
TODO: confirm after release
https://hasurahq.atlassian.net/browse/NDAT-192
-->
1. Hasura GraphQL engine `v2.15.0` onwards
2. CockroachDB `v22.2` onwards
:::

75
docs/docs/databases/postgres/cockroachdb/hasura-cockroachdb-compatibility.mdx Normal file
View File

@ -0,0 +1,75 @@
---
sidebar_label: Hasura - CockroachDB compatibility
sidebar_position: 2
description: Hasura CockroachDB Postgres database support
keywords:
- hasura
- docs
- databases
- cockroachdb
- compatibility
---
# Hasura - CockroachDB Compatibility
## Introduction
As CockroachDB supports PostgresSQL, the way it functions with Hasura is also very similar. However, there are a few
incompatibilities to be aware of.
## Incompatibilities and unsupported features
The most up-to-date list of unsupported Postgres features can be found on the
[CockroachDB website](https://www.cockroachlabs.com/docs/stable/postgresql-compatibility.html).
- [Unsupported Postgres features](https://www.cockroachlabs.com/docs/stable/postgresql-compatibility.html#unsupported-features)
- [Features that differ from Postgres](https://www.cockroachlabs.com/docs/stable/postgresql-compatibility.html#features-that-differ-from-postgresql)
Currently, the following features are supported with CockroachDB and Hasura:
## Queries
Queries are fully supported, but please note that GraphQL key ordering in JSON objects is not guaranteed. This is
because CockroachDB implements the `JSONB` variant of the Postgres JSON types, which do not preserve key ordering.
Please also note that SERIAL columns will produce numbers that overflow Javascript numbers. These will need special
treatment by either enabling the
[`HASURA_GRAPHQL_STRINGIFY_NUMERIC_TYPES` environment variable](/deployment/graphql-engine-flags/reference.mdx) or
bespoke JSON parsing client-side.
## Tables
Querying from all kinds of tables and views is currently supported. This includes local, reference, and distributed
tables. All the tables can be tracked from the Hasura Console.
## Relationships
The following table describes the supported relationships based on the supported joins in CockroachDB:
| | To Local | To Reference | To Distributed |
| -------------------- | ------------- | ------------- | -------------- |
| **From Local** | Object, Array | Object, Array | |
| **From Reference** | Object, Array | Object, Array | |
| **From Distributed** | | Object | Object, Array |
The Hasura Console allows you to add all the supported relationships.
## Permissions
All permissions work on CockroachDB like on Postgres without any restrictions.
## Functions
CockroachDB, and therefore Hasura, does not yet support user-defined functions (UDFs) on a stable release. However, UDF
support has recently been added to CockroachDB Beta
([see issue](https://github.com/cockroachdb/cockroach/issues/58356)), so watch this space!
## Mutations
Mutations are supported in GraphQL Engine with the exception of fetching relationship data as part of `returning`. This
is not yet supported.
## Event triggers
CockroachDB does not yet support creating triggers ([see issue](https://github.com/cockroachdb/cockroach/issues/28296))
on reference tables. Hence, this is currently not supported.

33
docs/docs/databases/postgres/cockroachdb/index.mdx Normal file
View File

@ -0,0 +1,33 @@
---
description: Hasura CockroachDB
keywords:
- hasura
- docs
- databases
- cockroachdb
slug: index
---
# CockroachDB
## Introduction
[CockroachDB](https://www.cockroachlabs.com/product/) is an open-source, cloud-native, distributed SQL database. As it
is Postgres-compatible, the majority of Postgres' features, tooling, and ecosystem can be leveraged.
:::tip Supported versions:
<!--
TODO: confirm after release
https://hasurahq.atlassian.net/browse/NDAT-192
-->
1. Hasura GraphQL engine `v2.15.0` onwards
2. CockroachDB `v22.2` onwards
:::
## Know more
- [Getting started](/databases/postgres/cockroachdb/getting-started/index.mdx)
- [Hasura - CockroachDB compatibility](/databases/postgres/cockroachdb/hasura-cockroachdb-compatibility.mdx)

4
docs/docs/databases/postgres/index.mdx
View File

@ -28,15 +28,13 @@ Hasura supports most databases with full Postgres compatibility such as:
- [Yugabyte](https://www.yugabyte.com/)
- [Timescale](https://www.timescale.com/)
- [Citus](https://www.citusdata.com/)
- [CockroachDB](https://www.cockroachlabs.com/product/)
- [Aurora](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Aurora.AuroraPostgreSQL.html)
- [RDS](https://aws.amazon.com/rds/postgresql/)
- [Crunchy](https://www.crunchydata.com/)
- [AlloyDB](https://cloud.google.com/alloydb)
- [Neon](https://neon.tech/)
We have more distributed flavours like CockroachDB coming soon. See
[GitHub issue](https://github.com/hasura/graphql-engine/issues/678).
Curious about any other Postgres flavours? Any other questions? Ask us on
[GitHub discussions](https://github.com/hasura/graphql-engine/discussions)

BIN
docs/static/img/databases/cockroachdb-postgres/1-add-source.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 88 KiB

BIN
docs/static/img/databases/cockroachdb-postgres/2-add-source.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

BIN
docs/static/img/databases/cockroachdb-postgres/4-track-tables.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 80 KiB

BIN
docs/static/img/databases/cockroachdb-postgres/5-track-rels.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 75 KiB

BIN
docs/static/img/databases/cockroachdb-postgres/6-add-tables.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 143 KiB

BIN
docs/static/img/databases/cockroachdb-postgres/7-make-graphql-query.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 237 KiB

58
install-manifests/docker-compose-cockroach/docker-compose.yaml Normal file
View File

@ -0,0 +1,58 @@
version: '3.6'
services:
postgres:
image: postgres:14
restart: always
volumes:
- postgres-data:/var/lib/postgresql/data
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgrespassword
## Hasura is compatible with CockroachDB 22.2 onwards
cockroach:
image: cockroachdb/cockroach-unstable:v22.2.0-beta.4
# starts an _insecure_, single-node CockroachDB intended for non-production uses only
# follow the CockroachDB Cloud Guide to connect to a production CockroachDB cluster
command:
- start-single-node
- --insecure
- --accept-sql-without-tls
ports:
- '26257:26257'
environment:
COCKROACH_USER: 'root'
COCKROACH_DATABASE: 'hasura'
volumes:
- '${PWD}/cockroach-data:/cockroach/cockroach-data'
- ./docker-compose/cockroach/init.sh:/docker-entrypoint-initdb.d/init-hasura.sh:ro
graphql-engine:
## TODO: replace image after beta release
## https://hasurahq.atlassian.net/browse/NDAT-192
image: hasurabuild/graphql-engine:mono-pr-6366-cockroach.ubuntu
## Apple M1-compatible image
# image: hasura/graphql-engine:dev-2da1d2a-enable-cockroach.debian.arm64
ports:
- '8080:8080'
depends_on:
- 'postgres'
- 'cockroach'
restart: always
environment:
## postgres database to store Hasura metadata
HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
## enable the console served by server
HASURA_GRAPHQL_ENABLE_CONSOLE: 'true' # set to "false" to disable console
## enable debugging mode. It is recommended to disable this in production
HASURA_GRAPHQL_DEV_MODE: 'true'
HASURA_GRAPHQL_ENABLED_LOG_TYPES: startup, http-log, webhook-log, websocket-log, query-log
## uncomment next line to run console offline (i.e load console assets from server instead of CDN)
## TODO: comment line after beta release
## https://hasurahq.atlassian.net/browse/NDAT-192
HASURA_GRAPHQL_CONSOLE_ASSETS_DIR: /srv/console-assets
## uncomment next line to set an admin secret
# HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
volumes:
postgres-data:
cockroach-data: