DEFINE CONFIG
statementThe DEFINE CONFIG
statement allows you to set external configurations on your database. It can be used to configure API middleware and permissions, or to configure how the database’s tables and functions are exposed via the GraphQL API.
WarningBy running SurrealDB with configurations for the database API or the GraphQL module, you are opting into an experimental feature. While these features are fully functional, they are still considered experimental and may not be as stable as the core SurrealQL module which means we cannot guarantee that it will provide the same security guarantees. They are not recommended for production use. We welcome your feedback and contributions to help improve the feature and make it more robust.
DEFINE CONFIG GRAPHQL
statement.DEFINE CONFIG GRAPHQL
statement.SURREAL_CAPS_ALLOW_EXPERIMENTAL
environment variable set to "graphql"
.
SurrealQL SyntaxDEFINE CONFIG [ OVERWRITE | IF NOT EXISTS ] [ API [ MIDDLEWARE @expression, .. ] [ PERMISSIONS [ NONE | FULL | @expression ] ] [ GRAPHQL [ AUTO | NONE ] [ TABLES (AUTO | NONE | INCLUDE table1, table2, ...) ] [ FUNCTIONS (AUTO | NONE | INCLUDE [function1, function2, ...] | EXCLUDE [function1, function2, ...]) ] ]
The DEFINE CONFIG API
statement can be used to set middleware and permissions in order to alter the behaviour of the database for guest and record users. This middleware can be used in cases such as rate limiting on the query language and setting how many resources a client can read or alter at a time.
DEFINE CONFIG API
is often used in conjunction with a flag or environment variable to disable arbitrary queries, thereby forcing record and anonymous users to interact with the database via API endpoints alone.
The following is an example of a DEFINE CONFIG
statement that includes a timeout and a single header in the responses of all API endpoints.
DEFINE CONFIG API MIDDLEWARE api::timeout(10s), api::res::headers({ 'Access-Control-Allow-Origin': '*' });
To set the actual API endpoints and their middleware, a DEFINE API
statement is used for each endpoint.
The behaviour of API endpoints can be tested using the api::invoke
method, or through a regular HTTP call to the endpoint that includes the namespace and database name.
This next example uses DEFINE CONFIG
to set a single response header, followed by two endpoints that return different output.
DEFINE CONFIG API MIDDLEWARE api::res::headers({ 'Access-Control-Allow-Origin': '*' }); DEFINE API "/test" FOR get THEN {}; DEFINE API "/test2" FOR get THEN { RETURN { body: { some: "data" } } }; api::invoke("/test"); api::invoke("/test2");
The query shows that the endpoints return a combination of the DEFINE CONFIG
middleware and the response object set in the DEFINE API
statements.
-------- Query -------- { headers: { "access-control-allow-origin": '*' }, raw: false, status: 200 } -------- Query -------- { body: { some: 'data' }, headers: { "access-control-allow-origin": '*' }, raw: false, status: 200 }
Note that the middleware and permissions inside individual DEFINE API
statements will override the middleware in a DEFINE CONFIG API
statement. In the following example, the default 10s
timeout is set to a single microsecond for the "/test"
endpoint, giving the intended query no time to complete.
DEFINE CONFIG API MIDDLEWARE api::timeout(10s), api::res::headers({ 'Access-Control-Allow-Origin': '*' }); DEFINE API OVERWRITE "/test" FOR get MIDDLEWARE api::timeout(1µs) THEN { RETURN { status: 200, body: { data: (SELECT * FROM person), however: "This will probably never return because the timeout is 1 microsecond" } }; }; api::invoke("/test");
Output'The query was not executed because it exceeded the timeout'
The configuration set using the DEFINE CONFIG GRAPHQL
is essential for enabling GraphQL functionality in your database, specifying which tables and functions should be included or excluded from the GraphQL schema.
The GraphQL configuration defined using this statement dictates how clients interact with your database through GraphQL queries and mutations.
DEFINE CONFIG GRAPHQL
statement must be executed before any GraphQL queries can be made.NotConfigured
error.-- Define GraphQL configuration DEFINE CONFIG GRAPHQL AUTO;
The TABLES
clause in the DEFINE CONFIG GRAPHQL
statement specifies how tables are exposed via GraphQL. There are four options for the TABLES
configuration:
AUTO
: Automatically include all tables in the GraphQL schema.NONE
: Do not include any tables in the GraphQL schema.INCLUDE
: Specify a list of tables to include in the GraphQL schema.EXCLUDE
: Specify a list of tables to exclude from the GraphQL schema.AUTO
When you specify TABLES AUTO
, all tables in the database are automatically included in the GraphQL schema.
DEFINE CONFIG GRAPHQL TABLES AUTO;
NONE
When you specify TABLES NONE
, no tables are included in the GraphQL schema.
DEFINE CONFIG GRAPHQL TABLES NONE;
INCLUDE
You can specify a list of tables to include in the GraphQL schema using the INCLUDE
clause. The list of tables is specified as a comma-separated list without brackets.
DEFINE CONFIG GRAPHQL TABLES INCLUDE user, post, comment;
NoteThe
EXCLUDE
option forTABLES
is currently not implemented.
The FUNCTIONS
clause in the DEFINE CONFIG GRAPHQL
statement specifies how functions are exposed via GraphQL. There are four options for the FUNCTIONS
configuration:
AUTO
: Automatically include all functions in the GraphQL schema.NONE
: Do not include any functions in the GraphQL schema.INCLUDE
: Specify a list of functions to include in the GraphQL schema.EXCLUDE
: Specify a list of functions to exclude from the GraphQL schema.AUTO
When you specify FUNCTIONS AUTO
, all functions in the database are automatically included in the GraphQL schema.
DEFINE CONFIG GRAPHQL FUNCTIONS AUTO;
NONE
When you specify FUNCTIONS NONE
, no functions are included in the GraphQL schema.
DEFINE CONFIG GRAPHQL FUNCTIONS NONE;
INCLUDE
You can specify a list of functions to include in the GraphQL schema using the INCLUDE
clause. The list of functions is specified as a comma-separated list enclosed in square brackets []
.
DEFINE CONFIG GRAPHQL FUNCTIONS INCLUDE [getUser, listPosts, searchComments];
EXCLUDE
You can specify a list of functions to exclude from the GraphQL schema using the EXCLUDE
clause. The list of functions is specified as a comma-separated list enclosed in square brackets []
.
DEFINE CONFIG GRAPHQL FUNCTIONS EXCLUDE [debugFunction, testFunction];
IF NOT EXISTS
clauseThe IF NOT EXISTS
clause can be used to define the GraphQL configuration only if it does not already exist. This is useful when you want to ensure that the configuration is only created if it does not already exist, preventing errors due to duplicate definitions.
-- Define GraphQL configuration only if it does not already exist DEFINE CONFIG GRAPHQL IF NOT EXISTS TABLES AUTO FUNCTIONS AUTO;
OVERWRITE
clauseThe OVERWRITE
clause can be used to redefine the GraphQL configuration, overwriting any existing configuration. This is useful when you want to update or modify the existing GraphQL configuration.
-- Redefine GraphQL configuration, overwriting existing configuration DEFINE CONFIG OVERWRITE GRAPHQL TABLES INCLUDE user, post FUNCTIONS NONE;
This example defines a GraphQL configuration that includes specific tables and functions.
DEFINE CONFIG GRAPHQL TABLES INCLUDE user, post FUNCTIONS INCLUDE [getUser, listPosts];
This example defines a GraphQL configuration that automatically includes all tables and functions.
DEFINE CONFIG GRAPHQL TABLES AUTO FUNCTIONS AUTO;
This example defines a GraphQL configuration that includes all functions except specific ones.
DEFINE CONFIG GRAPHQL FUNCTIONS EXCLUDE [debugFunction, testFunction];
If you attempt to access the GraphQL endpoint without defining the GraphQL configuration, you will receive a NotConfigured
error.
Error Response{ "error": "NotConfigured: GraphQL endpoint is not configured. Please define the GraphQL configuration using DEFINE CONFIG GRAPHQL." }
Execute the DEFINE CONFIG GRAPHQL
statement to define the GraphQL configuration.
-- Define GraphQL configuration DEFINE CONFIG GRAPHQL TABLES AUTO FUNCTIONS AUTO;
If you have defined the GraphQL configuration but no tables are defined in the database, you will receive an error stating “No tables found in database” when attempting to use the GraphQL API. You can fix this by defining at least one table in your database using the DEFINE TABLE
statement.
Error Response{ "error": "No tables found in database. Please define at least one table to use the GraphQL API." }
Solution: Define at least one table in your database.
DEFINE TABLE foo SCHEMAFUL; DEFINE FIELD val ON foo TYPE int; CREATE foo:1 SET val = 42;
Cause: Insufficient permissions or incorrect authentication credentials.
Solution: Ensure you are authenticated as a user with the necessary permissions and that the permissions on tables and fields are correctly configured.
-- Define a user with access permissions DEFINE USER my_user ON DATABASE PASSWORD 'my_password'; DEFINE ACCESS user ON DATABASE TYPE RECORD SIGNUP ( CREATE user SET email = $email, pass = crypto::argon2::generate($pass) ) SIGNIN ( SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(pass, $pass) ) DURATION FOR SESSION 60s, FOR TOKEN 1d; -- Define a table with permissions DEFINE TABLE foo SCHEMAFUL PERMISSIONS FOR select WHERE $auth.email = email; DEFINE FIELD email ON foo TYPE string; DEFINE FIELD val ON foo TYPE int; -- Insert data CREATE foo:1 SET val = 42, email = "user@example.com"; CREATE foo:2 SET val = 43, email = "other@example.com";
When querying the GraphQL API as user@example.com
, only the records where email = "user@example.com"
will be accessible due to the permissions set.
-- Define GraphQL configuration to include all tables automatically DEFINE CONFIG GRAPHQL TABLES AUTO; -- Define a table and insert data DEFINE TABLE foo SCHEMAFUL; DEFINE FIELD val ON foo TYPE int; CREATE foo:1 SET val = 42; CREATE foo:2 SET val = 43;
Now, you can fetch data via GraphQL:
query { foo { id val } }
Response:
{ "data": { "foo": [ { "id": "foo:1", "val": 42 }, { "id": "foo:2", "val": 43 } ] } }
-- Define GraphQL configuration to include only specific tables DEFINE CONFIG OVERWRITE GRAPHQL TABLES INCLUDE foo;
When querying the GraphQL schema, only the included tables will be available.
You can use limit
, start
, order
, and filter
in your GraphQL queries to control the data returned.
query { foo(limit: 1) { id val } }
query { foo(start: 1) { id val } }
query { foo(order: { desc: val }) { id val } }
query { foo(filter: { val: { eq: 42 } }) { id val } }
The DEFINE CONFIG GRAPHQL
statement is essential for enabling and configuring the GraphQL API in SurrealDB. By specifying which tables and functions are included or excluded, you can fine-tune the GraphQL schema to match your application’s needs.
ImportantAlways ensure you have the necessary permissions and have selected the appropriate namespace and database before using the
DEFINE CONFIG GRAPHQL
statement.
DEFINE CONFIG GRAPHQL
to enable and configure the GraphQL API.OVERWRITE
and IF NOT EXISTS
clauses as needed to manage your configuration.limit
, start
, order
, and filter
to control the data returned.By following these guidelines, you can effectively use the DEFINE CONFIG GRAPHQL
statement to configure and interact with your SurrealDB database via GraphQL.