Skip to content

Commit

Permalink
Improve surreal start command documentation (#818)
Browse files Browse the repository at this point in the history
Co-authored-by: Obinna Ekwuno <[email protected]>
  • Loading branch information
matthewjnield and Ekwuno authored Sep 5, 2024
1 parent 89b487b commit e7c92f6
Showing 1 changed file with 26 additions and 4 deletions.
30 changes: 26 additions & 4 deletions doc-surrealdb_versioned_docs/version-latest/cli/start.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ __BEFORE YOU START :__ Make sure you’ve [installed SurrealDB](/docs/surrealdb/
<ul>
<li><code>rocksdb</code> for RocksDB</li>
<li><code>fdb</code> for FoundationDB</li>
<li><code>indxdb</code> for IndxDB</li>
<li><code>indxdb</code> for IndexedDB</li>
<li><code>memory</code> (or no argument) for in-memory storage</li>
<li><code>surrealkv</code> for SurrealKV</li>
<li><code>tikv</code> for TiKV</li>
Expand All @@ -124,12 +124,34 @@ __BEFORE YOU START :__ Make sure you’ve [installed SurrealDB](/docs/surrealdb/

## Example usage

To display the current command-line tool version, along with the platform and architecture, in a terminal run the surreal version.
This example will show how to host a SurrealDB server with the `surreal start` command, and then access the Surreal DB server using the [`surreal sql` command](/docs/surrealdb/cli/sql).

To start a SurrealDB server, run the `surreal start` command, using the options below. This example stores the database in memory, with a username and password, hosted at `127.0.0.1:8000` (the default location).

```bash
surreal version
surreal start memory --user my_username --pass my_password
```

The server is actively running, and should be left alone until you want to stop hosting the SurrealDB server.

:::note
__Note:__ The message "Started web server on 127.0.0.1:8000", indicates where the server is being hosted and must be accessed by clients. The location `127.0.0.1:8000` is the default, and can be manually changed by specifying the `--bind` option of the `surreal start` command.
:::


To access the SurrealDB server that you have started hosting, open a separate terminal which will act as the "client", while the previous terminal is still running the `surreal start` command described above.

In the new terminal, run the [`surreal sql` command](/docs/surrealdb/cli/sql) using the options shown below.

```bash
surreal sql --endpoint http://127.0.0.1:8000 --namespace my_namespace --database my_database --auth-level root --username my_username --password my_password
```

Ensure that the hosting location indicated by the output of the `surreal start` command is passed to the `--endpoint` argument, and that you specify the same `--username` and `--password` as in the `surreal start` command.

The above example also selects a namespace and database so that you can immediately start entering queries if you wish. See the documentation of the [`surreal sql` command](/docs/surrealdb/cli/sql) for more information.


## Strict mode

SurrealDB supports the ability to startup in strict mode. When running in strict mode, all `NAMESPACE`, `DATABASE`, and `TABLE` definitions will not be created automatically when data is inserted. Instead, if the selected namespace, database, or table has not been specifically defined, then the query will return an error.
Expand Down Expand Up @@ -262,4 +284,4 @@ CAPABILITIES:
--deny-funcs [<DENY_FUNCS>...] Deny execution of all functions. Optionally, you can provide a comma-separated list of function names to deny [env:SURREAL_CAPS_DENY_FUNC=]
--deny-net [<DENY_NET>...] Deny all outbound network access. Optionally, you can provide a comma-separated list of targets to deny [env: SURREAL_CAPS_DENY_NET=]
```
```

0 comments on commit e7c92f6

Please sign in to comment.