# Configuration & Conversion

## Connection

There are three main knobs to turn for the connection.
Two are for conversion to/from SQL, covered below.

The other is the `row_factory`, which works the same way
as in `sqlite3`.
It is unlikely you'll ever need to do this,
but you can specify the `row_factory`
when calling `connect`.

## Converting To Sql

The connection takes a {class}`coolqlite.to_sql.ToSqlFnRegistry`.
It takes a {class}`coolqlite.to_sql.ToSqlConfig`.

Right now it only asks if you want to add the default
temporal conversion functions.

Configuring your own named or typed converters is covered in
[Usage's Insertion docs](./usage.md#what-about-inserting-things-other-than-strs-and-ints).

You can shadow any "built-in" converters set up by the config.
It will issue a warning, not an error.

## Converting From Sql

The connection takes a {class}`cattrs.BaseConverter`.

{func}`coolqlite.from_sql.configure_converter`
will create a new converter with coolqlite's reasonable defaults,
or add coolqlite's defaults to an existing converter if you have one.

If you want to override coolqlite's behavior,
you use the configuration functions directly.
If you're supplying your own converter,
we assume you don't want new versions to add new defaults,
so opting-in is the best way to ensure consistent behavior.

{func}`~coolqlite.from_sql.configure_strict_primitives`
does just that.
By default, cattrs will covert/coerce primitives:

```python
>>> from cattrs import Converter
>>> Converter().structure(2, str)
'2'
```

This overrides that, insisting on strict primitives.

{func}`~coolqlite.from_sql.configure_union_passthrough`
allows specifying `SqliteType` and its subsets for structuring,
e.g. `str | int`.

{func}`~coolqlite.from_sql.configure_converter_datetimes`
adds structure hooks for the various `datetype` temporal types,
and unions between their naive and aware counterparts.

If you want a hook for something that could be multiple
temporal types (e.g. something that accepts a date or a time),
you must add the hook yourself.