diff --git a/README.md b/README.md index cef9dc53d7..12d42c6890 100644 --- a/README.md +++ b/README.md @@ -199,6 +199,9 @@ tools: description: 'id' represents the unique ID for each flight. ``` +For more details on configuring different types of tools, see the [Tool +documentation.](docs/tools/README.md) + ### Toolsets diff --git a/docs/sources/README.md b/docs/sources/README.md index 4ccb9a3a22..665af95af0 100644 --- a/docs/sources/README.md +++ b/docs/sources/README.md @@ -29,3 +29,4 @@ We currently support the following types of kinds of sources: * [cloud-sql-postgres](./cloud-sql-pg.md) - Connect to a Cloud SQL for PostgreSQL instance. * [postgres](./postgres.md) - Connect to any PostgreSQL compatible database. +* [spanner](./spanner.md) - Connect to a Spanner database. diff --git a/docs/sources/spanner.md b/docs/sources/spanner.md new file mode 100644 index 0000000000..7360bb75e7 --- /dev/null +++ b/docs/sources/spanner.md @@ -0,0 +1,49 @@ +# Spanner Source + +[Spanner][spanner-docs] fully managed, mission-critical database service +that brings together relational, graph, key-value, and search. It offers +transactional consistency at global scale, automatic, synchronous replication +for high availability, and support for two SQL dialects: GoogleSQL (ANSI 2011 +with extensions) and PostgreSQL. + +If you are new to Spanner, you can try to [create and query a database using +the Google Cloud console][spanner-quickstart]. + +[spanner-docs]: https://cloud.google.com/spanner/docs +[spanner-quickstart]: https://cloud.google.com/spanner/docs/create-query-database-console + +## Requirements + +### IAM Identity +By default, Spanner uses the [OAuth 2.0][oauth2] for API authentication and +authorization. The Cloud Spanner API uses your [Application Default Credentials +(ADC)][adc] to authorize your connection to Spanner. + +In addition to [setting the ADC for your server][set-adc], you need to ensure the IAM identity has been given the following IAM permissions: +- `roles/spanner.databaseUser` + +[oauth2]: https://datatracker.ietf.org/doc/html/rfc6749 +[adc]: https://cloud.google.com/docs/authentication#adc +[set-adc]: https://cloud.google.com/docs/authentication/provide-credentials-adc + +## Example + +```yaml +sources: + my-spanner-source: + kind: "spanner" + project: "my-project-name" + instance: "my-instance" + database: "my_db" + # dialect: "googlesql" +``` + +## Reference + +| **field** | **type** | **required** | **description** | +|-----------|:--------:|:------------:|------------------------------------------------------------------------------| +| kind | string | true | Must be "spanner". | +| project | string | true | Name of the GCP project that the cluster was created in (e.g. "my-project"). | +| instance | string | true | Name of the AlloyDB instance within the cluser (e.g. "my-instance"). | +| database | string | true | Name of the Postgres database to connect to (e.g. "my_db"). | +| dialect | string | true | Name of the dialect type of the Spanner database, must be either `googlesql` or `postgresql`. Default: `googlesql`. | diff --git a/docs/tools/README.md b/docs/tools/README.md index ae725d7f64..5492450d7e 100644 --- a/docs/tools/README.md +++ b/docs/tools/README.md @@ -48,6 +48,8 @@ We currently support the following types of kinds of tools: * [postgres-sql](./postgres-sql.md) - Run a PostgreSQL statement against a PostgreSQL-compatible database. +* [spanner](./spanner.md) - Run a Spanner (either googlesql or postgresql) + statement againts Spanner database. ## Specifying Parameters diff --git a/docs/tools/spanner.md b/docs/tools/spanner.md new file mode 100644 index 0000000000..8e48fdb7df --- /dev/null +++ b/docs/tools/spanner.md @@ -0,0 +1,110 @@ +# Spanner Tool + +A "spanner-sql" tool executes a pre-defined SQL statement (either +`googlesql` or `postgresql`) against Spanner database. It's +compatible with any of the following sources: +- [spanner](../sources/spanner.md) + +For `googlesql` dialect, the specified SQL statement is executed +as a [data manipulation language (DML)][gsql-dml] statements, and specified parameters will inserted +according to their name: e.g. "@name". + +For `postgresql` dialect, the specified SQL statement is executed as a +[prepared statement][pg-prepare], and specified parameters will inserted according +to their position: e.g. "$1" will be the first parameter specified, "$@" will be the +second parameter, and so on. + + +[gsql-dml]: https://cloud.google.com/spanner/docs/reference/standard-sql/dml-syntax +[pg-prepare]: https://www.postgresql.org/docs/current/sql-prepare.html + +## Example + +For `googlesql` dialect: +```yaml +tools: + search_flights_by_number: + kind: spanner + source: my-spanner-instance + statement: | + SELECT * FROM flights + WHERE airline = @airline + AND flight_number = @flight_number + LIMIT 10 + description: | + Use this tool to get information for a specific flight. + Takes an airline code and flight number and returns info on the flight. + Do NOT use this tool with a flight id. Do NOT guess an airline code or flight number. + A airline code is a code for an airline service consisting of two-character + airline designator and followed by flight number, which is 1 to 4 digit number. + For example, if given CY 0123, the airline is "CY", and flight_number is "123". + Another example for this is DL 1234, the airline is "DL", and flight_number is "1234". + If the tool returns more than one option choose the date closes to today. + Example: + {{ + "airline": "CY", + "flight_number": "888", + }} + Example: + {{ + "airline": "DL", + "flight_number": "1234", + }} + parameters: + - name: airline + type: string + description: Airline unique 2 letter identifier + - name: flight_number + type: string + description: 1 to 4 digit number +``` + +For `postgresql` dialect: +```yaml +tools: + search_flights_by_number: + kind: spanner + source: my-spanner-instance + statement: | + SELECT * FROM flights + WHERE airline = $1 + AND flight_number = $2 + LIMIT 10 + description: | + Use this tool to get information for a specific flight. + Takes an airline code and flight number and returns info on the flight. + Do NOT use this tool with a flight id. Do NOT guess an airline code or flight number. + A airline code is a code for an airline service consisting of two-character + airline designator and followed by flight number, which is 1 to 4 digit number. + For example, if given CY 0123, the airline is "CY", and flight_number is "123". + Another example for this is DL 1234, the airline is "DL", and flight_number is "1234". + If the tool returns more than one option choose the date closes to today. + Example: + {{ + "airline": "CY", + "flight_number": "888", + }} + Example: + {{ + "airline": "DL", + "flight_number": "1234", + }} + parameters: + - name: airline + type: string + description: Airline unique 2 letter identifier + - name: flight_number + type: string + description: 1 to 4 digit number +``` + +## Reference + +| **field** | **type** | **required** | **description** | +|-------------|:--------------------------------------------:|:------------:|-----------------------------------------------------------------------------------------------------| +| kind | string | true | Must be "postgres-generic". | +| source | string | true | Name of the source the SQL should execute on. | +| description | string | true | Port to connect to (e.g. "5432") | +| statement | string | true | SQL statement to execute on. | +| parameters | [parameter](README.md#specifying-parameters) | true | List of [parameters](README.md#specifying-parameters) that will be inserted into the SQL statement. | +