^ Initial Steps

project-folder               structure and location of XML meta-program
  | ....
  |- sdm                     SDM folder (any path, any name)
      |--- go.dal            root-file: an empty file named as 'php.dal', 'java.dal', 'cpp.dal', 'python.dal', or 'go.dal' (ensure lower case)
      |--- sdm.xml           declarations of DTO/model and/or DAO classes
      |--- settings.xml      common settings
      |--- sdm.xsd           ------ XSD-files for XML code completion and parsing
      |--- settings.xsd      ------
      |--- dao.xsd           ------
      |--- ProjectsDao.xml   external XML files as an option to declare DAO classes
  | ...
  | - .sdm                   config file of SDM sidebar tool-button (JetBrains only, none in Eclipse)

1. Create/Open an SDM folder
2. Create/Open (double-click) a root-file to enter the Plug-in GUI, switch to "Admin"
3. Create XSD files, "sdm.xml", and "settings.xml"
4. Click "settings.xml" to start editing. Read and follow the notes in XML comments. Save the changes.
5. One of the buttons marked as [x] may be a good starting point. See also the Demo Projects

The content of ".sdm" file:

# more than one "*.dal" file in the same project is ok

sdm/go.dal              # path-name of the root-file from example above

sdm/sdm.xml             # add more files from SDM folder for quick access
sdm/settings.xml

src/my_favorite.php     # the others are ok as well

^ settings.xml -> examples of JDBC settings

^ settings.xml -> type-map

Here you specify how the types detected by code generator are rendered in the target code.

<type-map default="">
    <type detected="java.lang.Integer" target="int64">
    <type detected="java.lang.Double" target="float64">
    <type detected="java.lang.Float" target="float64">
    <type detected="java.lang.String" target="string">
    <type detected="byte[]" target="[]byte"/>
    <type detected="java.lang.Object" target="interface{}"/>
</type-map>

Algorithm of processing is the following:

1. if detected type is found among 'detected', then related 'target' is rendered
2. if not, then 'default' is rendered
3. if 'default' is empty, detected type is rendered as-is.

If you want to create "type-map" from zero, read this: misc.html#type-map.

if you need more strong typing in generated DAO classes, read this: misc.html#strong-typing.

There may be some nuances depending on database/driver.

Example 1. MySQL JDBC driver detects all field types correctly. At the same time, MySQL divers for Go fetch all values as []uint8:

Example 2. Oracle JDBC driver detects all numerics as "java.math.BigDecimal". At the same time, Go + "github.com/godror/godror" fetches all numerics as strings:

Example 3. For Java + Android + SQLite, you may need this:

<type-map default="">
    <!-- On Dev. PC, it is Integer, but in Android run-time it is Long -->
    <type detected="java.lang.Integer" target="java.lang.Long"/>
</type-map>

Example 4. JDBC driver for SQLite3 detects date/time as "java.lang.String" or "java.lang.Object", but it happens that Go + "github.com/mattn/go-sqlite3" fetches date/time as "time:time.Time".
In such cases, 'type-map' may be not working, and you need explicit declarations:

<dto-class name="Orders" ref="get_orders.sql">
    <field type="time:time.Time" column="o_date"/>
</dto-class>

^ settings.xml -> macros

To generate complex fields like in example below

class Task(Base):
    __tablename__ = 'tasks'

    t_id = Column('t_id', Integer, primary_key=True, autoincrement=True)
    g_id = Column('g_id', Integer, ForeignKey('groups.g_id'))
    t_priority = Column('t_priority', Integer)
    t_date = Column('t_date', String(65535))
    t_subject = Column('t_subject', String(65535))
    t_comments = Column('t_comments', String(65535))

you will need to extend the section "settings.xml" => <macros> and use related references in "settings.xml" => <type-map><type ... target="...:

<type-map default="">
    <type detected="sa-java.lang.Integer" target="${sa-type}|0:Integer"/>
    <type detected="sa-java.lang.Float" target="${sa-type}|0:Float"/>
    <type detected="sa-java.lang.String" target="${sa-type}|0:String"/>
    <type detected="sa-byte[]" target="${sa-type}|0:LargeBinary"/>
    <type detected="sa-java.lang.Object" target="${sa-type-unknown}"/>
type-map>

<macros>
    <macro name="${sa-type-unknown}" value="${sa-column-base}|type:"/>

    <macro name="${sa-type}" value="${sa-column-base}|type:, ${0}"/>

    <macro name="${sa-column-base}"/>
            <vm/>
                <![CDATA[= Column('${column}'${type}#if($fi.ColumnSize>0)($fi.ColumnSize)#end#if($fi.FK), ForeignKey('$fi.FK')#end
#if($fi.PK), primary_key=True#end
#if($fi.AI), autoincrement=True#end
#if(!$fi.PK)
#if($fi.Indexed), index=True#end
#if($fi.Unique), unique=True#end
#if($fi.Nullable), nullable=True#end
#end)${comment}]]/>
            </vm/>
    </macro/>
macros>

Examples of the field-related macros are available in plug-in GUI => tab "Admin" => [X] and in Demo-Projects: https://github.com/panedrone/sqldalmaker

To customize class-based macros, use this:

• refs to entries of section <macros>:

  <dto scope="" inheritance="" field-names-mode="0" macro="${dto}"/>
  <dao scope="" field-assign-mode="0" macro="${dao}"/>

• refs to external files:

  <dto scope="" inheritance="" field-names-mode="0" macro="sdm/python.models.vm"/>
  <dao scope="" field-assign-mode="0" macro="sdm/python.dao.vm"/>

^ Areas of Responsibility

• Generated Code is free of direct calls to an underlying DB-accessing API (PDO, JDBC, QtSql, etc.)
• All low level stuff is wrapped into a Proxy class
• Meaningful functionality of Proxy class it exposed with an interface DataStore
• Generated Code is based on DataStore which makes it is minimalistic and well readable.

Example below is to demonstrate how to organize it in Golang:

• Proxy and DataStore: https://github.com/panedrone/sdm_todolist_go_react_vue_npm_sqlite3/blob/master/sqlx/dbal/data_store_sqlx.go
• Usage in Generated Code: https://github.com/panedrone/sdm_todolist_go_react_vue_npm_sqlite3/blob/master/sqlx/dbal/projects_dao.go

For more examples, refer Demo-Projects and the plugin GUI, tab 'Admin'.