dotnet edgeql tool

[quinchs]

Summary

As outlined in quinchs/EdgeDB.Net#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]

@1st1 @fantix ready for review!

[i0bs]

@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?

[dodyg]

Is this tool already available or still in the works?