edgedb
dotnet edgeql tool
Summary
As outlined in https://github.com/quinchs/EdgeDB.Net/issues/21, this tool provides a way to create .cs files from .edgeql files. All commands/parameters are up for change to meet consistency with other edgedb tools
Commands
The dotnet tools cli name is edgedb-net, mimic'ing the pythons edgedb-py command name.
Generate
generate is the main command to generate source files from edgeql.
Arguments
p, project Whether or not to create the default class library that
will contain the generated source code. Enabled by
default.
o, output The output directory for the generated source to be
placed. When generating a project, source files will be
placed in that projects directory. Default is the
current directory
n, project-name The name of the generated project and namespace of
generated files.
f, force Force regeneration of files
w, watch Listens for any changes or new edgeql files and
(re)generates them automatically
dsn DSN for EdgeDB to connect to (overrides all other
options except password)
credentials-file Path to JSON file to read credentials from
I, instance Local instance name created with edgedb instance create
to connect to (overrides host and port)
H, host Host of the EdgeDB instance
P, port Port to connect to EdgeDB
d, database Database name to connect to
u, user User name of the EdgeDB user
password Ask for password on the terminal (TTY)
password-from-stdin Read the password from stdin rather than TTY (useful
for scripts)
tls-ca-file Certificate to match server against
This might either be full self-signed server
certificate or certificate authority (CA) certificate
that server certificate is signed with.
tls-security Specify the client-side TLS security mode.
loglevel Configure the log level
help Display more information on a specific command.
version Display version information.
Example
$ edgedb-net generate -o ~/myproject/src/generated
Connection uses the same resolution logic as the edgedb CLI tool, as well as the same arguments for specifying connection parameters.
Watch
The watch command is simply to start/stop/view the watcher for the current project.
Arguments
t, directory The directory to watch for .edgeql files.
k, kill Kill the current running watcher for the project
b, background Runs the watcher in a background process
o, output The output directory for the generated source to be
placed.
n, project-name The name of the generated project and namespace of
generated files.
dsn DSN for EdgeDB to connect to (overrides all other
options except password)
credentials-file Path to JSON file to read credentials from
I, instance Local instance name created with edgedb instance create
to connect to (overrides host and port)
H, host Host of the EdgeDB instance
P, port Port to connect to EdgeDB
d, database Database name to connect to
u, user User name of the EdgeDB user
password Ask for password on the terminal (TTY)
password-from-stdin Read the password from stdin rather than TTY (useful
for scripts)
tls-ca-file Certificate to match server against
This might either be full self-signed server
certificate or certificate authority (CA) certificate
that server certificate is signed with.
tls-security Specify the client-side TLS security mode.
loglevel Configure the log level
help Display more information on a specific command.
version Display version information.
Example
$ edgedb-net watch
[18:56:09 INF] Watcher started for /My/Awesome/Project
$ edgedb-net watch --background
[18:56:46 INF] Background process started with id 38294
Project root is located from the output directory, if none is specified then the current directory + namespace is used.
Generation structure
Code generation will generate a source file per edgeql file, ignoring files in ./dbschema/migrations/*, each generated source file contains a class representing the result and a class containing execute methods. Here's an example:
EdgeQL
select Person {
name, email
}
filter .email = <str>$email
Source file
// AUTOGENERATED: DO NOT MODIFY
// edgeql:E116C5881529C70BFC6A9D0350075968AD967D391FEE0F74033FA870A1FE56DD
// Generated on 2022-08-26T11:52:03.5962767Z
#nullable enable
using EdgeDB;
namespace EdgeDB.Generated;
#region Types
[EdgeDBType]
public sealed class GetUserResult
{
[EdgeDBProperty("id")]
public Guid Id { get; set; }
[EdgeDBProperty("name")]
public String? Name { get; set; }
[EdgeDBProperty("email")]
public String? Email { get; set; }
}
#endregion
public static class GetUser
{
public static readonly string Query = @"select Person {
name, email
}
filter .email = <str>$email";
public static Task<GetUserResult?> ExecuteAsync(IEdgeDBQueryable client, String? email, CancellationToken token = default)
=> client.QuerySingleAsync<GetUserResult>(Query, new Dictionary<string, object?>() { { "email", email } }, capabilities: (Capabilities)0ul, token: token);
public static Task<GetUserResult?> GetUserAsync(this IEdgeDBQueryable client, String? email, CancellationToken token = default)
=> ExecuteAsync(client, email, token: token);
}
#nullable restore
A user consuming this generated file has two ways of using it:
// Option one: extension methods
using EdgeDB.Generated;
var client = new EdgeDBClient(...);
var user = await client.GetUserAsync(email: "[email protected]");
...
// Option two: direct call
using EdgeDB.Generated;
var client = new EdgeDBClient(...);
var user = await GetUser.ExecuteAsync(client, email: "[email protected]");
Example app
An example application was made to test out the flow of code generation, this was the command used to generate ./EdgeDB.Generated in that app:
$ edgedb-net generate
@quinchs I'd like to propose us adding another callable to the .NET domain for CLI commands and adding a new documentation page surrounding usage of all commands. EdgeDB already have a Sphinx reference as :cli:synopsis:. Maybe we could use this as well?
