1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
|
Contributing to usql
====================
Any contributions are welcome. If you found a bug, or a missing feature,
take a look at existing [issues](https://github.com/xo/usql/issues)
and create a new one if needed.
You can also open up a [pull request](https://github.com/xo/usql/pulls) (PR)
with code or documentation changes.
# Adding a new driver
1. Add a new schema in [dburl](https://github.com/xo/dburl).
1. Create a new go package in `drivers`. It should have an `init()` function, that would call `drivers.Register()`.
1. Regenerate code in the `internal` package by running `internal/gen.sh`.
1. Add any new required modules using `go get` or by editing `go.mod` manually and running `go mod tidy`.
1. Run all tests, build `usql` and see if the new driver works.
1. Update `README.md`.
> Tip: check out closed PRs for examples, and/or search the codebase
for names of databases you're familiar with.
# Enabling metadata introspection for a driver
For `\d*` commands to work, `usql` needs to know how to read the structure of a database.
A driver must provide a metadata reader, by setting the `NewMetadataReader` property
in the `drivers.Driver` structure passed to `drivers.Register()`. This needs to be a function
that given a database and reader options, returns a reader instance for this particular driver.
If the database has a `information_schema` schema, with standard tables like `tables` and `columns`,
you can use an existing reader from the `drivers/informationschema` package.
Since there are usually minor difference in objects defined in that schema in different databases,
there's a set of options to configure this reader. Refer to
the [package docs](https://pkg.go.dev/github.com/xo/usql/drivers/metadata/informationschema) for details.
If you can't use the `informationschema` reader, consider implementing a new one.
It should implement at least one of the following reader interfaces:
* CatalogReader
* SchemaReader
* TableReader
* ColumnReader
* IndexReader
* IndexColumnReader
* FunctionReader
* FunctionColumnReader
* SequenceReader
Every of these interfaces consist of a single function, that takes a `Filter` structure as an argument,
and returns a set of results and an error.
Example drivers using their own readers include:
* `sqlite3`
* `oracle` and `godror` sharing the same reader
If you want to use the `informationschema` reader, but need to override one or more readers,
use the `metadata.NewPluginReader(readers ...Reader)` function. It returns an object calling
reader functions from the last reader passed in the arguments, that implements it.
Example drivers extending an `informationschema` reader using a plugin reader:
* `postgres`
`\d*` commands are actually implemented by a metadata writer. There's currently only one,
but it too can be replaced and/or extended.
# Enabling autocomplete for a driver
If a driver provides a metadata reader, the default completer will use it.
A driver can provide it's own completer, by setting the `NewCompleter` property
in the `drivers.Driver` structure passed to `drivers.Register()`.
|
