database.md
1 --- 2 title: Database 3 description: Details on the database design and how the service is used in Mercury Core. 4 --- 5 6 This page provides information about the database used in Mercury Core, including its design, structure, and how it integrates with other services. 7 8 Mercury Core uses [SurrealDB](https://surrealdb.com) as its primary database solution. 9 10 ## Startup 11 12 The following command can be used to start an instance of SurrealDB, assuming it's ran in the root directory of the Mercury Core repository. 13 14 ```bash 15 surreal start -u=root -p=root surrealkv://data/surreal 16 ``` 17 18 This should produce output similar to the following: 19 20 ```log 21 .d8888b. 888 8888888b. 888888b. 22 d88P Y88b 888 888 'Y88b 888 '88b 23 Y88b. 888 888 888 888 .88P 24 'Y888b. 888 888 888d888 888d888 .d88b. 8888b. 888 888 888 8888888K. 25 'Y88b. 888 888 888P' 888P' d8P Y8b '88b 888 888 888 888 'Y88b 26 '888 888 888 888 888 88888888 .d888888 888 888 888 888 888 27 Y88b d88P Y88b 888 888 888 Y8b. 888 888 888 888 .d88P 888 d88P 28 'Y8888P' 'Y88888 888 888 'Y8888 'Y888888 888 8888888P' 8888888P' 29 30 31 2038-01-19T03:14:07.119628Z INFO surreal::env: Running 2.4.0 for linux on x86_64 32 2038-01-19T03:14:07.120154Z INFO surrealdb::core::kvs::ds: Starting kvs store at surrealkv://data/surreal 33 2038-01-19T03:14:07.120164Z INFO surrealdb::core::kvs::surrealkv: Setting maximum segment size: 536870912 34 2038-01-19T03:14:07.120166Z INFO surrealdb::core::kvs::surrealkv: Setting maximum value threshold: 64 35 2038-01-19T03:14:07.187947Z INFO surrealdb::core::kvs::surrealkv: Setting maximum value cache size: 15304316928 36 2038-01-19T03:14:07.187968Z INFO surrealdb::core::kvs::surrealkv: Wait for disk sync acknowledgement: false 37 2038-01-19T03:14:07.283928Z INFO surrealdb::core::kvs::ds: Started kvs store at data/surreal with versions disabled 38 2038-01-19T03:14:07.284608Z INFO surreal::dbs: Initialising credentials user=root 39 2038-01-19T03:14:07.284864Z WARN surrealdb::core::kvs::ds: Credentials were provided, but existing root users were found. The root user 'root' will not be created 40 2038-01-19T03:14:07.284871Z WARN surrealdb::core::kvs::ds: Consider removing the --user and --pass arguments from the server start command 41 2038-01-19T03:14:07.301045Z INFO surrealdb::net: Listening for a system shutdown signal. 42 2038-01-19T03:14:07.301057Z INFO surrealdb::net: Started web server on 127.0.0.1:8000 43 ``` 44 45 Omitting the `surrealkv://data/surreal` path argument will cause SurrealDB to use an in-memory database, which is useful for testing purposes. You may see a warning about the root user account already existing; which is normal if you have started the database before. 46 47 ## Database inspection 48 49 A database management tool is available through the [Surrealist](https://app.surrealdb.com/) web interface, which can also be installed and run locally. 50 51 ## Common issues 52 53 ### Connection problems 54 55 SurrealDB supports connections via both HTTP (http://, https://) and WebSocket (ws://, wss://) protocols. Using the insecure versions should be fine if the service is running in local development or connected to from the Site hosted on the same machine, but if connecting remotely (such as to remotely manage the database on a VPS), the secure versions should be used. Add a domain configuration to the Caddyfile and change the default password to allow for this. 56 57 The WebSocket versions of the connection are broadly recommended over the HTTP versions, as they provide improved reliability and don't require re-authentication every 1 hour after connecting. If your connection seems to drop after being open for a long time (>1 hour), it may be over HTTP.. 58 59 ### Filesystem permissions 60 61 In some cases, the database may fail to start due to filesystem permission issues. This can occur if the user running the Mercury Core service does not have the necessary permissions to read or write to the database files. 62 63 An example of potential output could be as follows: 64 65 ```log 66 2038-01-19T03:14:07.740481Z INFO surreal::env: Running 2.4.0 for linux on x86_64 67 2038-01-19T03:14:07.741021Z INFO surrealdb::core::kvs::ds: Starting kvs store at surrealkv://data/surreal 68 2038-01-19T03:14:07.741047Z INFO surrealdb::core::kvs::surrealkv: Setting maximum segment size: 536870912 69 2038-01-19T03:14:07.741051Z INFO surrealdb::core::kvs::surrealkv: Setting maximum value threshold: 64 70 2038-01-19T03:14:07.805631Z INFO surrealdb::core::kvs::surrealkv: Setting maximum value cache size: 15304321024 71 2038-01-19T03:14:07.805646Z INFO surrealdb::core::kvs::surrealkv: Wait for disk sync acknowledgement: false 72 2038-01-19T03:14:07.805673Z INFO surrealdb::core::kvs::ds: Started kvs store at surreal with versions disabled 73 2038-01-19T03:14:07.805687Z ERROR surreal::cli: There was a problem with the database: There was a problem with the underlying datastore: Log error: IO error: kind=permission denied, message=Permission denied (os error 13) 74 Goodbye! 75 [process exited with code 1] 76 ```