An Ecto SQLite3 adapter.
Reflow documentation to around the 88-90 column
Matthew Johnston
(Nov 4, 2024, 8:00 AM -0600)
c330935d
97c9cb40
+84
-71
+84
-71
lib/ecto/adapters/sqlite3.ex
+84
-71
lib/ecto/adapters/sqlite3.ex
···
13
13
14
14
* `:database` - The path to the database. In memory is allowed. You can use
15
15
`:memory` or `":memory:"` to designate that.
16
-
* `:default_transaction_mode` - one of `deferred` (default), `immediate`,
17
-
or `exclusive`. If a mode is not specified in a call to `Repo.transaction/2`,
18
-
this will be the default transaction mode.
19
-
* `:journal_mode` - Sets the journal mode for the sqlite connection. Can be
20
-
one of the following `:delete`, `:truncate`, `:persist`, `:memory`,
21
-
`:wal`, or `:off`. Defaults to `:wal`.
22
-
* `:temp_store` - Sets the storage used for temporary tables. Default is
23
-
`:default`. Allowed values are `:default`, `:file`, `:memory`.
24
-
* `:synchronous` - Can be `:extra`, `:full`, `:normal`, or `:off`. Defaults
25
-
to `:normal`.
26
-
* `:foreign_keys` - Sets if foreign key checks should be enforced or not.
27
-
Can be `:on` or `:off`. Default is `:on`.
28
-
* `:cache_size` - Sets the cache size to be used for the connection. This is
29
-
an odd setting as a positive value is the number of pages in memory to use
30
-
and a negative value is the size in kilobytes to use. Default is `-64000`.
31
-
* `:cache_spill` - The cache_spill pragma enables or disables the ability of
32
-
the pager to spill dirty cache pages to the database file in the middle of
33
-
a transaction. By default it is `:on`, and for most applications, it
34
-
should remain so.
16
+
* `:default_transaction_mode` - one of `:deferred` (default), `:immediate`, or
17
+
`:exclusive`. If a mode is not specified in a call to `Repo.transaction/2`, this
18
+
will be the default transaction mode.
19
+
* `:journal_mode` - Sets the journal mode for the sqlite connection. Can be one of
20
+
the following `:delete`, `:truncate`, `:persist`, `:memory`, `:wal`, or `:off`.
21
+
Defaults to `:wal`.
22
+
* `:temp_store` - Sets the storage used for temporary tables. Default is `:default`.
23
+
Allowed values are `:default`, `:file`, `:memory`.
24
+
* `:synchronous` - Can be `:extra`, `:full`, `:normal`, or `:off`. Defaults to `:normal`.
25
+
* `:foreign_keys` - Sets if foreign key checks should be enforced or not. Can be
26
+
`:on` or `:off`. Default is `:on`.
27
+
* `:cache_size` - Sets the cache size to be used for the connection. This is an odd
28
+
setting as a positive value is the number of pages in memory to use and a negative
29
+
value is the size in kilobytes to use. Default is `-64000`.
30
+
* `:cache_spill` - The cache_spill pragma enables or disables the ability of the
31
+
pager to spill dirty cache pages to the database file in the middle of a
32
+
transaction. By default it is `:on`, and for most applications, it should remain
33
+
so.
35
34
* `:case_sensitive_like` - whether LIKE is case-sensitive or not. Can be
36
35
`:off` or `:on`. Defaults to `:off`.
37
-
* `:auto_vacuum` - Defaults to `:none`. Can be `:none`, `:full` or
38
-
`:incremental`. Depending on the database size, `:incremental` may be
39
-
beneficial.
36
+
* `:auto_vacuum` - Defaults to `:none`. Can be `:none`, `:full` or `:incremental`.
37
+
Depending on the database size, `:incremental` may be beneficial.
40
38
* `:locking_mode` - Defaults to `:normal`. Allowed values are `:normal` or
41
39
`:exclusive`. See [sqlite documentation][1] for more information.
42
-
* `:secure_delete` - Defaults to `:off`. Can be `:off` or `:on`. If `:on`, it will cause SQLite3
43
-
to overwrite records that were deleted with zeros.
44
-
* `:wal_auto_check_point` - Sets the write-ahead log auto-checkpoint
45
-
interval. Default is `1000`. Setting the auto-checkpoint size to zero or a
46
-
negative value turns auto-checkpointing off.
40
+
* `:secure_delete` - Defaults to `:off`. Can be `:off` or `:on`. If `:on`, it will
41
+
cause SQLite3 to overwrite records that were deleted with zeros.
42
+
* `:wal_auto_check_point` - Sets the write-ahead log auto-checkpoint interval.
43
+
Default is `1000`. Setting the auto-checkpoint size to zero or a negative value
44
+
turns auto-checkpointing off.
47
45
* `:busy_timeout` - Sets the busy timeout in milliseconds for a connection.
48
46
Default is `2000`.
49
47
* `:pool_size` - the size of the connection pool. Defaults to `5`.
50
-
* `:binary_id_type` - Defaults to `:string`. Determines how binary IDs are stored in the database and the type of
51
-
`:binary_id` columns. See the [section on binary ID types](#module-binary-id-types) for more details.
52
-
* `:uuid_type` - Defaults to `:string`. Determines the type of `:uuid` columns. Possible values and
53
-
column types are the same as for [binary IDs](#module-binary-id-types).
54
-
* `:datetime_type` - Defaults to `:iso8601`. Determines how datetime fields are stored in the database.
55
-
The allowed values are `:iso8601` and `:text_datetime`. `:iso8601` corresponds to a string of the form
56
-
`YYYY-MM-DDThh:mm:ss` and `:text_datetime` corresponds to a string of the form `YYYY-MM-DD hh:mm:ss`
57
-
* `:load_extensions` - list of paths identifying extensions to load. Defaults to []. The provided list will
58
-
be merged with the global extensions list, set on :exqlite, :load_extensions. Be aware that the path should
59
-
handle pointing to a library compiled for the current architecture. See `Exqlite.Connection.connect/1` for more.
48
+
* `:binary_id_type` - Defaults to `:string`. Determines how binary IDs are stored in
49
+
the database and the type of `:binary_id` columns. See the
50
+
[section on binary ID types](#module-binary-id-types) for more details.
51
+
* `:uuid_type` - Defaults to `:string`. Determines the type of `:uuid` columns.
52
+
Possible values and column types are the same as for
53
+
[binary IDs](#module-binary-id-types).
54
+
* `:datetime_type` - Defaults to `:iso8601`. Determines how datetime fields are
55
+
stored in the database. The allowed values are `:iso8601` and `:text_datetime`.
56
+
`:iso8601` corresponds to a string of the form `YYYY-MM-DDThh:mm:ss` and
57
+
`:text_datetime` corresponds to a string of the form `YYYY-MM-DD hh:mm:ss`
58
+
* `:load_extensions` - list of paths identifying extensions to load. Defaults to `[]`.
59
+
The provided list will be merged with the global extensions list, set on
60
+
`:exqlite, :load_extensions`. Be aware that the path should handle pointing to a
61
+
library compiled for the current architecture. See `Exqlite.Connection.connect/1`
62
+
for more.
60
63
61
64
For more information about the options above, see [sqlite documentation][1]
62
65
63
66
### Differences between SQLite and Ecto SQLite defaults
64
67
65
68
For the most part, the defaults we provide above match the defaults that SQLite usually
66
-
ships with. However, SQLite has conservative defaults due to its need to be strictly backwards
67
-
compatible, so some of them do not necessarily match "best practices". Below are the defaults
68
-
we provide above that differ from the normal SQLite defaults, along with rationale.
69
+
ships with. However, SQLite has conservative defaults due to its need to be strictly
70
+
backwards compatible, so some of them do not necessarily match "best practices". Below
71
+
are the defaults we provide above that differ from the normal SQLite defaults, along
72
+
with rationale.
69
73
70
74
* `:journal_mode` - we use `:wal`, as it is vastly superior
71
75
for concurrent access. SQLite usually defaults to `:delete`.
···
87
91
88
92
### Binary ID types
89
93
90
-
The `:binary_id_type` configuration option allows configuring how `:binary_id` fields are stored in the database as
91
-
well as the type of the column in which these IDs will be stored. The possible values are:
94
+
The `:binary_id_type` configuration option allows configuring how `:binary_id` fields
95
+
are stored in the database as well as the type of the column in which these IDs will
96
+
be stored. The possible values are:
92
97
* `:string` (default): IDs are stored as strings, and the type of the column is `TEXT`.
93
98
* `:binary`: IDs are stored in their raw binary form, and the type of the column is `BLOB`.
94
99
95
100
The main differences between the two formats are as follows:
96
-
* When stored as binary, UUIDs require much less space in the database. IDs stored as strings require 36 bytes each,
97
-
while IDs stored as binary only require 16 bytes.
98
-
* Because SQLite does not have a dedicated UUID type, most clients cannot represent UUIDs stored as binary in a human
99
-
readable format. Therefore, IDs stored as strings may be easier to work with if manual manipulation is required.
101
+
* When stored as binary, UUIDs require much less space in the database. IDs stored as
102
+
strings require 36 bytes each, while IDs stored as binary only require 16 bytes.
103
+
* Because SQLite does not have a dedicated UUID type, most clients cannot represent
104
+
UUIDs stored as binary in a human readable format. Therefore, IDs stored as strings
105
+
may be easier to work with if manual manipulation is required.
100
106
101
107
## Limitations and caveats
102
108
···
116
122
### Async Sandbox testing
117
123
118
124
The Ecto SQLite3 adapter does not support async tests when used with
119
-
`Ecto.Adapters.SQL.Sandbox`. This is due to SQLite only allowing up one
120
-
write transaction at a time, which often does not work with the Sandbox approach of
121
-
wrapping each test in a transaction.
125
+
`Ecto.Adapters.SQL.Sandbox`. This is due to SQLite only allowing up one write
126
+
transaction at a time, which often does not work with the Sandbox approach of wrapping
127
+
each test in a transaction.
122
128
123
129
### LIKE match on BLOB columns
124
130
125
-
We have the DSQLITE_LIKE_DOESNT_MATCH_BLOBS compile-time option set to true,
126
-
as [recommended][3] by SQLite. This means you cannot do LIKE queries on BLOB columns.
131
+
We have the DSQLITE_LIKE_DOESNT_MATCH_BLOBS compile-time option set to true, as
132
+
[recommended][3] by SQLite. This means you cannot do LIKE queries on BLOB columns.
127
133
128
134
### Case sensitivity
129
135
···
131
137
option outlined above.
132
138
133
139
However, for equality comparison, case sensitivity is always _on_.
134
-
If you want to make a column not be case sensitive, for email storage for example, you can
135
-
make it case insensitive by using the [`COLLATE NOCASE`][6] option in SQLite. This is configured
136
-
via the `:collate` option.
140
+
If you want to make a column not be case sensitive, for email storage for example, you
141
+
can make it case insensitive by using the [`COLLATE NOCASE`][6] option in SQLite. This
142
+
is configured via the `:collate` option.
137
143
138
144
So instead of:
139
145
···
145
151
146
152
### Check constraints
147
153
148
-
SQLite3 supports specifying check constraints on the table or on the column definition. We currently only
149
-
support adding a check constraint via a column definition, since the table definition approach only
150
-
works at table-creation time and cannot be added at table-alter time. You can see more information in
151
-
the SQLite3 [CREATE TABLE documentation](https://sqlite.org/lang_createtable.html).
154
+
SQLite3 supports specifying check constraints on the table or on the column definition.
155
+
We currently only support adding a check constraint via a column definition, since the
156
+
table definition approach only works at table-creation time and cannot be added at
157
+
table-alter time. You can see more information in the SQLite3
158
+
[CREATE TABLE documentation](https://sqlite.org/lang_createtable.html).
152
159
153
-
Because of this, you cannot add a constraint via the normal `Ecto.Migration.constraint/3` method, as that
154
-
operates via ALTER TABLE ADD CONSTRAINT, and this type of ALTER TABLE operation SQLite3 does not support.
155
-
You can however get the full functionality by adding a constraint at the column level, specifying the name
156
-
and expression. Per the SQLite3 documentation, there is no _functional_ difference between a column or table constraint.
160
+
Because of this, you cannot add a constraint via the normal `Ecto.Migration.constraint/3`
161
+
method, as that operates via `ALTER TABLE ADD CONSTRAINT`, and this type of `ALTER TABLE`
162
+
operation SQLite3 does not support. You can however get the full functionality by
163
+
adding a constraint at the column level, specifying the name and expression. Per the
164
+
SQLite3 documentation, there is no _functional_ difference between a column or table
165
+
constraint.
157
166
158
167
Thus, adding a check constraint for a new column is as simple as:
159
168
···
161
170
162
171
### Handling foreign key constraints in changesets
163
172
164
-
Unfortunately, unlike other databases, SQLite3 does not provide the precise name of the constraint violated,
165
-
but only the columns within that constraint (if it provides any information at all). Because of this, changeset
166
-
functions like `Ecto.Changeset.foreign_key_constraint/3` may not work at all.
173
+
Unfortunately, unlike other databases, SQLite3 does not provide the precise name of
174
+
the constraint violated, but only the columns within that constraint (if it provides
175
+
any information at all). Because of this, changeset functions like
176
+
`Ecto.Changeset.foreign_key_constraint/3` may not work at all.
167
177
168
-
This is because the above functions depend on the Ecto Adapter returning the name of the violated constraint,
169
-
which you annotate in your changeset so that Ecto can convert the constraint violation into the correct
170
-
updated changeset when the constraint is hit during a `m:Ecto.Repo.update/2` or `m:Ecto.Repo.insert/2` operation.
171
-
Since we cannot get the name of the violated constraint back from SQLite3 at `INSERT` or `UPDATE` time,
172
-
there is no way to effectively use these changeset functions. This is a SQLite3 limitation.
178
+
This is because the above functions depend on the Ecto Adapter returning the name of
179
+
the violated constraint, which you annotate in your changeset so that Ecto can convert
180
+
the constraint violation into the correct updated changeset when the constraint is hit
181
+
during a `c:Ecto.Repo.update/2` or `c:Ecto.Repo.insert/2` operation. Since we cannot
182
+
get the name of the violated constraint back from SQLite3 at `INSERT` or `UPDATE`
183
+
time, there is no way to effectively use these changeset functions. This is a SQLite3
184
+
limitation.
173
185
174
-
See [this GitHub issue](https://github.com/elixir-sqlite/ecto_sqlite3/issues/42) for more details.
186
+
See [this GitHub issue](https://github.com/elixir-sqlite/ecto_sqlite3/issues/42) for
187
+
more details.
175
188
176
189
### Schemaless queries
177
190