main.go
The main function in then main.go is the entry point for your plugin. This function must call plugin.Serve from the plugin sdk to instantiate your plugin gRPC server. You will pass the plugin function that you will create in the plugin.go file.
plugin.go
The plugin.go file should implement a single Plugin Definition (Plugin() function) that returns a pointer to a Plugin to be loaded by the gRPC server.
By convention, the package name for your plugin should be the same name as your plugin, and go files for your plugin (except main.go) should reside in a folder with the same name.
Plugin Definition
| Argument | Description |
|---|---|
| Name | The name of the plugin (steampipe-plugin-{plugin name}). |
| TableMap | A map of table names to Table definitions. |
| DefaultTransform | A default Transform Function to be used when one is not specified. While not required, this may save quite a bit of repeated code. |
| DefaultGetConfig | Provides an optional mechanism for providing plugin-level defaults to a get config. This is merged with the GetConfig defined in the table and/or columns. Typically, this is used to standardize error handling with ShouldIgnoreError. |
| SchemaMode | Specifies if the schema should be checked and re-imported if changed every time Steampipe starts. This can be set to dynamic or static. Defaults to static. |
| RequiredColumns | An optional list of columns that ALL tables in this plugin MUST implement. |
Example Plugin Definition
Here's the definition of the Zendesk plugin.
Table Definition
The plugin.Table may specify:
| Argument | Description |
|---|---|
| Name | The name of the table. |
| Description | A short description, added as a comment on the table and used in help commands and documentation. |
| Columns | An array of column definitions. |
| List | A List Config definition, used to fetch the data items used to build all rows of a table. |
| Get | A Get Config definition, used to fetch a single item. |
| DefaultTransform | A default transform function to be used when one is not specified. If set, this will override the default set in the plugin definition. |
Example Table Definition
Here's how the zendesk_user table is defined.
List Config
A ListConfig definition defines how to list all rows of a table.
| Argument | Description |
|---|---|
| KeyColumns | An optional list of columns that require a qualifier in order to list data for this table. |
| Hydrate | A hydrate function which is called first when performing a 'list' call. |
| ParentHydrate | An optional parent list function - if you list items with a parent-child relationship, this will list the parent items. |
Get Config
A GetConfig definition defines how to get a single row of a table.
| Argument | Description |
|---|---|
| KeyColumns | A list of keys which are used to uniquely identify rows - used to determine whether a query is a 'get' call. |
| ItemFromKey [DEPRECATED]] | This property is deprecated. |
| Hydrate | A hydrate function which is called first when performing a 'get' call. If this returns 'not found', no further hydrate functions are called. |
| ShouldIgnoreError | A function which will return whether to ignore a given error. |
Column Definition
A column definition definition specifies the name and description of the column, its data type, and the functions to call to hydrate the column (if the list call does not) and transform it (if the default transformation is not sufficient).
| Argument | Description |
|---|---|
| Name | The column name. |
| Type | The data type for this column. |
| Description | The column description, added as a comment and used in help commands and documentation. |
| Hydrate | You can explicitly specify the hydrate function function to populate this column. This is only needed if neither the default hydrate functions nor the List function return data for this column. |
| Default | An optional default column value. |
| Transform | An optional chain of transform functions to generate the column value. |
Column Data Types
Currently supported data types are:
| Name | Type |
|---|---|
| ColumnType_BOOL | Boolean |
| ColumnType_INT | Integer |
| ColumnType_DOUBLE | Double precision floating point |
| ColumnType_STRING | String |
| ColumnType_JSON | JSON |
| ColumnType_DATETIME | Date/Time (Deprecated - use ColumnType_TIMESTAMP) |
| ColumnType_TIMESTAMP | Date/Time |
| ColumnType_IPADDR | IP Address |
| ColumnType_CIDR | IP network CIDR |
| ColumnType_UNKNOWN | Unknown |
| ColumnType_INET | Either an IP Address or an IP network CIDR |
| ColumnType_LTREE | Ltree |