Fix emulator build error
[platform/framework/web/chromium-efl.git] / sql / README.md
1 # SQLite abstraction layer
2
3 [TOC]
4
5 ## SQLite for system designers
6
7 [SQLite](https://www.sqlite.org/) is a
8 [relational database management system (RDBMS)](https://en.wikipedia.org/wiki/Relational_database#RDBMS)
9 that [supports most of SQL](https://www.sqlite.org/lang.html).
10
11 SQLite is architected as a library that can be embedded in another application,
12 such as Chrome. SQLite runs in the application's process, and shares its memory
13 and other resources. This is similar to embedded databases like
14 [LevelDB](https://github.com/google/leveldb) and
15 [BerkeleyDB](https://en.wikipedia.org/wiki/Berkeley_DB). By contrast, most
16 popular RDMBSes, like [PostgreSQL](https://www.postgresql.org/) and
17 [MySQL](https://www.mysql.com/), are structured as standalone server processes
18 that accept queries from client processes.
19
20 TODO: Explain the process model and locking
21
22 TODO: Explain Chrome decisions -- exclusive locking, full per-feature isolation
23 (separate databases and page caches)
24
25
26 ## SQLite for database designers
27
28 The section summarizes aspects of SQLite that are relevant to schema and
29 query design, and may be surprising to readers with prior experience in other
30 popular SQL database systems, such as
31 [PostgreSQL](https://www.postgresql.org/) and [MySQL](https://www.mysql.com/).
32
33
34 ### Data storage model {#storage-model}
35
36 The main bottleneck in SQLite database performance is usually disk I/O. So,
37 designing schemas that perform well requires understanding how SQLite stores
38 data on disk.
39
40 At a very high level, a SQLite database is a forest of
41 [B-trees](https://en.wikipedia.org/wiki/B-tree), some of which are
42 [B+-trees](https://en.wikipedia.org/wiki/B%2B_tree). The database file is an
43 array of fixed-size pages, where each page stores a B-tree node. The page size
44 can only be set when a database file is created, and impacts both SQL statement
45 execution speed, and memory consumption.
46
47 The data in each table (usually called *rows*, *records*, or *tuples*) is stored
48 in a separate B-tree. The data in each index (called *entries*, *records* or
49 *tuples*) is also stored in a separate B-tree. So, each B-tree is associated
50 with exactly one table. The [*Indexing* section](#indexing-model) goes into
51 further details.
52
53 Each B-tree node stores multiple tuples of values. The values and their
54 encodings are described in the [*Value types* section](#data-types).
55
56 Tying everything together: The performance of a SQL statement is roughly the
57 number of database pages touched (read / written) by the statement. These pages
58 are nodes belonging to the B-trees associated with the tables mentioned in the
59 statement. The number of pages touched when accessing a B-tree depends on the
60 B-tree's depth. Each B-tree's depth depends on its record count (number of
61 records stored in it), and on its node width (how many records fit in a node).
62
63
64 #### Value types {#data-types}
65
66 SQLite stores values using
67 [5 major types](https://www.sqlite.org/datatype3.html), which are summarized
68 below.
69
70 1. NULL is a special type for the `NULL` value.
71
72 2. INTEGER represents big-endian twos-complement integers. Boolean values
73    (`TRUE` and `FALSE`) are represented as the integer values 1 and 0.
74
75 3. REAL represents IEEE 754-2008 64-bit floating point numbers.
76
77 4. TEXT represents strings (sequences of characters) encoded using a
78    [supported SQLite encoding](https://www.sqlite.org/c3ref/c_any.html). These
79    values are
80    [sorted](https://www.sqlite.org/datatype3.html#sort_order) according to
81    [a collating sequence](https://www.sqlite.org/datatype3.html#collation) or
82    [a collating function](https://www.sqlite.org/c3ref/create_collation.html).
83
84 5. BLOB represents sequences of bytes that are opaque to SQLite. These values are
85    sorted using the bitwise binary comparison offered by
86    [memcmp](https://en.cppreference.com/w/cpp/string/byte/memcmp).
87
88 SQLite stores index keys and row values (records / tuples) using
89 [a tightly packed format](https://sqlite.org/fileformat2.html#record_format)
90 that makes heavy use of [varints](https://sqlite.org/fileformat2.html#varint)
91 and variable-length fields. The column types have almost no influence on the
92 encoding of values. This has the following consequences.
93
94 * All SQL integer types, such as `TINYINT` and `BIGINT`, are treated as aliases
95   for `INTEGER`.
96 * All SQL non-integer numeric types, such as `DECIMAL`, `FLOAT`, and
97   `DOUBLE PRECISION` are treated as aliases for `REAL`.
98 * Numeric precision and scale specifiers, such as `DECIMAL(5,2)` are ignored.
99 * All string types, such as `CHAR`, `CHARACTER VARYING`, `VARCHAR`, and `CLOB`,
100   are treated as aliases for `TEXT`.
101 * Maximum string length specifiers, such as `CHAR(255)` are ignored.
102
103 SQLite uses clever heuristics, called
104 [type affinity](https://www.sqlite.org/datatype3.html#type_affinity),
105 to map SQL column types such as `VARCHAR` to the major types above.
106
107 Chrome database schemas should avoid type affinity, and should not include any
108 information ignored by SQLite.
109
110
111 #### Indexing {#indexing-model}
112
113 SQLite [uses B-trees](https://www.sqlite.org/fileformat2.html#pages) to store
114 both table and index data.
115
116 The exclusive use of B-trees reduces the amount of schema design decisions.
117 Notable examples:
118
119 * There is no equivalent to
120   [PostgreSQL's index types](https://www.postgresql.org/docs/13/indexes-types.html).
121   In particular, since there are no hashed indexes, the design does not need to
122   consider whether the index only needs to support equality queries, as opposed
123   to greater/smaller than comparisons.
124
125 * There is no equivalent to
126   [PostgreSQL's table access methods](https://www.postgresql.org/docs/13/tableam.html).
127   Each table is clustered by a primary key index, which is implicitly stored in
128   the table's B-tree.
129
130 By default, table rows (records / tuples) are stored in a B-tree keyed by
131 [rowid](https://sqlite.org/lang_createtable.html#rowid), an automatically
132 assigned 64-bit integer key. Effectively, these tables are clustered by rowid,
133 which acts as an implicit primary key. Opting out of this SQLite-specific
134 default requires appending
135 [`WITHOUT ROWID`](https://sqlite.org/withoutrowid.html) to the `CREATE TABLE`
136 instruction.
137
138 SQLite's [B-tree page format](https://sqlite.org/fileformat2.html#b_tree_pages)
139 has optimized special cases for tables clustered by rowid. This makes rowid the
140 most efficient [surrogate key](https://en.wikipedia.org/wiki/Surrogate_key)
141 implementation in SQLite. To make this optimization easier to use, any column
142 that is a primary key and has an `INTEGER` type is considered an alias for
143 rowid.
144
145 Each SQLite index
146 [is stored in a B-tree](https://sqlite.org/fileformat2.html#representation_of_sql_indices).
147 Each index entry is stored as a B-tree node whose key is made up of the record's
148 index key column values, followed by the record's primary key column values.
149
150 `WITHOUT ROWID` table indexes can include primary key columns without additional
151 storage costs. This is because indexes for `WITHOUT ROWID` tables enjoy
152 [a space optimization](https://sqlite.org/fileformat2.html#representation_of_sql_indices)
153 where columns in both the primary key and the index key are not stored twice in
154 B-tree nodes. Note that data in such tables cannot be recovered by `sql::Recovery`.
155
156
157 ### Statement execution model {#query-model}
158
159 At [a very high level](https://www.sqlite.org/arch.html), SQLite compiles SQL
160 statements (often called *queries*) into bytecode executed by a virtual machine
161 called the VDBE, or [the bytecode engine](https://www.sqlite.org/opcode.html).
162 A compiled statement can be executed multiple times, amortizing the costs of
163 query parsing and planning. Chrome's SQLite abstraction layer makes it easy to
164 use compiled queries.
165
166 Assuming effective use of cached statements, the performance of a SQL statement
167 comes down to the *query plan* that SQLite generates for the statement. The
168 query plan is the sequence of B-tree accesses used to execute the statement,
169 which determines the number of B-tree pages touched.
170
171 The rest of this section summarizes the following SQLite documentation pages.
172
173 1. [query planner overview](https://www.sqlite.org/queryplanner.html)
174 2. [query optimizer overview](https://www.sqlite.org/optoverview.html)
175 3. [`EXPLAIN QUERY PLAN` output description](https://www.sqlite.org/eqp.html)
176
177 At a high level, a SQLite query plan is a sequence of **nested** loops, where
178 each loop iterates over the data in a B-tree. Each loop can use the current
179 record of the outer loops.
180
181 TODO: Complete this section. Cover joins, sorting, etc.
182
183 #### Getting SQLite's query plans
184
185 Ideally, the SQL schemas and statements used by Chrome features would be simple
186 enough that the query plans would be obvious to the reader.
187
188 When this isn't the case, the fastest way to get the query plan is to load the
189 schema in [the SQLite shell](https://sqlite.org/cli.html), and use
190 [`EXPLAIN QUERY PLAN`](https://www.sqlite.org/eqp.html).
191
192 The following command builds a SQLite shell that uses Chrome's build of SQLite,
193 and supports the `EXPLAIN QUERY PLAN` command.
194
195 ```sh
196 autoninja -C out/Default sqlite_dev_shell
197 ```
198
199 Inside the SQLite shell, the `.eqp on` directive automatically shows the results
200 of `EXPLAIN QUERY PLAN` for every SQL statement executed in the shell.
201
202
203 #### Query steps {#query-step-types}
204
205 Query steps are the building blocks of SQLite query plans. Each query step is
206 essentially a loop that iterates over the records in a B-tree. These loops
207 differ in terms of how many B-tree pages they touch, and how many records they
208 produce. This sub-section lists the types of steps implemented by SQLite.
209
210 ##### Scans
211
212 Scans visit an entire (table or index) B-tree. For this reason, scans are almost
213 never acceptable in Chrome. Most of our features don't have limits on the amount
214 of stored data, so scans can result in an unbounded amount of I/O.
215
216 A *table scan* visits the entire table's B-tree.
217
218 A *covering index scan* visits an entire index B-tree, but doesn't access the
219 associated table B-tree.
220
221 SQLite doesn't have any special optimization for `COUNT(*)` queries. In other
222 words, SQLite does not track subtree sizes in its B-tree nodes.
223
224 Reviewers sometimes emphasize performance issues by calling the scans *full*
225 table scans and *full* index scans, where "full" references the fact that the
226 number of B-tree pages accessed is proportional to the entire data set stored on
227 disk.
228
229 TODO: Complete this section. Add examples in a way that doesn't make the section
230 overly long.
231
232 ##### Searches
233
234 Searches access a subset of a (table or index) B-tree nodes. Searches limit the
235 amount of nodes they need to access based on query restrictions, such as terms
236 in the `WHERE` clause. Seeing a `SEARCH` in a query plan is not a guarantee of
237 performance. Searches can vary wildly in the amount of B-tree pages they need to
238 access.
239
240 One of the fastest possible searches is a *table search* that performs exactly
241 one B-tree lookup, and produces at most one record.
242
243 The other fastest possible search is a *covering index search* that also
244 performs one lookup, and produces at most one record.
245
246 TODO: Complete this section. Add examples in a way that doesn't make the section
247 overly long.
248
249
250 ## General advice
251
252 The following pieces of advice usually come up in code reviews.
253
254
255 ### Quickly iterating on SQL statements
256
257 [The SQLite shell](https://sqlite.org/cli.html) offers quick feedback for
258 converging on valid SQL statement syntax, and avoiding SQLite features that are
259 disabled in Chrome. In addition, the
260 [`EXPLAIN`](https://www.sqlite.org/lang_explain.html) and
261 [`EXPLAIN QUERY PLAN`](https://www.sqlite.org/eqp.html) statements show the
262 results of SQLite's query planner and optimizer, which are very helpful for
263 reasoning about the performance of complex queries. The SQLite shell directive
264 `.eqp on` automatically issues `EXPLAIN QUERY PLAN` for all future commands.
265
266
267 The following commands set up SQLite shells using Chrome's build of SQLite.
268
269 ```sh
270 autoninja -C out/Default sqlite_shell sqlite_dev_shell
271 ```
272
273 * `sqlite_shell` runs the SQLite build that we ship in Chrome. It offers the
274   ground truth on whether a SQL statement can be used in Chrome code or not.
275 * `sqlite_dev_shell` enables the `EXPLAIN` and `EXPLAIN QUERY PLAN` statements,
276   as well as a few features used by [Perfetto](https://perfetto.dev/)'s analysis
277   tools.
278
279
280 ### SQL style
281
282 SQLite queries are usually embedded as string literals in C++ code. The
283 advice here has the following goals.
284
285 1. Easy to read queries. The best defense against subtle bugs is making the
286    queries very easy to read, so that any bugs become obvious at code review
287    time. SQL string literals don't benefit from our code analysis
288    infrastructure, so the only lines of defense against bugs are testing and
289    code review.
290
291 2. Simplify crash debugging. We will always have a low volume of non-actionable
292    crash reports, because Chrome runs on billions of devices, some of which have
293    faulty RAM or processors.
294
295 3. No unnecessary performance overheads. The C++ optimizer doesn't understand
296    SQL query literals, so the queries end up as written in the Chrome binary.
297    Extra characters cost binary size, as well as CPU time (which turns into
298    battery usage) during query parsing.
299
300 4. Match the embedding language (C++) style guide. This reduces the mental
301    context switch overhead for folks who write and/or review C++ code that
302    contains SQL.
303
304 Format statements like so.
305
306 ```cc
307   static constexpr char kOriginInfoSql[] =
308       // clang-format off
309       "CREATE TABLE origin_infos("
310           "origin TEXT NOT NULL,"
311           "last_modified INTEGER NOT NULL,"
312           "secure INTEGER NOT NULL)";
313   // clang-format on
314
315   static constexpr char kInsertSql[] =
316       // clang-format off
317       "INSERT INTO infos(origin,last_modified,secure) "
318           "VALUES(?,?,?)";
319   // clang-format on
320
321   static constexpr char kSelectSql[] =
322       // clang-format off
323       "SELECT origin,last_modified,secure FROM origins "
324           "WHERE last_modified>? "
325           "ORDER BY last_modified";
326   // clang-format on
327 ```
328
329 * [SQLite keywords](https://sqlite.org/lang_keywords.html) should use ALL CAPS.
330   This makes SQL query literals easier to distinguish and search for.
331
332 * Identifiers, such as table and row names, should use snake_case.
333
334 * Identifiers, keywords, and parameter placeholders (`?`) should be separated by
335   exactly one character. Separators may be spaces (` `), commas (`,`), or
336   parentheses (`(`, `)`).
337
338 * Statement-ending semicolons (`;`) are omitted.
339
340 * SQL statements are stored in variables typed `static constexpr char[]`, or in
341   string literals passed directly to methods.
342
343 * [`INSERT` statements](https://sqlite.org/lang_insert.html) should list all the
344   table columns by name, in the same order as the corresponding `CREATE TABLE`
345   statements.
346
347 * [`SELECT` statements](https://sqlite.org/lang_select.html) should list the
348   desired table columns by name, in the same order as the corresponding
349   `CREATE TABLE` statements. `SELECT *` is strongly discouraged, at least until
350   we have schema checks on database opens.
351
352 * [`SELECT` statements](https://sqlite.org/lang_select.html) that retrieve more
353   than one row should include an
354   [`ORDER BY` clause](https://sqlite.org/lang_select.html#the_order_by_clause)
355   to clarify the implicit ordering.
356   * SELECTs whose outer loop is a table search or table scan implicitly order
357     results by [rowid](https://sqlite.org/lang_createtable.html#rowid) or, in
358     the case of [`WITHOUT ROWID`](https://sqlite.org/withoutrowid.html) tables,
359     by the table's primary key.
360   * SELECTs whose outer loop is an index scan or index search order results
361     according to that index.
362
363 * [`CREATE INDEX` statements](https://sqlite.org/lang_createindex.html) should
364   immediately follow the
365   [`CREATE TABLE` statement](https://sqlite.org/lang_createtable.html) for the
366   indexed table.
367
368 * Explicit `CREATE UNIQUE INDEX` statements should be preferred to
369   [`UNIQUE` constraints on `CREATE TABLE`](https://sqlite.org/lang_createtable.html#unique_constraints).
370
371 * Values must either be embedded in the SQL statement string literal, or bound
372   using [parameters](https://www.sqlite.org/lang_expr.html#varparam).
373
374 * Parameter placeholders should always use the `?` syntax. Alternative syntaxes,
375   such as `?NNN` or `:AAAA`, have few benefits in a codebase where the `Bind`
376   statements are right next to the queries, and are less known to readers.
377
378 * SQL statements should be embedded in C++ as string literals. The `char[]` type
379   makes it possible for us to compute query length at compile time in the
380   future. The `static` and `constexpr` qualifiers both ensure optimal code
381   generation.
382
383 * Do not execute multiple SQL statements (e.g., by calling `Step()` or `Run()`
384   on `sql::Statement`) on the same C++ line. It's difficult to get more than
385   line numbers from crash reports' stack traces.
386
387
388 ### Schema style
389
390 Identifiers (table / index / column names and aliases) must not be
391 [current SQLite keywords](https://sqlite.org/lang_keywords.html). Identifiers
392 may not start with the `sqlite_` prefix, to avoid conflicting with the name of a
393 [SQLite internal schema object](https://www.sqlite.org/fileformat2.html#storage_of_the_sql_database_schema).
394
395 Column types should only be one of the the SQLite storage types (`INTEGER`,
396 `REAL`, `TEXT`, `BLOB`), so readers can avoid reasoning about SQLite's type
397 affinity.
398
399 Columns that will store boolean values should have the `INTEGER` type.
400
401 Columns that will store `base::Time` values should have the `INTEGER` type.
402 Values should be serialized using `sql::Statement::BindTime()` and deserialized
403 using `sql::Statement::ColumnTime()`.
404
405 Column types should not include information ignored by SQLite, such as numeric
406 precision or scale specifiers, or string length specifiers.
407
408 Columns should have
409 [`NOT NULL` constraints](https://sqlite.org/lang_createtable.html#not_null_constraints)
410 whenever possible. This saves maintainers from having to reason about the less
411 intuitive cases of [`NULL` handling](https://sqlite.org/nulls.html).
412
413 `NOT NULL` constraints must be explicitly stated in column definitions that
414 include `PRIMARY KEY` specifiers. For historical reasons, SQLite
415 [allows NULL primary keys](https://sqlite.org/lang_createtable.html#the_primary_key)
416 in most cases.  When a table's primary key is composed of multiple columns,
417 each column's definition should have a `NOT NULL` constraint.
418
419 Columns should avoid `DEFAULT` values. Columns that have `NOT NULL` constraints
420 and lack a `DEFAULT` value are easier to review and maintain, as SQLite takes
421 over the burden of checking that `INSERT` statements aren't missing these
422 columns.
423
424 Surrogate primary keys should use the column type `INTEGER PRIMARY KEY`, to take
425 advantage of SQLite's rowid optimizations.
426 [`AUTOINCREMENT`](https://www.sqlite.org/autoinc.html) should only be used where
427 primary key reuse would be unacceptable.
428
429
430 ### Discouraged features
431
432 SQLite exposes a vast array of functionality via SQL statements. The following
433 features are not a good match for SQL statements used by Chrome feature code.
434
435 #### PRAGMA statements {#no-pragmas}
436
437 [`PRAGMA` statements](https://www.sqlite.org/pragma.html) should never be used
438 directly. Chrome's SQLite abstraction layer should be modified to support the
439 desired effects instead.
440
441 Direct `PRAGMA` use limits our ability to customize and secure our SQLite build.
442 `PRAGMA` statements may turn on code paths with less testing / fuzzing coverage.
443 Furthermore, some `PRAGMA` statements invalidate previously compiled queries,
444 reducing the efficiency of Chrome's compiled query cache.
445
446 #### Virtual tables {#no-virtual-tables}
447
448 [`CREATE VIRTUAL TABLE` statements](https://www.sqlite.org/vtab.html) should not
449 be used. The desired functionality should be implemented in C++, and access
450 storage using standard SQL statements.
451
452 Virtual tables are [SQLite's module system](https://www.sqlite.org/vtab.html).
453 SQL statements on virtual tables are essentially running arbitrary code, which
454 makes them very difficult to reason about and maintain. Furthermore, the virtual
455 table implementations don't receive the same level of fuzzing coverage as the
456 SQLite core.
457
458 Access to virtual tables is disabled by default for SQLite databases opened with
459 Chrome's `sql::Database` infrastructure. This is intended to steer feature
460 developers away from the discouraged feature.
461
462 Chrome's SQLite build has virtual table functionality reduced to the minimum
463 needed to support [FTS3](https://www.sqlite.org/fts3.html) in WebSQL, and an
464 internal feature.
465 [SQLite's run-time loading mechanism](https://www.sqlite.org/loadext.html) is
466 disabled, and most
467 [built-in virtual tables](https://www.sqlite.org/vtablist.html) are disabled as
468 well.
469
470 Ideally we would disable SQLite's virtual table support using
471 [SQLITE_OMIT_VIRTUALTABLE](https://sqlite.org/compile.html#omit_virtualtable)
472 once [WebSQL](https://www.w3.org/TR/webdatabase/) is removed from Chrome, but
473 virtual table support is required to use SQLite's [built-in corruption recovery
474 module](https://www.sqlite.org/recovery.html). The [SQLITE_DBPAGE virtual
475 table](https://www.sqlite.org/dbpage.html) is also enabled only for corruption
476 recovery and should not be used in Chrome.
477
478 #### Foreign key constraints {#no-foreign-keys}
479
480 [SQL foreign key constraints](https://sqlite.org/foreignkeys.html) should not be
481 used. All data validation should be performed using explicit `SELECT` statements
482 (generally wrapped as helper methods) inside transactions. Cascading deletions
483 should be performed using explicit `DELETE` statements inside transactions.
484
485 Chrome features cannot rely on foreign key enforcement, due to the
486 possibility of data corruption. Furthermore, foreign key constraints make it
487 more difficult to reason about system behavior (Chrome feature code + SQLite)
488 when the database gets corrupted. Foreign key constraints also make it more
489 difficult to reason about query performance.
490
491 As a result, foreign key constraints are not enforced on SQLite databases
492 opened with Chrome's `sql::Database` infrastructure.
493
494 After
495 [WebSQL](https://www.w3.org/TR/webdatabase/) is removed from Chrome, we plan
496 to disable SQLite's foreign key support using
497 [SQLITE_OMIT_FOREIGN_KEY](https://sqlite.org/compile.html#omit_foreign_key).
498
499 #### CHECK constraints {#no-checks}
500
501 [SQL CHECK constraints](https://sqlite.org/lang_createtable.html#check_constraints)
502 should not be used, for the same reasons as foreign key constraints. The
503 equivalent checks should be performed in C++, typically using `DCHECK`.
504
505 After
506 [WebSQL](https://www.w3.org/TR/webdatabase/) is removed from Chrome, we plan
507 to disable SQLite's CHECK constraint support using
508 [SQLITE_OMIT_CHECK](https://sqlite.org/compile.html#omit_check).
509
510 #### Triggers {#no-triggers}
511
512 [SQL triggers](https://sqlite.org/lang_createtrigger.html) should not be used.
513
514 Triggers significantly increase the difficulty of reviewing and maintaining
515 Chrome features that use them.
516
517 Triggers are not executed on SQLite databases opened with Chrome's
518 `sql::Database` infrastructure. This is intended to steer feature developers
519 away from the discouraged feature.
520
521 After [WebSQL](https://www.w3.org/TR/webdatabase/) is removed from Chrome, we
522 plan to disable SQLite's trigger support using
523 [SQLITE_OMIT_TRIGGER](https://sqlite.org/compile.html#omit_trigger).
524
525 #### Common Table Expressions {#no-ctes}
526
527 [SQL Common Table Expressions (CTEs)](https://sqlite.org/lang_with.html) should
528 not be used. Chrome's SQL schemas and queries should be simple enough that
529 the factoring afforded by
530 [ordinary CTEs](https://sqlite.org/lang_with.html#ordinary_common_table_expressions)
531 is not necessary.
532 [Recursive CTEs](https://sqlite.org/lang_with.html#recursive_common_table_expressions)
533 should be implemented in C++.
534
535 Common Table Expressions do not open up any query optimizations that would not
536 be available otherwise, and make it more difficult to review / analyze queries.
537
538 #### Views {#no-views}
539
540 SQL views, managed by the
541 [`CREATE VIEW` statement](https://www.sqlite.org/lang_createview.html) and the
542 [`DROP VIEW` statement](https://www.sqlite.org/lang_dropview.html), should not
543 be used. Chrome's SQL schemas and queries should be simple enough that the
544 factoring afforded by views is not necessary.
545
546 Views are syntactic sugar, and do not open up any new SQL capabilities. SQL
547 statements on views are more difficult to understand and maintain, because of
548 the extra layer of indirection.
549
550 Access to views is disabled by default for SQLite databases opened with Chrome's
551 `sql::Database` infrastructure. This is intended to steer feature developers
552 away from the discouraged feature.
553
554 After
555 [WebSQL](https://www.w3.org/TR/webdatabase/) is removed from Chrome, we plan
556 to disable SQLite's VIEW support using
557 [SQLITE_OMIT_VIEW](https://www.sqlite.org/compile.html#omit_view).
558
559 #### Double-quoted string literals {#no-double-quoted-strings}
560
561 String literals should always be single-quoted. That being said, string literals
562 should be rare in Chrome code, because any user input must be injected using
563 statement parameters and the `Statement::Bind*()` methods.
564
565 Double-quoted string literals are non-standard SQL syntax. The SQLite authors
566 [currently consider this be a misfeature](https://www.sqlite.org/quirks.html#double_quoted_string_literals_are_accepted).
567
568 SQLite support for double-quoted string literals is disabled for databases
569 opened with Chrome's `sql::Database` infrastructure. This is intended to steer
570 feature developers away from this discouraged feature.
571
572 After
573 [WebSQL](https://www.w3.org/TR/webdatabase/) is removed from Chrome, we plan
574 to disable SQLite's support for double-quoted string literals using
575 [SQLITE_DQS=0](https://www.sqlite.org/compile.html#dqs).
576
577 #### Compound SELECT statements {#no-compound-queries}
578
579 [Compound SELECT statements](https://www.sqlite.org/lang_select.html#compound_select_statements)
580 should not be used. Such statements should be broken down into
581 [simple SELECT statements](https://www.sqlite.org/lang_select.html#simple_select_processing),
582 and the operators `UNION`, `UNION ALL`, `INTERSECT` and `EXCEPT` should be
583 implemented in C++.
584
585 A single compound SELECT statement is more difficult to review and properly
586 unit-test than the equivalent collection of simple SELECT statements.
587 Furthermore, the compound SELECT statement operators can be implemented more
588 efficiently in C++ than in SQLite's bytecode interpreter (VDBE).
589
590 After
591 [WebSQL](https://www.w3.org/TR/webdatabase/) is removed from Chrome, we plan
592 to disable SQLite's compound SELECT support using
593 [SQLITE_OMIT_COMPOUND_SELECT](https://www.sqlite.org/compile.html#omit_compound_select).
594
595 #### Built-in functions {#no-builtin-functions}
596
597 SQLite's [built-in functions](https://sqlite.org/lang_corefunc.html) should be
598 only be used in SQL statements where they unlock significant performance
599 improvements. Chrome features should store data in a format that leaves the most
600 room for query optimizations, and perform any necessary transformations after
601 reading / before writing the data.
602
603 * [Aggregation functions](https://sqlite.org/lang_aggfunc.html) are best
604   replaced with C++ code that iterates over rows and computes the desired
605   results.
606 * [Date and time functions](https://sqlite.org/lang_datefunc.html) are best
607   replaced by `base::Time` functionality.
608 * String-processing functions, such as
609   [`printf()`](https://sqlite.org/printf.html) and `trim()` are best replaced
610   by C++ code that uses the helpers in `//base/strings/`.
611 * Wrappers for [SQLite's C API](https://sqlite.org/c3ref/funclist.html), such as
612   `changes()`, `last_insert_rowid()`, and `total_changes()`, are best replaced
613   by functionality in `sql::Database` and `sql::Statement`.
614 * SQLite-specific functions, such as  `sqlite_source_id()` and
615   `sqlite_version()` should not be necessary in Chrome code, and may suggest a
616   problem in the feature's design.
617
618 [Math functions](https://sqlite.org/lang_mathfunc.html) and
619 [Window functions](https://sqlite.org/windowfunctions.html#biwinfunc) are
620 disabled in Chrome's SQLite build.
621
622 #### ATTACH DATABASE statements {#no-attach}
623
624 [`ATTACH DATABASE` statements](https://www.sqlite.org/lang_attach.html) should
625 not be used. Each Chrome feature should store its data in a single database.
626 Chrome code should not assume that transactions across multiple databases are
627 atomic.
628
629 We plan to remove all existing `ATTACH DATABASE` use from Chrome.
630
631
632 ### Disabled features
633
634 We aim to disable SQLite features that should not be used in Chrome, subject to
635 the constraint of keeping WebSQL's feature set stable. We currently disable all
636 new SQLite features, to avoid expanding the attack surface exposed to WebSQL.
637 This stance may change once WebSQL is removed from Chrome.
638
639 The following SQLite features have been disabled in Chrome.
640
641 #### JSON
642
643 Chrome features should prefer
644 [procotol buffers](https://developers.google.com/protocol-buffers) to JSON for
645 on-disk (persistent) serialization of extensible structured data.
646
647 Chrome features should store the values used by indexes directly in their own
648 columns, instead of relying on
649 [SQLite's JSON support](https://www.sqlite.org/json1.html).
650
651 #### UPSERT
652
653 [SQLite's UPSERT implementation](https://www.sqlite.org/lang_UPSERT.html) has
654 been disabled in order to avoid increasing WebSQL's attack surface. UPSERT is
655 disabled using the `SQLITE_OMIT_UPSERT` macro, which is not currently included
656 in [the SQLite compile-time option list](https://www.sqlite.org/compile.html),
657 but exists in the source code.
658
659 We currently think that the new UPSERT functionality is not essential to
660 implementing Chrome features efficiently. An example where UPSERT is necessary
661 for the success of a Chrome feature would likely get UPSERT enabled.
662
663 #### Window functions
664
665 [Window functions](https://sqlite.org/windowfunctions.html#biwinfunc) have been
666 disabled primarily because they cause a significant binary size increase, which
667 leads to a corresponding large increase in the attack surface exposed to WebSQL.
668
669 Window functions increase the difficulty of reviewing and maintaining the Chrome
670 features that use them, because window functions add complexity to the mental
671 model of query performance.
672
673 We currently think that this maintenance overhead of window functions exceeds
674 any convenience and performance benefits (compared to simpler queries
675 coordinated in C++).