Improve documentation

[zamazan4ik]

Hi!

I have checked the documentation for the database and I see that there are a LOT of missing parts. I think that's because SurrealDB is too young. But from the user perspective - that is really scary try to use something without documentation for essential parts.

I think the list and examples below will be a good start point to fill the missing gaps.

Some examples of the most important gaps (fmpov):

• Clustering support (and provided guarantees)
• Replication support
• Backup/restore
• Upgrade/downgrade processes and guarantees between releases
• Monitoring, alerting, etc

Some examples of good documentation:

• CockroachDB
• ScyllaDB

I hope it will be helpful. Thanks in advance!

[tobiemh]

Hi @zamazan4ik thanks for creating this discussion. We are definitely working on the documentation, and know there is room for lots of improvement!

There is still a considerable amount of things missing so thanks for pointing out those core topics! It's definitely helpful!

With regards to backup / restore these two pages might be a start:

• Export (or backup) https://surrealdb.com/docs/cli/export
• Import (or restore) https://surrealdb.com/docs/cli/import

[LeonidChetverikov]

Also it will be interesting to get yours vision about HA solution, it is part of production readiness of DB.
Thank you in advice!

[bakman2]

I know that documentation is hard, but it is the key for success.
This is an awesome project thanks for the brilliant features surrealdb is offering. I am just a home user and trying it out for the live/websocket features.

the documentation assumes only in-memory storage, at home in a single lxc that is not very practical, so i start it with a path as indicated:

USAGE:
    surreal start [OPTIONS] [--] [path]

ARGS:
    <path>    Database path used for storing data [default: memory]

surreal start --log debug --user root --pass root /root/surrealdb/test.db

Result:

error: Invalid value "/root/surrealdb/test.db" for '<path>': Provide a valid database path parameter

root@oracle:~# pwd
/root

root@oracle:~# ls -l 
drwxr-xr-x 3 root root 3 Sep 11 05:10 surrealdb

How is this an invalid path ?

By sheer accident i found someone mentioning the path in this format:

file:////root/surrealdb/test.db

which works.

Perhaps this format should be included in the help parameters and on web ?

[SYUMJOBA]

Yes ... that is something I lost an entire hour on. Surreal does not actually ask for a "file path" as an OS would, but rather some sort of "protocol handle". "file:" is the prefix for what pseudo protocol you are willing to use, same as "https:///?<variables&stuff>" you are using "file:/".

That is something the docs should talk about because it can easily mess things up, also because it also kinda is a smart feature because it would allow you to start a surreal database on a host server somewhere else, VERY useful for networking applications.

Tho I like how simple and straight to the point the SurrealDB docs are ... we'll see.

[itsezc]

Is there any documentation for the upgrade process? I think this could be highlighted a little bit clearer

[LeoDog896]

There is also barely any documentation for using scopes in SurrealDB.

[gnimmelf]

I see on discord that this is s.th you are working on (tokens), so I just wanted to chime in on security/permissions/scope etc as the first thing I went looking for in the documentation. The reason is that as a frontender, my first goal is to set this up on a server to access it securely from anywhere, and only then start with the schemaless graph playground that instantly sold me on surreal.

Cheers,
Flemming

[F9Alejandro]

Some documentation on DEFINE besides the schema for it would be lovely, then we could get a better usage idea for LOGIN since it just throws an error for the entire line no matter what I do.

[gnimmelf]

Hope this helps,

it took me forever to figure out ns (or was it sc?) also has to be in there, even with discord help =P

const defaultParams = {
  ns: 'intergate',
  db: 'test',
  sc: 'account',
};

const doFetch = async (urlPath, { headers = {}, body = {} } = {}) => {
  const response = await fetch(`http://localhost:8000/${urlPath}`, {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      ...headers,
    },
    body: JSON.stringify({
      ...body,
      ...defaultParams,
    }),
  });
  const result = response.json();
  console.info(urlPath, { result });
  return result;
};

export const signin = async (credentials) => {
  return await doFetch('signin', { body: credentials });
};

export const signup = async (credentials) => {
  return await doFetch('signup', { body: credentials });
};

export const userCount = async () => {
  return await doFetch('sql', { body: credentials });
};

[SYUMJOBA]

should I mention?

The same text is repeated 4 times 😂. Poor newcomers

[D0bhareach]

Would like add a little more to aforementioned.
Mdbook would be great to these who do not have constant connection now I just 'wgeted' docs site.

• Questions like security for server root user, roles, configurations etc.
• Where server files are stored?
• Surrealdb is it suppose to run as a server?
• Need for tutorial. With Articles:

1. Installation.
2. INFO about server. How to look around.
3. Security. Layers of security.
4. Users, Roles, Permissions. How to DEFINE. How to harden configs.
5. Import demo data.
6. Query demo: simple and with RELATE.
7. Indexing.
8. Why and when use schema, how?
9. CREATE DB, Table.
10. Populate rows.
11. Functions.
12. Using as Embedded and In-Memory.
13. How to test. Analytics.

While I was writing it I realized this all probably related to documentation project. Beg for excuses if created too much noise.

[naisofly]

Hey everyone! I hope you've seen our new docs at https://docs.surrealdb.com and read about the transition here ✌️