sql Module

This file is part of the web2py Web Framework
Developed by Massimo Di Pierro <mdipierro@cs.depaul.edu>,
limodou <limodou@gmail.com> and srackham <srackham@gmail.com>.

Just for backward compatibility

classgluon.sql.DAL(uri='sqlite://dummy.db',pool_size=0,folder=None,db_codec='UTF-8',check_reserved=None,migrate=True,fake_migrate=False,migrate_enabled=True,fake_migrate_all=False,decode_credentials=False,driver_args=None,adapter_args=None,attempts=5,auto_import=False,bigint_id=False,debug=False,lazy_tables=False,db_uid=None,do_connect=True,after_connection=None,tables=None,ignore_field_case=True,entity_quoting=False,table_hash=None)[source]

Bases:pydal.helpers.classes.Serializable,pydal.helpers.classes.BasicStorage

An instance of this class represents a database connection

Parameters:
  • uri (str) –

    contains information for connecting to a database.Defaults to‘sqlite://dummy.db’

    Note

    experimental: you can specify a dictionary as uriparameter i.e. with:

    db=DAL({"uri":"sqlite://storage.sqlite","tables":{...},...})

    for an example of dict input you can check the outputof the scaffolding db model with

    db.as_dict()

    Note that for compatibility with Python older thanversion 2.6.5 you should cast your dict input keysto str due to a syntax limitation on kwarg names.for proper DAL dictionary input you can use one of:

    obj=serializers.cast_keys(dict,[encoding="utf-8"])#or else (for parsing json input)obj=serializers.loads_json(data,unicode_keys=False)
  • pool_size – How many open connections to make to the database object.
  • folder – where .table files will be created. Automatically set withinweb2py. Use an explicit path when using DAL outside web2py
  • db_codec – string encoding of the database (default: ‘UTF-8’)
  • table_hash – database identifier with .tables. If your connection hashchange you can still using old .tables if they have db_hashas prefix
  • check_reserved –

    list of adapters to check tablenames and column namesagainst sql/nosql reserved keywords. Defaults toNone

    • ’common’ List of sql keywords that are common to all databasetypes such as “SELECT, INSERT”. (recommended)
    • ’all’ Checks against all known SQL keywords
    • ’<adaptername>’’ Checks against the specific adapters list ofkeywords
    • ’<adaptername>_nonreserved’ Checks against the specific adapterslist of nonreserved keywords. (if available)
  • migrate – sets default migrate behavior for all tables
  • fake_migrate – sets default fake_migrate behavior for all tables
  • migrate_enabled – If set to False disables ALL migrations
  • fake_migrate_all – If set to True fake migrates ALL tables
  • attempts – Number of times to attempt connecting
  • auto_import – If set to True, tries import automatically tabledefinitions from the databases folder (works only for simple models)
  • bigint_id – If set, turn on bigint instead of int for id and referencefields
  • lazy_tables – delays table definition until table access
  • after_connection – can a callable that will be executed after theconnection

Example

Use as:

db=DAL('sqlite://test.db')

or:

db=DAL(**{"uri":...,"tables":[...]...})# experimentaldb.define_table('tablename',Field('fieldname1'),Field('fieldname2'))
classField(fieldname,type='string',length=None,default=<function <lambda>>,required=False,requires=<function <lambda>>,ondelete='CASCADE',notnull=False,unique=False,uploadfield=True,widget=None,label=None,comment=None,writable=True,readable=True,update=None,authorize=None,autodelete=False,represent=None,uploadfolder=None,uploadseparate=False,uploadfs=None,compute=None,custom_store=None,custom_retrieve=None,custom_retrieve_file_properties=None,custom_delete=None,filter_in=None,filter_out=None,custom_qualifier=None,map_none=None,rname=None)

Bases:pydal.objects.Expression,pydal.helpers.classes.Serializable

Lazy

alias ofFieldMethod

Method

alias ofFieldMethod

Virtual

alias ofFieldVirtual

as_dict(flat=False,sanitize=True)
clone(point_self_references_to=False,**args)
count(distinct=None)
formatter(value)
retrieve(name,path=None,nameonly=False)

Ifnameonly==True return (filename, fullfilename) instead of(filename, stream)

retrieve_file_properties(name,path=None)
set_attributes(*args,**attributes)
sqlsafe
sqlsafe_name
store(file,filename=None,path=None)
validate(value)
classRow(*args,**kwargs)

Bases:pydal.helpers.classes.BasicStorage

A dictionary that lets you do d[‘a’] as well as d.athis is only used to store aRow

as_dict(datetime_to_str=False,custom_types=None)
as_json(mode='object',default=None,colnames=None,serialize=True,**kwargs)

serializes the row to a JSON objectkwargs are passed to .as_dict methodonly “object” mode supported

serialize = False used by Rows.as_json

TODO: return array mode with query column order

mode and colnames are not implemented

as_xml(row_name='row',colnames=None,indent=' ')
get(key,default=None)
classTable(db,tablename,*fields,**args)

Bases:pydal.helpers.classes.Serializable,pydal.helpers.classes.BasicStorage

Represents a database table

Example::
You can create a table as::
db = DAL(…)db.define_table(‘users’, Field(‘name’))

And then:

db.users.insert(name='me')# print db.users._insert(...) to see SQLdb.users.drop()
as_dict(flat=False,sanitize=True)
bulk_insert(items)

here items is a list of dictionaries

drop(mode='')
fields
import_from_csv_file(csvfile,id_map=None,null='<NULL>',unique='uuid',id_offset=None,*args,**kwargs)

Import records from csv file.Column headers must have same names as table fields.Field ‘id’ is ignored.If column names read ‘table.file’ the ‘table.’ prefix is ignored.

  • ‘unique’ argument is a field which must be unique (typically auuid field)
  • ‘restore’ argument is default False; if set True will remove old valuesin table first.
  • ‘id_map’ if set to None will not map ids

The import will keep the id numbers in the restored table.This assumes that there is an field of type id that is integer and inincrementing order.Will keep the id numbers in restored table.

insert(**fields)
on(query)
sqlsafe
sqlsafe_alias
truncate(mode=None)
update(*args,**kwargs)
update_or_insert(_key=<function <lambda>>,**values)
validate_and_insert(**fields)
validate_and_update(_key=<function <lambda>>,**fields)
validate_and_update_or_insert(_key=<function <lambda>>,**fields)
with_alias(alias)
as_dict(flat=False,sanitize=True)[source]
can_join()[source]
check_reserved_keyword(name)[source]

Validatesname against SQL keywordsUses self.check_reserve which is a list of operators to use.

close()[source]
commit()[source]
define_table(tablename,*fields,**args)[source]
staticdistributed_transaction_begin(*instances)[source]
staticdistributed_transaction_commit(*instances)[source]
executesql(query,placeholders=None,as_dict=False,fields=None,colnames=None,as_ordered_dict=False)[source]

Executes an arbitrary query

Parameters:
  • query (str) – the query to submit to the backend
  • placeholders – is optional and will always be None.If using raw SQL with placeholders, placeholders may bea sequence of values to be substituted inor, (if supported by the DB driver), a dictionary with keysmatching named placeholders in your SQL.
  • as_dict – will always be None when using DAL.If using raw SQL can be set to True and the results cursorreturned by the DB driver will be converted to a sequence ofdictionaries keyed with the db field names. Results returnedwith as_dict=True are the same as those returned when applying.to_list() to a DAL query. If “as_ordered_dict”=True thebehaviour is the same as when “as_dict”=True with the keys(field names) guaranteed to be in the same order as returnedby the select name executed on the database.
  • fields –

    list of DAL Fields that match the fields returned from theDB. The Field objects should be part of one or more Tableobjects defined on the DAL object. The “fields” list can includeone or more DAL Table objects in addition to or instead ofincluding Field objects, or it can be just a single table(not in a list). In that case, the Field objects will beextracted from the table(s).

    Note

    if eitherfields orcolnames is provided, the resultswill be converted to a DALRows object using thedb._adapter.parse() method

  • colnames – list of field names in tablename.fieldname format

Note

It is also possible to specify both “fields” and the associated“colnames”. In that case, “fields” can also include DAL Expressionobjects in addition to Field objects. For Field objects in “fields”,the associated “colnames” must still be in tablename.fieldnameformat. For Expression objects in “fields”, the associated“colnames” can be any arbitrary labels.

DAL Table objects referred to by “fields” or “colnames” can be dummytables and do not have to represent any real tables in the database.Also, note that the “fields” and “colnames” must be in thesame order as the fields in the results cursor returned from the DB.

export_to_csv_file(ofile,*args,**kwargs)[source]
staticget_instances()[source]

Returns a dictionary with uri as key with timings and defined tables:

{'sqlite://storage.sqlite':{'dbstats':[(selectauth_user.emailfromauth_user,0.02009)],'dbtables':{'defined':['auth_cas','auth_event','auth_group','auth_membership','auth_permission','auth_user'],'lazy':'[]'}}}
has_representer(name)[source]
import_from_csv_file(ifile,id_map=None,null='<NULL>',unique='uuid',map_tablenames=None,ignore_missing_tables=False,*args,**kwargs)[source]
import_table_definitions(path,migrate=False,fake_migrate=False,tables=None)[source]
lazy_define_table(tablename,*fields,**args)[source]
logger = <logging.Logger object>
parse_as_rest(patterns,args,vars,queries=None,nested_select=True)[source]

Example

Use as:

db.define_table('person',Field('name'),Field('info'))db.define_table('pet',Field('ownedby',db.person),Field('name'),Field('info'))@request.restful()defindex():defGET(*args,**vars):patterns=["/friends[person]","/{person.name}/:field","/{person.name}/pets[pet.ownedby]","/{person.name}/pets[pet.ownedby]/{pet.name}","/{person.name}/pets[pet.ownedby]/{pet.name}/:field",("/dogs[pet]",db.pet.info=='dog'),("/dogs[pet]/{pet.name.startswith}",db.pet.info=='dog'),]parser=db.parse_as_rest(patterns,args,vars)ifparser.status==200:returndict(content=parser.response)else:raiseHTTP(parser.status,parser.error)defPOST(table_name,**vars):iftable_name=='person':returndb.person.validate_and_insert(**vars)eliftable_name=='pet':returndb.pet.validate_and_insert(**vars)else:raiseHTTP(400)returnlocals()
represent(name,*args,**kwargs)[source]
representers = {'rows_render': <function represent at 0x7ff70774eb18>, 'rows_xml': <class 'gluon.sqlhtml.SQLTABLE'>}
rollback()[source]
serializers = {'json': <function custom_json at 0x7ff7079ec488>, 'xml': <function xml at 0x7ff7079ec578>}
staticset_folder(folder)[source]
smart_query(fields,text)[source]
tables
uuid()
validators = None
validators_method(field)

Field type validation, using web2py’s validators mechanism.

makes sure the content of a field is in line with the declaredfieldtype

where(query=None,ignore_common_filters=None)[source]
classgluon.sql.Field(fieldname,type='string',length=None,default=<function <lambda>>,required=False,requires=<function <lambda>>,ondelete='CASCADE',notnull=False,unique=False,uploadfield=True,widget=None,label=None,comment=None,writable=True,readable=True,update=None,authorize=None,autodelete=False,represent=None,uploadfolder=None,uploadseparate=False,uploadfs=None,compute=None,custom_store=None,custom_retrieve=None,custom_retrieve_file_properties=None,custom_delete=None,filter_in=None,filter_out=None,custom_qualifier=None,map_none=None,rname=None)[source]

Bases:pydal.objects.Expression,pydal.helpers.classes.Serializable

Lazy

Represents a database field

Example

Usage:

a=Field(name,'string',length=32,default=None,required=False,requires=IS_NOT_EMPTY(),ondelete='CASCADE',notnull=False,unique=False,uploadfield=True,widget=None,label=None,comment=None,uploadfield=True,# True means store on disk,# 'a_field_name' means store in this field in db# False means file content will be discarded.writable=True,readable=True,update=None,authorize=None,autodelete=False,represent=None,uploadfolder=None,uploadseparate=False# upload to separate directories by uuid_keys# first 2 character and tablename.fieldname# False - old behavior# True - put uploaded file in#   <uploaddir>/<tablename>.<fieldname>/uuid_key[:2]#        directory)uploadfs=None# a pyfilesystem where to store upload)

to be used as argument ofDAL.define_table

alias ofFieldMethod

Method

alias ofFieldMethod

Virtual

alias ofFieldVirtual

as_dict(flat=False,sanitize=True)[source]
clone(point_self_references_to=False,**args)[source]
count(distinct=None)[source]
formatter(value)[source]
retrieve(name,path=None,nameonly=False)[source]

Ifnameonly==True return (filename, fullfilename) instead of(filename, stream)

retrieve_file_properties(name,path=None)[source]
set_attributes(*args,**attributes)[source]
sqlsafe
sqlsafe_name
store(file,filename=None,path=None)[source]
validate(value)[source]