diff --git a/docs/table.rst b/docs/table.rst index 54ae523..27df299 100644 --- a/docs/table.rst +++ b/docs/table.rst @@ -6,14 +6,56 @@ Tables are accessed using the indexing operator, like so: .. code-block:: python - from sqlite_utils.db import Database + from sqlite_utils import Database import sqlite3 - database = Database(sqlite3.connect("my_database.db")) - table = database["my_table"] + db = Database(sqlite3.connect("my_database.db")) + table = db["my_table"] If the table does not yet exist, it will be created the first time you attempt to insert or upsert data into it. +Creating tables +=============== + +The easiest way to create a new table is to insert a record into it: + +.. code-block:: python + + from sqlite_utils import Database + import sqlite3 + + db = Database(sqlite3.connect("/tmp/dogs.db")) + dogs = db["dogs"] + dogs.insert({ + "name": "Cleo", + "twitter": "cleopaws", + "age": 3, + "is_good_dog": True, + }) + +This will automatically create a new table called "dogs" with the following schema:: + + CREATE TABLE dogs ( + name TEXT, + twitter TEXT, + age INTEGER, + is_good_dog INTEGER + ) + +The column types are automatically derived from the types of the incoming data. + +You can also specify a primary key by passing the ``pk=`` parameter to the ``.insert()`` call. This will only be obeyed if the record being inserted causes the table to be created: + +.. code-block:: python + + dogs.insert({ + "id": 1, + "name": "Cleo", + "twitter": "cleopaws", + "age": 3, + "is_good_dog": True, + }, pk="id") + Introspection ============= @@ -21,13 +63,22 @@ If you have loaded an existing table, you can use introspection to find out more >>> db["PlantType"] + +The ``.count`` property shows the current number of rows (``select count(*) from table``):: + >>> db["PlantType"].count 3 + >>> db["Street_Tree_List"].count + 189144 + +The ``.columns`` property shows the columns in the table:: + >>> db["PlantType"].columns [Column(cid=0, name='id', type='INTEGER', notnull=0, default_value=None, is_pk=1), Column(cid=1, name='value', type='TEXT', notnull=0, default_value=None, is_pk=0)] - >>> db["Street_Tree_List"].count - 189144 + +The ``.foreign_keys`` property shows if the table has any foreign key relationships:: + >>> db["Street_Tree_List"].foreign_keys [ForeignKey(table='Street_Tree_List', column='qLegalStatus', other_table='qLegalStatus', other_column='id'), ForeignKey(table='Street_Tree_List', column='qCareAssistant', other_table='qCareAssistant', other_column='id'), @@ -35,3 +86,33 @@ If you have loaded an existing table, you can use introspection to find out more ForeignKey(table='Street_Tree_List', column='qSpecies', other_table='qSpecies', other_column='id'), ForeignKey(table='Street_Tree_List', column='qCaretaker', other_table='qCaretaker', other_column='id'), ForeignKey(table='Street_Tree_List', column='PlantType', other_table='PlantType', other_column='id')] + +The ``.schema`` property outputs the table's schema as a SQL string:: + + >>> print(db["Street_Tree_List"].schema) + CREATE TABLE "Street_Tree_List" ( + "TreeID" INTEGER, + "qLegalStatus" INTEGER, + "qSpecies" INTEGER, + "qAddress" TEXT, + "SiteOrder" INTEGER, + "qSiteInfo" INTEGER, + "PlantType" INTEGER, + "qCaretaker" INTEGER, + "qCareAssistant" INTEGER, + "PlantDate" TEXT, + "DBH" INTEGER, + "PlotSize" TEXT, + "PermitNotes" TEXT, + "XCoord" REAL, + "YCoord" REAL, + "Latitude" REAL, + "Longitude" REAL, + "Location" TEXT + , + FOREIGN KEY ("PlantType") REFERENCES [PlantType](id), + FOREIGN KEY ("qCaretaker") REFERENCES [qCaretaker](id), + FOREIGN KEY ("qSpecies") REFERENCES [qSpecies](id), + FOREIGN KEY ("qSiteInfo") REFERENCES [qSiteInfo](id), + FOREIGN KEY ("qCareAssistant") REFERENCES [qCareAssistant](id), + FOREIGN KEY ("qLegalStatus") REFERENCES [qLegalStatus](id)) diff --git a/setup.py b/setup.py index b6c3809..35f2e81 100644 --- a/setup.py +++ b/setup.py @@ -2,7 +2,7 @@ from setuptools import setup, find_packages import io import os -VERSION = "0.2" +VERSION = "0.3" def get_long_description(): diff --git a/sqlite_utils/db.py b/sqlite_utils/db.py index e3e83a7..0ceb7a8 100644 --- a/sqlite_utils/db.py +++ b/sqlite_utils/db.py @@ -104,6 +104,12 @@ class Table: ) return fks + @property + def schema(self): + return self.db.conn.execute( + "select sql from sqlite_master where name = ?", (self.name,) + ).fetchone()[0] + def create(self, columns, pk=None, foreign_keys=None): columns = {name: value for (name, value) in columns.items()} self.db.create_table(self.name, columns, pk=pk, foreign_keys=foreign_keys)